Class: Tuile::StyledString

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

Overview

An immutable string-with-styling, modeled as a sequence of Spans where each span carries a complete Style (fg, bg, bold, italic, underline, strikethrough). Spans are non-overlapping and fully tile the string — every character has exactly one resolved style, no overlay layers to merge, so the style at any column is just its span's style rather than a replay of the SGR state machine. The book's chapter 9 is the long-form why (spans vs. a String full of escape codes).

Constructors

StyledString.new                                  # empty
StyledString.plain("hello")                       # default style
StyledString.styled("hello", fg: :red, bold: true)
StyledString.parse("\e[31mhello\e[0m world")      # ANSI → spans

Algebra

All operations return a fresh StyledString — the underlying spans are frozen and shared. + coerces a String operand via StyledString.parse.

a + b                       # concatenate
ss.slice(2, 5)              # 5 display columns starting at column 2
ss.slice(2..5)              # range (inclusive end)
ss.lines                    # split on "\n" → Array<StyledString>
ss.each_char_with_style { |ch, style| ... }

Parser

StyledString.parse is strict by default — it recognizes only the SGR codes for Style's attributes (fg/bg/bold/italic/underline/strikethrough) and raises ParseError on anything else, keeping the parse(to_ansi(x)) == x round-trip honest. Pass lenient: true to instead discard everything it can't model (unmodeled SGR, cursor moves, OSC/DCS, stray escapes) and keep only the recognized colors — lossy by design, for piping in colored output you don't control. See the book for the full rationale.

Defined Under Namespace

Classes: ParseError, Span, Style

Constant Summary collapse

EMOJI_WIDTH =

The framework's single emoji-width policy, passed to every Unicode::DisplayWidth.of call in Tuile.

:rgi credits width 2 only to RGI sequences — the ones vendors actually ship a single glyph for — and sums the parts of anything else. That is the one setting never wrong in the dangerous direction: under-measuring lets a glyph overrun its cell, which shifts the rest of the row, desyncs the cursor and escapes the component's rect, while over-measuring leaves a blank column. D-cluster-width has the per-setting reasoning.

Returns:

  • (Symbol) 
:rgi
EMPTY =

Canonical shared empty Tuile::StyledString. Operations that produce an empty result (and callers that need a blank sentinel) can use this instead of allocating a fresh instance per call. Pre-warmed and frozen — the lazy #display_width / #to_ansi memoizations short-circuit on the already cached values, so reads on the frozen receiver do not attempt writes.

Returns:

new.tap do |s|
  s.display_width
  s.to_ansi
end.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(spans = []) ⇒ StyledString

@param spans

Parameters:

  • spans (::Array[Span]) (defaults to: []) 


418
419
420
 
# File 'lib/tuile/styled_string.rb', line 418

def initialize(spans = [])
  @spans = normalize(spans).freeze
end

Instance Attribute Details

#spans ⇒ ::Array[Span] (readonly)

@return — the frozen, normalized span list — no empty-text entries, no two adjacent entries sharing a style.

Returns:



415
416
417
 
# File 'lib/tuile/styled_string.rb', line 415

def spans
  @spans
end

Class Method Details

.parse(input, lenient: false) ⇒ StyledString

Parses an ANSI/SGR-coded string into a Tuile::StyledString. A Tuile::StyledString input is returned as-is. nil and the empty string both fast-path to EMPTY. Strings without any \e byte fast-path to a single default-styled span.

@param input

@param lenient — when true, unmodeled SGR codes and non-SGR escapes are discarded instead of raising — see Tuile::StyledString "## Parser". Lossy: the result no longer round-trips to input.

Parameters:

  • input (String, StyledString, nil)
  • lenient: (Boolean) (defaults to: false)

Returns:



385
386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/tuile/styled_string.rb', line 385

def parse(input, lenient: false)
  case input
  when nil then EMPTY
  when StyledString then input
  when String
    return EMPTY if input.empty?
    return new([Span.new(text: input, style: Style::DEFAULT)]) unless input.include?("\e")

    Parser.new(input, lenient:).parse
  else
    raise TypeError, "cannot parse #{input.class}"
  end
end

.plain(text) ⇒ StyledString

sord duck - #to_s looks like a duck type with an equivalent RBS interface, replacing with _ToS @param text

Parameters:

  • text (_ToS)

Returns:



355
356
357
358
359
360
 
# File 'lib/tuile/styled_string.rb', line 355

