Module: Terminal::Text

Defined in:
lib/terminal/text.rb,
lib/terminal/text/char_width.rb

Overview

Text helper functions.

Constant Summary collapse

UNICODE_VERSION =

supported Unicode Standard version

'17.0.0'

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.ambiguous_char_width ⇒ Integer

Value for width of letters whose display width is not precisely defined by the Unicode standard. Defaults to one (1).

See Also:



17
18
19
 
# File 'lib/terminal/text.rb', line 17

def ambiguous_char_width
  @ambiguous_char_width
end

Class Method Details

.each_line(*text, limit: nil, bbcode: true, ansi: true, ignore_newline: false) {|String| ... } ⇒ Enumerator? Also known as: each

Iterate each line of given text.

Examples:

Generate word-by-word wrapped text for a limited output width

Terminal::Text.each_line('This is a simple test 😀', limit: 6).to_a
# => ["This", "is a", "simple", "test", "😀"]

Yields:

  • (String) —

    text line

Raises:

  • ArgumentError when a limit less than 1 is given



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/terminal/text.rb', line 61

def each_line(
  *text,
  limit: nil,
  bbcode: true,
  ansi: true,
  ignore_newline: false,
  &block
)
  unless limit
    snippets = as_snippets(text, bbcode, ansi, ignore_newline, Word)
    return block ? lines(snippets, &block) : to_enum(:lines, snippets)
  end
  limit = limit.to_i
  raise(ArgumentError, "invalid limit - #{limit}") if limit < 1
  snippets = as_snippets(text, bbcode, ansi, ignore_newline, WordEx)
  return lim_lines(snippets, limit, &block) if block
  to_enum(:lim_lines, snippets, limit)
end

.each_line_with_size(*text, limit: nil, bbcode: true, ansi: true, ignore_newline: false) {|String, Integer| ... } ⇒ Enumerator? Also known as: each_with_size

Iterate each line and it's display width of given text.

Examples:

Generate word-by-word wrapped text for a limited output width

Terminal::Text.each_line_with_size('This is a simple test 😀', limit: 6).to_a
# => [["This", 4], ["is a", 4], ["simple", 6], ["test", 4], ["😀", 2]]

Yields:

  • (String, Integer) —

    text line and it's display width

Raises:

  • ArgumentError when a limit less than 1 is given



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/terminal/text.rb', line 91

def each_line_with_size(
  *text,
  limit: nil,
  bbcode: true,
  ansi: true,
  ignore_newline: false,
  &block
)
  unless limit
    snippets = as_snippets(text, bbcode, ansi, ignore_newline, Word)
    return block ? pairs(snippets, &block) : to_enum(:pairs, snippets)
  end
  limit = limit.to_i
  raise(ArgumentError, "invalid limit - #{limit}") if limit < 1
  snippets = as_snippets(text, bbcode, ansi, ignore_newline, WordEx)
  return lim_pairs(snippets, limit, &block) if block
  to_enum(:lim_pairs, snippets, limit)
end

.max_line_width(*text, ignore_newline: false) ⇒ Integer

Returns maximal width of a line of given text.



115
116
117
118
119
120
121
122
 
# File 'lib/terminal/text.rb', line 115

def max_line_width(*text, ignore_newline: false)
  return 0 if text.empty?
  ret = 0
  pairs(as_snippets(text, false, false, ignore_newline, Word)) do |_l, w|
    ret = w if w > ret
  end
  ret
end

.width(str, bbcode: true) ⇒ Integer

Calculates the display width of the text representation of a given argument. It can optionally ignore embedded BBCode.

The Unicode standard defines the display width for most characters but some are ambiguous. The function uses ambiguous_char_width for each of these characters.



30
31
32
33
34
35
36
37
38
39
 
# File 'lib/terminal/text.rb', line 30

def width(str, bbcode: true)
  return 0 if (str = bbcode ? Ansi.unbbcode(str) : str.to_s).empty?
  str = str.encode(@encoding) if str.encoding != @encoding
  width = 0
  str.scan(@scan_width) do |sp, gc|
    next width += char_width(gc) if gc
    width += 1 if sp
  end
  width
end