Class: Tuile::StyledString::Style

Inherits:
Object
  • Object
show all
Defined in:
lib/tuile/styled_string.rb

Overview

A frozen value type describing the visual style of a Span.

‘fg` and `bg` accept:

  • ‘nil` — the terminal default (SGR 39 / 49)

  • a symbol from COLOR_SYMBOLS — 8 standard + 8 bright ANSI colors

  • an Integer 0..255 — 256-color palette index (SGR 38;5;N / 48;5;N)

  • an ‘[r, g, b]` Array of three 0..255 Integers — 24-bit RGB

Constant Summary collapse

COLOR_SYMBOLS =

Symbolic color names recognized by #fg and #bg. Order is significant: indices 0..7 map to standard ANSI colors (SGR 30..37 fg / 40..47 bg); indices 8..15 map to bright variants (SGR 90..97 / 100..107).

Returns:

  • (Array<Symbol>) 
%i[
  black red green yellow blue magenta cyan white
  bright_black bright_red bright_green bright_yellow
  bright_blue bright_magenta bright_cyan bright_white
].freeze
DEFAULT =

The style with no color and no attributes — what the terminal shows without any SGR applied.

Returns:

new

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#bg ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol, Integer, Array<Integer>, nil) 


74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/tuile/styled_string.rb', line 74

class Style < Data.define(:fg, :bg, :bold, :italic, :underline)
  # Symbolic color names recognized by {#fg} and {#bg}. Order is
  # significant: indices 0..7 map to standard ANSI colors (SGR 30..37 fg
  # / 40..47 bg); indices 8..15 map to bright variants (SGR 90..97 /
  # 100..107).
  # @return [Array<Symbol>]
  COLOR_SYMBOLS = %i[
    black red green yellow blue magenta cyan white
    bright_black bright_red bright_green bright_yellow
    bright_blue bright_magenta bright_cyan bright_white
  ].freeze

  # @param fg [Symbol, Integer, Array<Integer>, nil]
  # @param bg [Symbol, Integer, Array<Integer>, nil]
  # @param bold [Boolean]
  # @param italic [Boolean]
  # @param underline [Boolean]
  # @return [Style]
  # @raise [ArgumentError] when a color is not one of the accepted forms.
  def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false)
    validate_color!(fg, :fg)
    validate_color!(bg, :bg)
    super(fg:, bg:, bold:, italic:, underline:)
  end

  # @param color [Object]
  # @param which [Symbol]
  # @return [void]
  def self.validate_color!(color, which)
    return if color.nil? || COLOR_SYMBOLS.include?(color)
    return if color.is_a?(Integer) && color.between?(0, 255)
    return if color.is_a?(Array) && color.length == 3 &&
              color.all? { |v| v.is_a?(Integer) && v.between?(0, 255) }

    raise ArgumentError, "invalid #{which} color: #{color.inspect}"
  end
  private_class_method :validate_color!

  # The style with no color and no attributes — what the terminal shows
  # without any SGR applied.
  # @return [Style]
  DEFAULT = new

  # @return [Boolean]
  def default? = self == DEFAULT

  # Returns a new {Style} with the given attributes overridden.
  # @param overrides [Hash{Symbol => Object}]
  # @return [Style]
  def merge(**overrides) = self.class.new(**to_h.merge(overrides))
end

#bold ⇒ Boolean (readonly)

Returns:

  • (Boolean) 


74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/tuile/styled_string.rb', line 74

class Style < Data.define(:fg, :bg, :bold, :italic, :underline)
  # Symbolic color names recognized by {#fg} and {#bg}. Order is
  # significant: indices 0..7 map to standard ANSI colors (SGR 30..37 fg
  # / 40..47 bg); indices 8..15 map to bright variants (SGR 90..97 /
  # 100..107).
  # @return [Array<Symbol>]
  COLOR_SYMBOLS = %i[
    black red green yellow blue magenta cyan white
    bright_black bright_red bright_green bright_yellow
    bright_blue bright_magenta bright_cyan bright_white
  ].freeze

  # @param fg [Symbol, Integer, Array<Integer>, nil]
  # @param bg [Symbol, Integer, Array<Integer>, nil]
  # @param bold [Boolean]
  # @param italic [Boolean]
  # @param underline [Boolean]
  # @return [Style]
  # @raise [ArgumentError] when a color is not one of the accepted forms.
  def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false)
    validate_color!(fg, :fg)
    validate_color!(bg, :bg)
    super(fg:, bg:, bold:, italic:, underline:)
  end

  # @param color [Object]
  # @param which [Symbol]
  # @return [void]
  def self.validate_color!(color, which)
    return if color.nil? || COLOR_SYMBOLS.include?(color)
    return if color.is_a?(Integer) && color.between?(0, 255)
    return if color.is_a?(Array) && color.length == 3 &&
              color.all? { |v| v.is_a?(Integer) && v.between?(0, 255) }

    raise ArgumentError, "invalid #{which} color: #{color.inspect}"
  end
  private_class_method :validate_color!

  # The style with no color and no attributes — what the terminal shows
  # without any SGR applied.
  # @return [Style]
  DEFAULT = new

  # @return [Boolean]
  def default? = self == DEFAULT

  # Returns a new {Style} with the given attributes overridden.
  # @param overrides [Hash{Symbol => Object}]
  # @return [Style]
  def merge(**overrides) = self.class.new(**to_h.merge(overrides))
end

#fg ⇒ Symbol, ... (readonly)

Returns:

  • (Symbol, Integer, Array<Integer>, nil) 


74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/tuile/styled_string.rb', line 74

class Style < Data.define(:fg, :bg, :bold, :italic, :underline)
  # Symbolic color names recognized by {#fg} and {#bg}. Order is
  # significant: indices 0..7 map to standard ANSI colors (SGR 30..37 fg
  # / 40..47 bg); indices 8..15 map to bright variants (SGR 90..97 /
  # 100..107).
  # @return [Array<Symbol>]
  COLOR_SYMBOLS = %i[
    black red green yellow blue magenta cyan white
    bright_black bright_red bright_green bright_yellow
    bright_blue bright_magenta bright_cyan bright_white
  ].freeze

  # @param fg [Symbol, Integer, Array<Integer>, nil]
  # @param bg [Symbol, Integer, Array<Integer>, nil]
  # @param bold [Boolean]
  # @param italic [Boolean]
  # @param underline [Boolean]
  # @return [Style]
  # @raise [ArgumentError] when a color is not one of the accepted forms.
  def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false)
    validate_color!(fg, :fg)
    validate_color!(bg, :bg)
    super(fg:, bg:, bold:, italic:, underline:)
  end

  # @param color [Object]
  # @param which [Symbol]
  # @return [void]
  def self.validate_color!(color, which)
    return if color.nil? || COLOR_SYMBOLS.include?(color)
    return if color.is_a?(Integer) && color.between?(0, 255)
    return if color.is_a?(Array) && color.length == 3 &&
              color.all? { |v| v.is_a?(Integer) && v.between?(0, 255) }

    raise ArgumentError, "invalid #{which} color: #{color.inspect}"
  end
  private_class_method :validate_color!

  # The style with no color and no attributes — what the terminal shows
  # without any SGR applied.
  # @return [Style]
  DEFAULT = new

  # @return [Boolean]
  def default? = self == DEFAULT

  # Returns a new {Style} with the given attributes overridden.
  # @param overrides [Hash{Symbol => Object}]
  # @return [Style]
  def merge(**overrides) = self.class.new(**to_h.merge(overrides))
end

#italic ⇒ Boolean (readonly)

Returns:

  • (Boolean) 


74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/tuile/styled_string.rb', line 74

class Style < Data.define(:fg, :bg, :bold, :italic, :underline)
  # Symbolic color names recognized by {#fg} and {#bg}. Order is
  # significant: indices 0..7 map to standard ANSI colors (SGR 30..37 fg
  # / 40..47 bg); indices 8..15 map to bright variants (SGR 90..97 /
  # 100..107).
  # @return [Array<Symbol>]
  COLOR_SYMBOLS = %i[
    black red green yellow blue magenta cyan white
    bright_black bright_red bright_green bright_yellow
    bright_blue bright_magenta bright_cyan bright_white
  ].freeze

  # @param fg [Symbol, Integer, Array<Integer>, nil]
  # @param bg [Symbol, Integer, Array<Integer>, nil]
  # @param bold [Boolean]
  # @param italic [Boolean]
  # @param underline [Boolean]
  # @return [Style]
  # @raise [ArgumentError] when a color is not one of the accepted forms.
  def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false)
    validate_color!(fg, :fg)
    validate_color!(bg, :bg)
    super(fg:, bg:, bold:, italic:, underline:)
  end

  # @param color [Object]
  # @param which [Symbol]
  # @return [void]
  def self.validate_color!(color, which)
    return if color.nil? || COLOR_SYMBOLS.include?(color)
    return if color.is_a?(Integer) && color.between?(0, 255)
    return if color.is_a?(Array) && color.length == 3 &&
              color.all? { |v| v.is_a?(Integer) && v.between?(0, 255) }

    raise ArgumentError, "invalid #{which} color: #{color.inspect}"
  end
  private_class_method :validate_color!

  # The style with no color and no attributes — what the terminal shows
  # without any SGR applied.
  # @return [Style]
  DEFAULT = new

  # @return [Boolean]
  def default? = self == DEFAULT

  # Returns a new {Style} with the given attributes overridden.
  # @param overrides [Hash{Symbol => Object}]
  # @return [Style]
  def merge(**overrides) = self.class.new(**to_h.merge(overrides))
end

#underline ⇒ Boolean (readonly)

Returns:

  • (Boolean) 


74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/tuile/styled_string.rb', line 74

class Style < Data.define(:fg, :bg, :bold, :italic, :underline)
  # Symbolic color names recognized by {#fg} and {#bg}. Order is
  # significant: indices 0..7 map to standard ANSI colors (SGR 30..37 fg
  # / 40..47 bg); indices 8..15 map to bright variants (SGR 90..97 /
  # 100..107).
  # @return [Array<Symbol>]
  COLOR_SYMBOLS = %i[
    black red green yellow blue magenta cyan white
    bright_black bright_red bright_green bright_yellow
    bright_blue bright_magenta bright_cyan bright_white
  ].freeze

  # @param fg [Symbol, Integer, Array<Integer>, nil]
  # @param bg [Symbol, Integer, Array<Integer>, nil]
  # @param bold [Boolean]
  # @param italic [Boolean]
  # @param underline [Boolean]
  # @return [Style]
  # @raise [ArgumentError] when a color is not one of the accepted forms.
  def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false)
    validate_color!(fg, :fg)
    validate_color!(bg, :bg)
    super(fg:, bg:, bold:, italic:, underline:)
  end

  # @param color [Object]
  # @param which [Symbol]
  # @return [void]
  def self.validate_color!(color, which)
    return if color.nil? || COLOR_SYMBOLS.include?(color)
    return if color.is_a?(Integer) && color.between?(0, 255)
    return if color.is_a?(Array) && color.length == 3 &&
              color.all? { |v| v.is_a?(Integer) && v.between?(0, 255) }

    raise ArgumentError, "invalid #{which} color: #{color.inspect}"
  end
  private_class_method :validate_color!

  # The style with no color and no attributes — what the terminal shows
  # without any SGR applied.
  # @return [Style]
  DEFAULT = new

  # @return [Boolean]
  def default? = self == DEFAULT

  # Returns a new {Style} with the given attributes overridden.
  # @param overrides [Hash{Symbol => Object}]
  # @return [Style]
  def merge(**overrides) = self.class.new(**to_h.merge(overrides))
end

Class Method Details

.new(fg: nil, bg: nil, bold: false, italic: false, underline: false) ⇒ Style

Parameters:

  • fg (Symbol, Integer, Array<Integer>, nil) (defaults to: nil)
  • bg (Symbol, Integer, Array<Integer>, nil) (defaults to: nil)
  • bold (Boolean) (defaults to: false)
  • italic (Boolean) (defaults to: false)
  • underline (Boolean) (defaults to: false)

Returns:

Raises:

  • (ArgumentError) —

    when a color is not one of the accepted forms.



93
94
95
96
97
 
# File 'lib/tuile/styled_string.rb', line 93

def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false)
  validate_color!(fg, :fg)
  validate_color!(bg, :bg)
  super(fg:, bg:, bold:, italic:, underline:)
end

Instance Method Details

#default? ⇒ Boolean

Returns:

  • (Boolean) 


118
 
# File 'lib/tuile/styled_string.rb', line 118

def default? = self == DEFAULT

#merge(**overrides) ⇒ Style

Returns a new Tuile::StyledString::Style with the given attributes overridden.

Parameters:

  • overrides (Hash{Symbol => Object})

Returns:



123
 
# File 'lib/tuile/styled_string.rb', line 123

def merge(**overrides) = self.class.new(**to_h.merge(overrides))