def plain(text)
  text = text.to_s
  return EMPTY if text.empty?

  new([Span.new(text: text, style: Style::DEFAULT)])
end

.styled(text, **style_kwargs) ⇒ StyledString

sord duck - #to_s looks like a duck type with an equivalent RBS interface, replacing with _ToS @param text

@param style_kwargs — forwarded to Tuile::StyledString::Style.new.

Parameters:

  • text (_ToS)
  • style_kwargs (::Hash[Symbol, Object])

Returns:



365
366
367
368
369
370
 
# File 'lib/tuile/styled_string.rb', line 365

def styled(text, **style_kwargs)
  text = text.to_s
  return EMPTY if text.empty?

  new([Span.new(text: text, style: Style.new(**style_kwargs))])
end

Instance Method Details

#+(other) ⇒ StyledString

Concatenation. A String operand is parsed via parse before joining (so embedded ANSI escapes round-trip through spans).

@param other

Parameters:

Returns:



466
467
468
469
470
471
 
# File 'lib/tuile/styled_string.rb', line 466

def +(other)
  other = self.class.parse(other) if other.is_a?(String)
  raise TypeError, "cannot concatenate #{other.class} to StyledString" unless other.is_a?(StyledString)

  self.class.new(@spans + other.spans)
end

#==(other) ⇒ Boolean Also known as: eql?

@param other

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


451
452
453
 
# File 'lib/tuile/styled_string.rb', line 451

def ==(other)
  other.is_a?(StyledString) && @spans == other.spans
end

#build_ansi ⇒ String

Returns:

  • (String) 


632
633
634
635
636
637
638
639
640
641
642
 
# File 'lib/tuile/styled_string.rb', line 632

def build_ansi
  out = +""
  current = Style::DEFAULT
  @spans.each do |span|
    out << current.sgr_to(span.style)
    out << span.text
    current = span.style
  end
  out << Ansi::RESET unless current.default?
  out
end

#display_width ⇒ Integer

Total display width in terminal columns, accounting for Unicode wide characters (fullwidth CJK = 2 columns, combining marks = 0, etc.).

Returns:

  • (Integer) 


425
426
427
 
# File 'lib/tuile/styled_string.rb', line 425

def display_width
  @display_width ||= @spans.sum { |s| Unicode::DisplayWidth.of(s.text, emoji: EMOJI_WIDTH) }
end

#each_char_with_style ⇒ ::Enumerator[untyped], self

