class RatatuiRuby::Text::Line

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

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

Attributes

alignment [R]

Alignment within the container.

:left, :center, or :right.

spans [R]

Array of Span objects.

style [R]

Line-level style applied to all spans.

A Style object that sets colors/modifiers for the entire line.

Public Class Methods

from_string (content, alignment: nil)

Source

# 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

Creates a simple line from a string.

Text::Line.from_string("Hello")

new (spans: [], alignment: nil, style: nil)

Source

# File lib/ratatui_ruby/text/line.rb, line 57
def initialize(spans: [], alignment: nil, style: nil)
  super
end

Creates a new Line.

spans: Array of Span objects (or Strings).
alignment: Symbol (optional).
style: Style object (optional).

Calls superclass method

Public Instance Methods

centered ()

Source

# File lib/ratatui_ruby/text/line.rb, line 138
def centered
  with(alignment: :center)
end

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

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

Returns: Line.

left_aligned ()

Source

# File lib/ratatui_ruby/text/line.rb, line 114
def left_aligned
  with(alignment: :left)
end

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

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

Returns: Line.

patch_style (patch)

Source

# File lib/ratatui_ruby/text/line.rb, line 215
def patch_style(patch)
  with(spans: spans.map { |s| s.patch_style(patch) })
end

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

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

patch: Style::Style to merge onto each span.

Returns: Line.

push_span (span)

Source

# File lib/ratatui_ruby/text/line.rb, line 189
def push_span(span)
  with(spans: spans + [span])
end

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

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)

span: Span to append.

Returns: Line.

reset_style ()

Source

# File lib/ratatui_ruby/text/line.rb, line 240
def reset_style
  with(spans: spans.map(&:reset_style))
end

Resets the style of this line.

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

Example

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

Returns: Line.

right_aligned ()

Source

# File lib/ratatui_ruby/text/line.rb, line 162
def right_aligned
  with(alignment: :right)
end

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

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

Returns: Line.

width ()

Source

# File lib/ratatui_ruby/text/line.rb, line 90
def width
  RatatuiRuby::Text.width(spans.map { |s| s.content.to_s }.join)
end

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

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

Returns: Integer (number of terminal cells).