Class: Sai::Decorator

Inherits:
Object
  • Object
show all
Includes:
ColorManipulations, Gradients, HexColors, NamedColors, NamedStyles, RGBColors
Defined in:
lib/sai/decorator.rb,
lib/sai/decorator/delegator.rb,
lib/sai/decorator/gradients.rb,
lib/sai/decorator/hex_colors.rb,
lib/sai/decorator/rgb_colors.rb,
lib/sai/decorator/named_colors.rb,
lib/sai/decorator/named_styles.rb,
lib/sai/decorator/color_manipulations.rb

Overview

Note:

For each named color, two methods are dynamically generated:

  • color_name - Applies the color to the foreground
  • on_color_name - Applies the color to the backgroundAll color methods return Decorator

A decorator for applying ANSI styles and colors to text

Examples:

Using a named color

decorator.blue.decorate('Hello').to_s      #=> "\e[38;2;0;0;238mHello\e[0m"
decorator.on_blue.decorate('Hello').to_s   #=> "\e[48;2;0;0;238mHello\e[0m"

Author:

Since:

  • 0.1.0

Defined Under Namespace

Modules: ColorManipulations, Delegator, Gradients, HexColors, NamedColors, NamedStyles, RGBColors

Instance Method Summary collapse

Constructor Details

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

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.

Initialize a new instance of Decorator

Parameters:

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

    the color mode to use

Author:

Since:

  • 0.1.0



49
50
51
52
53
54
55
56
 
# File 'lib/sai/decorator.rb', line 49

def initialize(mode: Sai.mode.auto)
  @background = nil
  @background_sequence = nil
  @mode = mode
  @foreground = nil
  @foreground_sequence = nil
  @styles = [] #: Array[Symbol]
end

Instance Method Details

Apply the ANSI style "blink" to the text

Examples:

decorator.blink.decorate('Hello, world!').to_s #=> "\e[5mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#bold ⇒ Decorator Originally defined in module NamedStyles

Apply the ANSI style "bold" to the text

Examples:

decorator.bold.decorate('Hello, world!').to_s #=> "\e[1mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#conceal ⇒ Decorator Originally defined in module NamedStyles

Apply the ANSI style "conceal" to the text

Examples:

decorator.conceal.decorate('Hello, world!').to_s #=> "\e[8mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#darken_background(amount) ⇒ Decorator Also known as: darken_bg Originally defined in module ColorManipulations

Darken the background color by a percentage

Examples:

decorator.on_blue.darken_text(0.5).decorate('Hello, world!').to_s #=> "\e[48;2;0;0;238mHello, world!\e[0m"

Parameters:

  • amount (Float) —

    the amount to darken the background color (0.0...1.0)

Returns:

  • (Decorator) —

    a new instance of Decorator with the darkened background color

Raises:

  • (ArgumentError) —

    if the percentage is out of range

Author:

Since:

  • 0.3.1

#darken_text(amount) ⇒ Decorator Also known as: darken_fg, darken_foreground Originally defined in module ColorManipulations

Darken the text color by a percentage

Examples:

decorator.blue.darken_text(0.5).decorate('Hello, world!').to_s #=> "\e[38;2;0;0;119mHello, world!\e[0m"

Parameters:

  • amount (Float) —

    the amount to darken the text color (0.0...1.0)

Returns:

  • (Decorator) —

    a new instance of Decorator with the darkened text color

Raises:

  • (ArgumentError) —

    if the percentage is out of range

Author:

Since:

  • 0.3.1

#decorate(text) ⇒ ANSI::SequencedString Also known as: apply, call, encode

Apply the styles and colors to the text

Examples:

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

Parameters:

  • text (String) —

    the text to decorate

Returns:

Author:

Since:

  • 0.1.0



72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/sai/decorator.rb', line 72

def decorate(text)
  return ANSI::SequencedString.new(text) unless should_decorate?
  return apply_sequence_gradient(text) if @foreground_sequence || @background_sequence

  sequences = [
    @foreground && Conversion::ColorSequence.resolve(@foreground, @mode),
    @background && Conversion::ColorSequence.resolve(@background, @mode, :background),
    style_sequences.join
  ].compact.join

  ANSI::SequencedString.new("#{sequences}#{text}#{ANSI::RESET}")
end

#dim ⇒ Decorator Originally defined in module NamedStyles

Apply the ANSI style "dim" to the text

Examples:

decorator.dim.decorate('Hello, world!').to_s #=> "\e[2mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#gradient(start_color, end_color, steps) ⇒ Decorator Originally defined in module Gradients

Build a foreground gradient between two colors for text decoration

Examples:

Create a foreground gradient from red to blue