Yields each character (per String#each_char) along with the Style it carries. Returns an Enumerator without a block.

Returns:

  • (::Enumerator[untyped], self) 


571
572
573
574
575
576
577
578
 
# File 'lib/tuile/styled_string.rb', line 571

def each_char_with_style
  return enum_for(__method__) unless block_given?

  @spans.each do |span|
    span.text.each_char { |c| yield c, span.style }
  end
  self
end

#each_glyph_with_style(styled) ⇒ void

This method returns an undefined value.

Like #each_char_with_style but per grapheme cluster. A cluster spanning a style boundary takes the style of its first span — pathological input, and splitting the cluster to honor both styles would paint a headless mark.

@param styled

Parameters:



790
791
792
793
794
 
# File 'lib/tuile/styled_string.rb', line 790

def each_glyph_with_style(styled)
  styled.spans.each do |span|
    span.text.each_grapheme_cluster { |g| yield g, span.style }
  end
end

#ellipsize(display_width, ellipsis = "…") ⇒ StyledString

Truncates to a target column width, appending an ellipsis when characters were dropped. The ellipsis counts toward the target — the returned Tuile::StyledString's display_width never exceeds display_width. When self already fits, self is returned. When display_width is smaller than the ellipsis's own width, the ellipsis is sliced down to fit and no original content is included.

@param display_width — target column width.

@param ellipsis — appended when truncation occurs. Defaults to the Unicode horizontal-ellipsis … (one column). A String is parsed via parse, so ANSI in it is preserved.

Parameters:

  • display_width (Integer)
  • ellipsis (?(String | StyledString)) (defaults to: "…")

Returns:



508
509
510
511
512
513
514
515
516
 
# File 'lib/tuile/styled_string.rb', line 508

def ellipsize(display_width, ellipsis = "…")
  return self.class.new if display_width <= 0
  return self if self.display_width <= display_width

  ellipsis = self.class.parse(ellipsis)
  return ellipsis.slice(0, display_width) if ellipsis.display_width >= display_width

  slice(0, display_width - ellipsis.display_width) + ellipsis
end

#empty? ⇒ Boolean

Returns:

  • (Boolean) 


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

def empty? = @spans.empty?

#glyphs_to_styled(glyphs) ⇒ StyledString

@param glyphs — [grapheme cluster, style, width] triples.

Parameters:

  • glyphs (::Array[::Array[untyped]])

Returns:



819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
 
# File 'lib/tuile/styled_string.rb', line 819

def glyphs_to_styled(glyphs)
  return self.class.new if glyphs.empty?

  spans = []
  current_text = +""
  current_style = glyphs.first[1]
  glyphs.each do |g, s, _|
    if s == current_style
      current_text << g
    else
      spans << Span.new(text: current_text, style: current_style)
      current_text = +g
      current_style = s
    end
  end
  spans << Span.new(text: current_text, style: current_style)
  self.class.new(spans)
end

#hard_break_glyphs(glyphs, width) ⇒ ::Array[::Array[::Array[untyped]]]

@param glyphs — [grapheme cluster, style, width] triples.

@param width

@return — each inner Array is a glyphs-shaped chunk.

Parameters:

  • glyphs (::Array[::Array[untyped]])
  • width (Integer)

Returns:

  • (::Array[::Array[::Array[untyped]]]) 


799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
 
# File 'lib/tuile/styled_string.rb', line 799

def hard_break_glyphs(glyphs, width)
  chunks = []
  current = []
  current_w = 0
  glyphs.each do |triple|
    cw = triple[2]
    if current_w + cw > width && current_w.positive?
      chunks << current
      current = []
      current_w = 0
    end
    current << triple
    current_w += cw
  end
  chunks << current
  chunks
end

#hash ⇒ Integer

Returns:

  • (Integer) 


457
458
459
 
# File 'lib/tuile/styled_string.rb', line 457

def hash
  @spans.hash
end

#inspect ⇒ String

Returns:

  • (String) 


625
626
627
 
# File 'lib/tuile/styled_string.rb', line 625

def inspect
  "#<#{self.class.name} #{to_s.inspect}>"
end

#lines ⇒ ::Array[StyledString]

Splits on "\n", preserving spans on each side. A trailing newline produces a trailing empty Tuile::StyledString (matches split("\n", -1)). An empty Tuile::StyledString returns a single empty entry, like "".split.

Returns:



522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
 
# File 'lib/tuile/styled_string.rb', line 522

def lines
  result = []
  current_spans = []
  @spans.each do |span|
    parts = span.text.split("\n", -1)
    parts.each_with_index do |part, idx|
      if idx.positive?
        result << self.class.new(current_spans)
        current_spans = []
      end
      current_spans << Span.new(text: part, style: span.style) unless part.empty?
    end
  end
  result << self.class.new(current_spans)
  result
end

#normalize(spans) ⇒ ::Array[Span]

@param spans

Parameters:

  • spans (::Array[Span])

Returns:



646
647
648
649
650
651
652
653
654
655
656
657
658
659
 
# File 'lib/tuile/styled_string.rb', line 646

def normalize(spans)
  result = []
  spans.each do |span|
    next if span.text.empty?

    if !result.empty? && result.last.style == span.style
      last = result.pop
      result << Span.new(text: last.text + span.text, style: span.style)
    else
      result << span
    end
  end
  result
end

#resolve_slice_bounds(start_or_range, len, total) ⇒ [Integer, Integer]

@param start_or_range

@param len

@param total — receiver's full display width.

@return — normalized [start_col, len_col].

Parameters:

  • start_or_range (Integer, ::Range[untyped])
  • len (Integer, nil)
  • total (Integer)

Returns:

  • ([Integer, Integer]) 


665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
 
# File 'lib/tuile/styled_string.rb', line 665

def resolve_slice_bounds(start_or_range, len, total)
  if start_or_range.is_a?(Range)
    range = start_or_range
    start = range.begin || 0
    finish = range.end
    start += total if start.negative?
    if finish.nil?
      finish = total
    else
      finish += total if finish.negative?
      finish += 1 unless range.exclude_end?
    end
    [start, finish - start]
  else
    raise ArgumentError, "length is required when slicing with an Integer" if len.nil?

    start = start_or_range
    start += total if start.negative?
    [start, len]
  end
end

#slice(start_or_range, len = nil) ⇒ StyledString

Substring by display columns, preserving spans. Characters whose column range only partially overlaps the slice (e.g. a 2-column CJK character straddling the start or end boundary) are dropped — never split.

Accepts either slice(start_col, len_col) or slice(range). Both forms support negative indices counting from the end of the string.

@param start_col

@param len_col

Parameters:

  • start_col (Integer)
  • len_col (Integer)

Returns:



486
487
488
489
490
491
492
493
 
# File 'lib/tuile/styled_string.rb', line 486

def slice(start_or_range, len = nil)
  total = display_width
  start, len = resolve_slice_bounds(start_or_range, len, total)
  return self.class.new if len <= 0 || start.negative? || start >= total

  len = [len, total - start].min
  slice_spans(start, len)
end

#slice_spans(start, len) ⇒ StyledString

@param start

@param len

Parameters:

  • start (Integer)
  • len (Integer)

Returns:



690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
 
# File 'lib/tuile/styled_string.rb', line 690

def slice_spans(start, len)
  out = []
  col = 0
  @spans.each do |span|
    span_width = Unicode::DisplayWidth.of(span.text, emoji: EMOJI_WIDTH)
    span_end = col + span_width

    next col = span_end if span_end <= start
    break if col >= start + len

    local_start = [0, start - col].max
    local_end = [span_width, start + len - col].min
    if local_end > local_start
      sliced = slice_text_by_columns(span.text, local_start, local_end - local_start)
      out << Span.new(text: sliced, style: span.style) unless sliced.empty?
    end
    col = span_end
  end
  self.class.new(out)
end

#slice_text_by_columns(text, start_col, len_col) ⇒ String

Walks grapheme clusters, so a slice boundary can never fall inside one: cutting a cluster would strand a combining mark with no base, which the painter drops outright, silently losing the accent off a letter.

@param text

@param start_col

@param len_col

Parameters:

  • text (String)
  • start_col (Integer)
  • len_col (Integer)

Returns:

  • (String) 


845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
 
# File 'lib/tuile/styled_string.rb', line 845

def slice_text_by_columns(text, start_col, len_col)
  out = +""
  col = 0
  text.each_grapheme_cluster do |g|
    gw = Buffer.display_width(g)
    glyph_end = col + gw
    if glyph_end <= start_col
      # entirely before slice — skip
    elsif col >= start_col + len_col
      break
    elsif col >= start_col && glyph_end <= start_col + len_col
      out << g
    end
    # any other case = partial overlap with a wide glyph — drop
    col = glyph_end
  end
  out
end

#to_ansi ⇒ String

Rendered ANSI string. Minimal-diff between adjacent spans: only the attributes that changed are emitted. A transition to the default style emits \e[0m (one code) instead of the longer "turn each attribute off" form. Always closes with \e[0m when the last span carried a non-default style, so the styled run doesn't bleed into subsequent output.

Returns:

  • (String) 


445
446
447
 
# File 'lib/tuile/styled_string.rb', line 445

def to_ansi
  @to_ansi ||= build_ansi
end

#to_s ⇒ String

Plain text concatenation across all spans — no SGR codes.

Returns:

  • (String) 


434
435
436
 
# File 'lib/tuile/styled_string.rb', line 434

def to_s
  @spans.map(&:text).join
end

#tokenize_for_wrap(hard_line) ⇒ ::Array[::Array[untyped]]

Splits into whitespace/word tokens by grapheme cluster, not character: a cluster is the unit a terminal draws, so measuring its parts separately would both mis-total an emoji sequence and let a wrap break a letter away from its combining mark.

@param hard_line

@return — tokens shaped [type, glyphs, w] where type is :space or :word, glyphs is an Array<[String, Style, Integer]> (grapheme cluster, style, display width), and w is the token's total width.

Parameters:

Returns:

  • (::Array[::Array[untyped]]) 


761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
 
# File 'lib/tuile/styled_string.rb', line 761

def tokenize_for_wrap(hard_line)
  tokens = []
  current_glyphs = []
  current_w = 0
  current_type = nil

  each_glyph_with_style(hard_line) do |g, s|
    type = [" ", "\t"].include?(g) ? :space : :word
    gw = Buffer.display_width(g)
    if current_type && current_type != type
      tokens << [current_type, current_glyphs, current_w]
      current_glyphs = []
      current_w = 0
    end
    current_type = type
    current_glyphs << [g, s, gw]
    current_w += gw
  end
  tokens << [current_type, current_glyphs, current_w] unless current_glyphs.empty?
  tokens
end

#under_bg(bg) ⇒ StyledString

Returns a copy with bg set only on spans that have none; a span with an explicit bg is left untouched. The fill-unset counterpart of #with_bg (which overrides every span) — it slides a background under the content, so a log line keeps its red error-level bg while its plain text picks up an inherited panel tint.

@param bg — background color, coerced via Color.coerce. nil returns self unchanged.

Parameters:

  • bg (Color, Symbol, Integer, ::Array[Integer], nil)

Returns:



602
603
604
605
606
607
608
609
 
# File 'lib/tuile/styled_string.rb', line 602

def under_bg(bg)
  return self if bg.nil?

  bg = Color.coerce(bg)
  self.class.new(@spans.map do |span|
    span.style.bg.nil? ? Span.new(text: span.text, style: span.style.merge(bg: bg)) : span
  end)
end

#with_bg(bg) ⇒ StyledString

Returns a new Tuile::StyledString with bg applied to every span, preserving each span's text and other style attributes (fg, bold, italic, underline, strikethrough). Useful for row-level highlights — the new bg overlays without dropping foreground colors the original styling carried.

@param bg — background color, coerced via Color.coerce. nil clears bg back to the terminal default.

Parameters:

  • bg (Color, Symbol, Integer, ::Array[Integer], nil)

Returns:



589
590
591
 
# File 'lib/tuile/styled_string.rb', line 589

def with_bg(bg)
  self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(bg: bg)) })
