Module: Terminal::Text

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

Overview

Text helper functions.

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

Returns:

  • (Integer) —

    value

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", "😀"]

Parameters:

  • text (#to_s, ...) —

    text objects to process

  • limit (#to_i, nil) (defaults to: nil) —

    optionally limit line size

  • bbcode (true, false) (defaults to: true) —

    whether to interprete embedded BBCode (see Ansi.bbcode)

  • ansi (true, false) (defaults to: true) —

    whether to keep embedded ANSI control codes

  • ignore_newline (true, false) (defaults to: false) —

    wheter to ignore embedded line breaks ("\r\n" or "\n")

Yields:

  • (String) —

    text line

Returns:

  • (Enumerator) —

    when no block given

  • (nil)

Raises:

  • ArgumentError when a limit less than 1 is given



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

def each_line(
  *text,
  limit: nil,
  bbcode: true,
  ansi: true,
  ignore_newline: false,
  &block
)
  unless limit
    snippeds = as_snippeds(text, bbcode, ansi, ignore_newline, Word)
    return block ? lines(snippeds, &block) : to_enum(:lines, snippeds)
  end
  limit = limit.to_i
  raise(ArgumentError, "invalid limit - #{limit}") if limit < 1
  snippeds = as_snippeds(text, bbcode, ansi, ignore_newline, WordEx)
  return lim_lines(snippeds, limit, &block) if block
  to_enum(:lim_lines, snippeds, 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]]

Parameters:

  • text (#to_s, ...) —

    text objects to process

  • limit (#to_i, nil) (defaults to: nil) —

    optionally limit line size

  • bbcode (true, false) (defaults to: true) —

    whether to interprete embedded BBCode (see Ansi.bbcode)

  • ansi (true, false) (defaults to: true) —

    whether to keep embedded ANSI control codes

  • ignore_newline (true, false) (defaults to: false) —

    wheter to ignore embedded line breaks ("\r\n" or "\n")

Yields:

  • (String, Integer) —

    text line and it's display width

Returns:

  • (Enumerator) —

    when no block given

  • (nil)

Raises:

  • ArgumentError when a limit less than 1 is given



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

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

Parameters:

  • str (#to_s) —

    object to process

  • bbcode (true|false) (defaults to: true) —

    whether to interpret embedded BBCode

Returns:

  • (Integer) —

    display width



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

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