decorator.gradient(:red, :blue, 10).decorate('Hello, World!')
#=> "\e[38;2;255;0;0mH\e[0m\e[38;2;204;0;51me\e[0m..."

Parameters:

  • start_color (Array<Integer>, String, Symbol) —

    the starting color

  • end_color (Array<Integer>, String, Symbol) —

    the ending color

  • steps (Integer) —

    the number of gradient steps (minimum 2)

Returns:

  • (Decorator) —

    a new instance of Decorator with foreground gradient colors

Raises:

  • (ArgumentError) —

    if steps is less than 2

Author:

Since:

  • 0.3.1

#hex(code) ⇒ Decorator Originally defined in module HexColors

Apply a hexadecimal color to the foreground

Examples:

decorator.hex("#EB4133").decorate('Hello, world!').to_s #=> "\e[38;2;235;65;51mHello, world!\e[0m"

Parameters:

  • code (String) —

    the hex color code

Returns:

  • (Decorator) —

    a new instance of Decorator with the hex color applied

Raises:

  • (ArgumentError) —

    if the hex code is invalid

Author:

Since:

  • 0.1.0

#italic ⇒ Decorator Originally defined in module NamedStyles

Apply the ANSI style "italic" to the text

Examples:

decorator.italic.decorate('Hello, world!').to_s #=> "\e[3mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#lighten_background(amount) ⇒ Decorator Also known as: lighten_bg Originally defined in module ColorManipulations

Lighten the background color by a percentage

Examples:

decorator.on_blue.lighten_background(0.5).decorate('Hello, world!').to_s
#=> "\e[48;2;0;0;255mHello, world!\e[0m"

Parameters:

  • amount (Float) —

    the amount to lighten the background color (0.0...1.0)

Returns:

  • (Decorator) —

    a new instance of Decorator with the lightened background color

Raises:

  • (ArgumentError) —

    if the percentage is out of range

Author:

Since:

  • 0.3.1

#lighten_text(amount) ⇒ Decorator Also known as: lighten_fg, lighten_foreground Originally defined in module ColorManipulations

Lighten the text color by a percentage

Examples:

decorator.blue.lighten_text(0.5).decorate('Hello, world!').to_s #=> "\e[38;2;0;0;127mHello, world!\e[0m"

Parameters:

  • amount (Float) —

    the amount to lighten the text color (0.0...1.0)

Returns:

  • (Decorator) —

    a new instance of Decorator with the lightened text color

Raises:

  • (ArgumentError) —

    if the percentage is out of range

Author:

Since:

  • 0.3.1

#no_blink ⇒ Decorator Originally defined in module NamedStyles

Remove the ANSI style "blink" from the text

Examples:

decorator.no_blink.decorate('Hello, world!').to_s #=> "\e[25mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#no_conceal ⇒ Decorator Originally defined in module NamedStyles

Remove the ANSI style "conceal" from the text

Examples:

decorator.no_conceal.decorate('Hello, world!').to_s #=> "\e[28mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#no_italic ⇒ Decorator Originally defined in module NamedStyles

Remove the ANSI style "italic" from the text

Examples:

decorator.no_italic.decorate('Hello, world!').to_s #=> "\e[23mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#no_reverse ⇒ Decorator Originally defined in module NamedStyles

Remove the ANSI style "reverse" from the text

Examples:

decorator.no_reverse.decorate('Hello, world!').to_s #=> "\e[27mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#no_strike ⇒ Decorator Originally defined in module NamedStyles

Remove the ANSI style "strike" from the text

Examples:

decorator.no_strike.decorate('Hello, world!').to_s #=> "\e[29mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#no_underline ⇒ Decorator Originally defined in module NamedStyles

Remove the ANSI style "underline" from the text

Examples:

decorator.no_underline.decorate('Hello, world!').to_s #=> "\e[24mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#normal_intensity ⇒ Decorator Originally defined in module NamedStyles

Remove any intensity styles (bold or dim) from the text

Examples:

decorator.normal_intensity.decorate('Hello, world!').to_s #=> "\e[22mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#on_gradient(start_color, end_color, steps) ⇒ Decorator Originally defined in module Gradients

Build a background gradient between two colors for text decoration

Examples:

Create a background gradient from red to blue

decorator.on_gradient(:red, :blue, 10).decorate('Hello, World!')
#=> "\e[48;2;255;0;0mH\e[0m\e[48;2;204;0;51me\e[0m..."

Parameters:

  • start_color (Array<Integer>, String, Symbol) —

    the starting color

  • end_color (Array<Integer>, String, Symbol) —

    the ending color

  • steps (Integer) —

    the number of gradient steps (minimum 2)

Returns:

  • (Decorator) —

    a new instance of Decorator with background gradient colors

