Class: RatatuiRuby::Text::Span

Inherits:
Object
  • Object
show all
Defined in:
lib/ratatui_ruby/text/span.rb

Overview

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]))

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(content:, style: nil) ⇒ Span

Creates a new Span.

content

String.

style

Style object (optional).



34
35
36
 
# File 'lib/ratatui_ruby/text/span.rb', line 34

def initialize(content:, style: nil)
  super
end

Class Method Details

.raw(content) ⇒ Object

Creates a span with the default style.

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

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

span = Text::Span.raw("test content")
span.content  # => "test content"
span.style    # => nil

– SPDX-SnippetEnd ++

content

String.

Returns: Span.



94
95
96
 
# File 'lib/ratatui_ruby/text/span.rb', line 94

def self.raw(content)
  new(content:)
end

.styled(content, style = nil) ⇒ Object

Concise helper for styling.

Example

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



43
44
45
 
# File 'lib/ratatui_ruby/text/span.rb', line 43

def self.styled(content, style = nil)
  new(content:, style:)
end

Instance Method Details

#patch_style(patch) ⇒ Object

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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)

– SPDX-SnippetEnd ++

patch

Style::Style to merge.

Returns: Span.



122
123
124
125
126
127
128
129
130
131
132
 
# 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

#reset_style ⇒ Object

Resets the style of the span.

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

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++ Returns: Span.



153
154
155
 
# File 'lib/ratatui_ruby/text/span.rb', line 153

def reset_style
  with(style: nil)
end

#width ⇒ Object

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

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

– SPDX-SnippetEnd ++ Returns: Integer.



69
70
71
 
# File 'lib/ratatui_ruby/text/span.rb', line 69

def width
  RatatuiRuby::Text.width(content.to_s)
end