Class: RatatuiRuby::Text::Line

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

Overview

A sequence of styled spans.

Words form sentences. Spans form lines.

This class composes multiple Span objects into a single horizontal row of text. It handles the layout of rich text fragments within the flow of a paragraph.

Use it to build multi-colored headers, status messages, or log entries.

Examples

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

Text::Line.new(
  spans: [
    Text::Span.styled("User: ", Style.new(modifiers: [:bold])),
    Text::Span.styled("kerrick", Style.new(fg: :blue))
  ]
)

– SPDX-SnippetEnd ++

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(spans: [], alignment: nil, style: nil) ⇒ Line

Creates a new Line.

spans

Array of Span objects (or Strings).

alignment

Symbol (optional).

style

Style object (optional).



57
58
59
 
# File 'lib/ratatui_ruby/text/line.rb', line 57

def initialize(spans: [], alignment: nil, style: nil)
  super
end

Class Method Details

.from_string(content, alignment: nil) ⇒ Object

Creates a simple line from a string.

Text::Line.from_string("Hello")



64
65
66
 
# File 'lib/ratatui_ruby/text/line.rb', line 64

def self.from_string(content, alignment: nil)
  new(spans: [Span.new(content:, style: nil)], alignment:)
end

Instance Method Details

#centered ⇒ Object

Center-aligns this line of text.

Convenience shortcut for alignment: :center. Setting the alignment of a Line overrides the alignment of its parent Text or Widget.

Example

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

line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
centered = line.centered
centered.alignment  # => :center

– SPDX-SnippetEnd ++ Returns: Line.



138
139
140
 
# File 'lib/ratatui_ruby/text/line.rb', line 138

def centered
  with(alignment: :center)
end

#left_aligned ⇒ Object

Left-aligns this line of text.

Convenience shortcut for alignment: :left. Setting the alignment of a Line overrides the alignment of its parent Text or Widget.

Example

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

line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
aligned = line.left_aligned
aligned.alignment  # => :left

– SPDX-SnippetEnd ++ Returns: Line.



114
115
116
 
# File 'lib/ratatui_ruby/text/line.rb', line 114

def left_aligned
  with(alignment: :left)
end

#patch_style(patch) ⇒ Object

Patches the style of this line, adding modifiers from the given style.

Applies patch_style to each span in the line. Use this when you want to layer styles on all spans without replacing their existing styles.

Example

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

line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
styled = line.patch_style(Style::Style.new(fg: :red))
styled.spans.first.style.fg  # => :red

– SPDX-SnippetEnd ++

patch

Style::Style to merge onto each span.

Returns: Line.



215
216
217
 
# File 'lib/ratatui_ruby/text/line.rb', line 215

def patch_style(patch)
  with(spans: spans.map { |s| s.patch_style(patch) })
end

#push_span(span) ⇒ Object

Adds a span to the line.

Since Line is immutable (a Data subclass), this returns a new Line with the span appended. The original line remains unchanged.

Example

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

line = Text::Line.new(spans: [Text::Span.new(content: "Hello, ")])
extended = line.push_span(Text::Span.new(content: "world!"))
extended.spans.size  # => 2
line.spans.size      # => 1 (original unchanged)

– SPDX-SnippetEnd ++

span

Span to append.

Returns: Line.



189
190
191
 
# File 'lib/ratatui_ruby/text/line.rb', line 189

def push_span(span)
  with(spans: spans + [span])
end

#reset_style ⇒ Object

Resets the style of this line.

Applies reset_style to each span in the line, clearing all styling.

Example

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

line = Text::Line.new(spans: [
  Text::Span.new(content: "styled", style: Style::Style.new(fg: :red))
])
reset = line.reset_style
reset.spans.first.style  # => nil

– SPDX-SnippetEnd ++ Returns: Line.



240
241
242
 
# File 'lib/ratatui_ruby/text/line.rb', line 240

def reset_style
  with(spans: spans.map(&:reset_style))
end

#right_aligned ⇒ Object

Right-aligns this line of text.

Convenience shortcut for alignment: :right. Setting the alignment of a Line overrides the alignment of its parent Text or Widget.

Example

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

line = Text::Line.new(spans: [Text::Span.new(content: "Hello")])
aligned = line.right_aligned
aligned.alignment  # => :right

– SPDX-SnippetEnd ++ Returns: Line.



162
163
164
 
# File 'lib/ratatui_ruby/text/line.rb', line 162

def right_aligned
  with(alignment: :right)
end

#width ⇒ Object

Calculates the display width of this line in terminal cells.

Sums the widths of all span contents using the same unicode-aware algorithm as Text.width. Useful for layout calculations.

Examples

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

line = Text::Line.new(spans: [
  Text::Span.new(content: "Hello "),
  Text::Span.new(content: "世界")
])
line.width  # => 10 (6 ASCII + 4 CJK)

– SPDX-SnippetEnd ++ Returns: Integer (number of terminal cells).



90
91
92
 
# File 'lib/ratatui_ruby/text/line.rb', line 90

def width
  RatatuiRuby::Text.width(spans.map { |s| s.content.to_s }.join)
end