Raises:

  • (ArgumentError) —

    if steps is less than 2

Author:

Since:

  • 0.3.1

#on_hex(code) ⇒ Decorator Originally defined in module HexColors

Apply a hexadecimal color to the background

Examples:

decorator.on_hex("#EB4133").decorate('Hello, world!').to_s #=> "\e[48;2;235;65;51mHello, world!\e[0m"

Parameters:

  • code (String) —

    the hex color code

Returns:

  • (Decorator) —

    a new instance of Decorator with the hex color applied

Raises:

  • (ArgumentError) —

    if the hex code is invalid

Author:

Since:

  • 0.1.0

#on_rainbow(steps) ⇒ Decorator Originally defined in module Gradients

Build a background rainbow gradient for text decoration

Examples:

Create a rainbow background gradient

decorator.on_rainbow(6).decorate('Hello, World!')
#=> "\e[48;2;255;0;0mH\e[0m\e[48;2;255;255;0me\e[0m..."

Parameters:

  • steps (Integer) —

    the number of colors to generate (minimum 2)

Returns:

  • (Decorator) —

    a new instance of Decorator with background rainbow colors

Raises:

  • (ArgumentError) —

    if steps is less than 2

Author:

Since:

  • 0.3.1

#on_rgb(red, green, blue) ⇒ Decorator Originally defined in module RGBColors

Apply an RGB color to the background

Examples:

decorator.on_rgb(235, 65, 51).decorate('Hello, world!').to_s #=> "\e[48;2;235;65;51mHello, world!\e[0m"

Parameters:

  • red (Integer) —

    the red component

  • green (Integer) —

    the green component

  • blue (Integer) —

    the blue component

Returns:

  • (Decorator) —

    a new instance of Decorator with the RGB color applied

Raises:

  • (ArgumentError) —

    if the RGB values are out of range

Author:

Since:

  • 0.1.0

#rainbow(steps) ⇒ Decorator Originally defined in module Gradients

Build a foreground rainbow gradient for text decoration

Examples:

Create a rainbow text gradient

decorator.rainbow(6).decorate('Hello, World!')
#=> "\e[38;2;255;0;0mH\e[0m\e[38;2;255;255;0me\e[0m..."

Parameters:

  • steps (Integer) —

    the number of colors to generate (minimum 2)

Returns:

  • (Decorator) —

    a new instance of Decorator with foreground rainbow colors

Raises:

  • (ArgumentError) —

    if steps is less than 2

Author:

Since:

  • 0.3.1

#rapid_blink ⇒ Decorator Originally defined in module NamedStyles

Apply the ANSI style "rapid_blink" to the text

Examples:

decorator.rapid_blink.decorate('Hello, world!').to_s #=> "\e[6mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#reverse ⇒ Decorator Originally defined in module NamedStyles

Apply the ANSI style "reverse" to the text

Examples:

decorator.reverse.decorate('Hello, world!').to_s #=> "\e[7mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#rgb(red, green, blue) ⇒ Decorator Originally defined in module RGBColors

Apply an RGB color to the foreground

Examples:

decorator.rgb(235, 65, 51).decorate('Hello, world!').to_s #=> "\e[38;2;235;65;51mHello, world!\e[0m"

Parameters:

  • red (Integer) —

    the red component

  • green (Integer) —

    the green component

  • blue (Integer) —

    the blue component

Returns:

  • (Decorator) —

    a new instance of Decorator with the RGB color applied

Raises:

  • (ArgumentError) —

    if the RGB values are out of range

Author:

Since:

  • 0.1.0

#strike ⇒ Decorator Originally defined in module NamedStyles

Apply the ANSI style "strike" to the text

Examples:

decorator.strike.decorate('Hello, world!').to_s #=> "\e[9mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#underline ⇒ Decorator Originally defined in module NamedStyles

Apply the ANSI style "underline" to the text

Examples:

decorator.underline.decorate('Hello, world!').to_s #=> "\e[4mHello, world!\e[0m"

Returns:

  • (Decorator) —

    a new instance of Decorator with the style applied

Author:

Since:

  • 0.1.0

#with_mode(mode) ⇒ Decorator

Apply a specific color mode to the decorator

Examples:

decorator.with_mode(Sai.mode.basic_auto) #=> => #<Sai::Decorator:0x123 @mode=1>

Parameters:

  • mode (Integer) —

    the color mode to use

Returns:

  • (Decorator) —

    a new instance of Decorator with the applied color mode

Author:

Since:

  • 0.2.0



102
103
104
 
# File 'lib/sai/decorator.rb', line 102

def with_mode(mode)
  dup.tap { |duped| duped.instance_variable_set(:@mode, mode) }
end