class RatatuiRuby::Text::Span

A styled string fragment.

Text is rarely uniform. You need to bold a keyword, colorize an error, or dim a timestamp.

This class attaches style to content. It pairs a string with visual attributes.

combine spans into a {Line} to create rich text.

Examples

Text::Span.new(content: "Error", style: Style.new(fg: :red, modifiers: [:bold]))

Attributes

content [R]

The text content.

style [R]

The style to apply.

Public Class Methods

new (content:, style: nil)

Source

# File lib/ratatui_ruby/text/span.rb, line 34
def initialize(content:, style: nil)
  super
end

Creates a new Span.

content: String.
style: Style object (optional).

Calls superclass method

raw (content)

Source

# File lib/ratatui_ruby/text/span.rb, line 94
def self.raw(content)
  new(content:)
end

Creates a span with the default style.

Use this factory method when you want unstyled text. It mirrors the Ratatui API.

Example

Text::Span.styled("Bold", Style::Style.new(modifiers: [:bold]))

Public Instance Methods

patch_style (patch)

Source

# File lib/ratatui_ruby/text/span.rb, line 122
def patch_style(patch)
  return self if patch.nil?
  return with(style: patch) if style.nil?

  merged = Style::Style.new(
    fg: patch.fg.nil? ? style.fg : patch.fg,
    bg: patch.bg.nil? ? style.bg : patch.bg,
    modifiers: patch.modifiers.empty? ? style.modifiers : (style.modifiers + patch.modifiers).uniq
  )
  with(style: merged)
end

Patches the style of the span, merging modifiers from the given style.

Non-nil values from the patch style override the existing style. Use this when you want to layer styles without replacing the entire style. Colors in the patch take precedence over existing colors. Modifiers are combined.

Example

span = Text::Span.new(content: "test", style: Style::Style.new(fg: :green))
patched = span.patch_style(Style::Style.new(bg: :yellow, modifiers: [:bold]))
patched.style.fg  # => :green (preserved)
patched.style.bg  # => :yellow (added)

patch: Style::Style to merge.

Returns: Span.

reset_style ()

Source

# File lib/ratatui_ruby/text/span.rb, line 153
def reset_style
  with(style: nil)
end

Resets the style of the span.

Returns a new span with no style applied. Use this to strip all styling.

Example

span = Text::Span.new(content: "styled", style: Style::Style.new(fg: :red))
reset = span.reset_style
reset.style  # => nil

Returns: Span.

width ()

Source

# File lib/ratatui_ruby/text/span.rb, line 69
def width
  RatatuiRuby::Text.width(content.to_s)
end

Returns the unicode display width of the content in terminal cells.

CJK characters and emoji count as 2 cells. ASCII characters count as 1 cell. Use this to measure how much horizontal space a span will occupy.

Example

span = Text::Span.new(content: "Hello")
span.width  # => 5

span = Text::Span.new(content: "你好")  # Chinese characters
span.width  # => 4

Returns: Integer.