Module: Sai

Extended by:
Decorator::Delegator
Defined in:
lib/sai.rb,
lib/sai/ansi.rb,
lib/sai/support.rb,
lib/sai/registry.rb,
lib/sai/decorator.rb,
lib/sai/mode_selector.rb,
lib/sai/conversion/rgb.rb,
lib/sai/ansi/color_parser.rb,
lib/sai/ansi/style_parser.rb,
lib/sai/decorator/delegator.rb,
lib/sai/decorator/gradients.rb,
lib/sai/terminal/color_mode.rb,
lib/sai/decorator/hex_colors.rb,
lib/sai/decorator/rgb_colors.rb,
lib/sai/ansi/sequenced_string.rb,
lib/sai/terminal/capabilities.rb,
lib/sai/decorator/named_colors.rb,
lib/sai/decorator/named_styles.rb,
lib/sai/ansi/sequence_processor.rb,
lib/sai/conversion/color_sequence.rb,
lib/sai/conversion/rgb/color_space.rb,
lib/sai/conversion/rgb/color_indexer.rb,
lib/sai/decorator/color_manipulations.rb,
lib/sai/conversion/rgb/color_classifier.rb,
lib/sai/conversion/rgb/color_transformer.rb

Overview

An elegant color management system for crafting sophisticated CLI applications

Sai (彩) - meaning 'coloring' or 'paint' in Japanese - is a powerful and intuitive system for managing color output in command-line applications. Drawing inspiration from traditional Japanese artistic techniques, Sai brings vibrancy and harmony to terminal interfaces through its sophisticated color management

Sai empowers developers to create beautiful, colorful CLI applications that maintain visual consistency across different terminal capabilities. Like its artistic namesake, it combines simplicity and sophistication to bring rich, adaptive color to your terminal interfaces

When included in a class or module, Sai provides the following instance methods:

The Sai module itself responds to all the same methods as Decorator, excluding methods used for applying decorations (apply, call, decorate, encode). These methods are directly delegated to a new Decorator instance

Examples:

Using Sai as a module

class MyClass
  include Sai
end

my_class = MyClass.new
my_class.decorator.red.on_blue.bold.decorate('Hello, World!')
#=> "\e[38;2;205;0;0m\e[48;2;0;0;238m\e[1mHello, World!\e[0m"

my_class.terminal_color_support.true_color? # => true

Using Sai directly

Sai.red.on_blue.bold.decorate('Hello, World!')
#=> "\e[38;2;205;0;0m\e[48;2;0;0;238m\e[1mHello, World!\e[0m"

Sai.support.true_color? # => true

Author:

Since:

  • 0.1.0

Defined Under Namespace

Modules: ANSI, Conversion, ModeSelector, Registry, Support, Terminal Classes: Decorator

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.mode ⇒ ModeSelector

The Sai mode selector

Examples:

Sai.mode.auto #=> 4

Returns:

Author:

Since:

  • 0.2.0



71
72
73
 
# File 'lib/sai.rb', line 71

def mode
  ModeSelector
end

.register(name, rgb_or_hex) ⇒ void

This method returns an undefined value.

Register a custom name and color

Examples:

Register a color

Sai.register(:my_color, '#CF4C5F')
Sai.register(:my_color, [207, 76, 95])

Sai.my_color.decorate('Hello, world!').to_s #=> "\e[38;2;207;76;95mHello, world!\e[0m"

Parameters:

  • name (String, Symbol) —

    the name of the color to register

  • rgb_or_hex (Array<Integer>, String) —

    the RGB values or hex code to register

Author:

Since:

  • 0.3.2



93
94
95
 
# File 'lib/sai.rb', line 93

def register(name, rgb_or_hex)
  Registry.register(name, rgb_or_hex)
end

.sequence(text) ⇒ ANSI::SequencedString

Sequence a string with ANSI escape codes

Examples:

Sequence a string with ANSI escape codes

Sai.sequence("\e[38;2;205;0;0mHello, World!\e[0m") #=> #<Sai::ANSI::SequencedString:0x123>

Parameters:

  • text (String) —

    the text to sequence

Returns:

Author:

Since:

  • 0.3.0



111
112
113
 
# File 'lib/sai.rb', line 111

def sequence(text)
  ANSI::SequencedString.new(text)
end

.support ⇒ Support

The supported color modes for the terminal

Examples:

Check the color support of the terminal

Sai.support.ansi? # => true
Sai.support.basic? # => true
Sai.support.advanced? # => true
Sai.support.no_color? # => false
Sai.support.true_color? # => true

Returns:

Author:

Since:

  • 0.1.0



131
132
133
 
# File 'lib/sai.rb', line 131

def support
  Support
end

.with_mode(mode) ⇒ Decorator Originally defined in module Decorator::Delegator

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Apply a specific color mode to the Sai::Decorator instance

Parameters:

  • mode (Integer) —

    the color mode to use

Returns:

  • (Decorator) —

    a new instance of Decorator with the applied color mode

Author:

Since:

  • 0.4.0

Instance Method Details

#color_mode ⇒ ModeSelector

A helper method that provides Sai color modes

Examples:

class MyClass
  include Sai
end

MyClass.new.color_mode.ansi #=> 2

Returns:

Author:

Since:

  • 0.2.0



172
173
174
 
# File 'lib/sai.rb', line 172

def color_mode
  ModeSelector
end

#decorator(mode: Sai.mode.auto) ⇒ Decorator

A helper method to initialize an instance of Decorator

Examples:

Initialize a new instance of Decorator

class MyClass
  include Sai
end

MyClass.new.decorator.blue.on_red.bold.decorate('Hello, world!')
#=> "\e[38;5;21m\e[48;5;160m\e[1mHello, world!\e[0m"

MyClass.new.decorator(mode: Sai.mode.no_color)
#=> "Hello, world!"

Parameters:

  • mode (Integer) (defaults to: Sai.mode.auto) —

    the color mode to use

Returns:

Author:

Since:

  • 0.1.0



198
199
200
 
# File 'lib/sai.rb', line 198

def decorator(mode: Sai.mode.auto)
  Decorator.new(mode:)
end

#terminal_color_support ⇒ Support

The supported color modes for the terminal

Examples:

Check the color support of the terminal

class MyClass
  include Sai
end

MyClass.new.terminal_color_support.ansi? # => true
MyClass.new.terminal_color_support.basic? # => true
MyClass.new.terminal_color_support.advanced? # => true
MyClass.new.terminal_color_support.no_color? # => false
MyClass.new.terminal_color_support.true_color? # => true

Returns:

Author:

Since:

  • 0.1.0



222
223
224
 
# File 'lib/sai.rb', line 222

def terminal_color_support
  Support
end