end

#with_fg(fg) ⇒ StyledString

Returns a new Tuile::StyledString with fg applied to every span, preserving each span's text and other style attributes (bg, bold, italic, underline, strikethrough). The new fg overlays without dropping background colors or text attributes the original styling carried.

@param fg — foreground color, coerced via Color.coerce. nil clears fg back to the terminal default.

Parameters:

  • fg (Color, Symbol, Integer, ::Array[Integer], nil)

Returns:



620
621
622
 
# File 'lib/tuile/styled_string.rb', line 620

def with_fg(fg)
  self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(fg: fg)) })
end

#wrap(width) ⇒ ::Array[StyledString]

Word-wraps to physical lines that each fit within width display columns, preserving spans and styles across breaks. Greedy word-wrap, hard-break for words wider than width, leading whitespace dropped on wrapped continuations, hard "\n" breaks preserved as separate output lines.

Whitespace runs are space or tab; other characters are treated as word content. When a single character is wider than width (e.g. a 2-column CJK character with width = 1), it is still emitted on its own line at its natural width. The "no line exceeds width" guarantee therefore holds whenever every character is at most width columns wide.

@param width — target column width. nil or <= 0 skips wrapping and returns each hard-line as-is, so callers can pass a stale viewport width without crashing.

@return — one entry per physical (output) line. An empty receiver returns [].

Parameters:

  • width (Integer, nil)

Returns:



556
557
558
559
560
561
562
563
564
565
 
# File 'lib/tuile/styled_string.rb', line 556

def wrap(width)
  return [] if empty?

  hard_lines = lines
  return hard_lines if width.nil? || width <= 0

  result = []
  hard_lines.each { |hl| result.concat(wrap_one(hl, width)) }
  result
end

#wrap_one(hard_line, width) ⇒ ::Array[StyledString]

@param hard_line — one hard-broken line — no embedded "\n".

@param width

Parameters:

Returns:



714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
 
# File 'lib/tuile/styled_string.rb', line 714

def wrap_one(hard_line, width)
  return [hard_line] if hard_line.empty?

  result = []
  line_glyphs = []
  line_w = 0

  tokenize_for_wrap(hard_line).each do |type, glyphs, w|
    if type == :space
      if line_w.zero?
        # leading whitespace on a wrapped continuation: drop
      elsif line_w + w <= width
        line_glyphs.concat(glyphs)
        line_w += w
      else
        result << glyphs_to_styled(line_glyphs)
        line_glyphs = []
        line_w = 0
      end
    elsif line_w + w <= width
      line_glyphs.concat(glyphs)
      line_w += w
    elsif w > width
      result << glyphs_to_styled(line_glyphs) unless line_w.zero?
      chunks = hard_break_glyphs(glyphs, width)
      chunks[0..-2].each { |chunk| result << glyphs_to_styled(chunk) }
      line_glyphs = chunks.last
      line_w = line_glyphs.sum { |triple| triple[2] }
    else
      result << glyphs_to_styled(line_glyphs)
      line_glyphs = glyphs
      line_w = w
    end
  end
  result << glyphs_to_styled(line_glyphs)
  result
end