Module: NattyUI::Features

Included in:
NattyUI, Element
Defined in:
lib/natty-ui/features.rb

Overview

These are all supported features by NattyUI or any other sub- element like #section, #message, #task, ...

Any printed text can contain BBCode-like embedded ANSI attributes which will be used when the output terminal supports attributes and colors.

Printing Methods collapse

Sub-Elements collapse

User Interaction collapse

Utilities collapse

Instance Method Details

#await(yes: 'Enter', no: 'Esc') ⇒ true, false #await(yes: 'Enter', no: 'Esc') {|temp| ... } ⇒ true, false

Wait for user input.

Examples:

Wait until user wants to coninue

ui.await { ui.puts '[faint][\\Press ENTER to continue...][/faint]' }

Ask yes/no-question

ui.await(yes: %w[j o t s y d Enter], no: %w[n Esc]) do
  ui.puts 'Do you like NayttUI?'
end
# => true, for user's YES
# => false, for user's NO
# Info:
# The keys will work for Afrikaans, Dutch, English, French, German,
# Italian, Polish, Portuguese, Romanian, Spanish and Swedish.

Overloads:

  • #await(yes: 'Enter', no: 'Esc') ⇒ true, false

    Returns wheter the user inputs a positive result.

    Parameters:

    • yes (String, Enumerable<String>) (defaults to: 'Enter') —

      key code/s a user can input to return positive result

    • no (String, Enumerable<String>) (defaults to: 'Esc') —

      key code/s a user can input to return negative resault

    Returns:

    • (true, false) —

      wheter the user inputs a positive result

  • #await(yes: 'Enter', no: 'Esc') {|temp| ... } ⇒ true, false

    Parameters:

    • yes (String, Enumerable<String>) (defaults to: 'Enter') —

      key code/s a user can input to return positive result

    • no (String, Enumerable<String>) (defaults to: 'Esc') —

      key code/s a user can input to return negative resault

    Yield Parameters:

    • temp (Temporary) —

      temporary displayed section (section will be erased after input)

    Returns:

    • (true, false) —

      wheter the user inputs a positive result

    • nil in error case



753
754
755
756
757
758
759
 
# File 'lib/natty-ui/features.rb', line 753

def await(yes: 'Enter', no: 'Esc')
  return __await(yes, no) unless block_given?
  temporary do |temp|
    yield(temp)
    __await(yes, no)
  end
end

#choice(*choices, abortable: false) ⇒ Integer? #choice(*choices, abortable: false) {|temp| ... } ⇒ Integer? #choice(**choices, abortable: false) ⇒ Object? #choice(**choices, abortable: false) {|temp| ... } ⇒ Object?

Allows the user to select an option from a selection. The selected option is returned.

Overloads:

  • #choice(*choices, abortable: false) ⇒ Integer?

    Parameters:

    • choices (#to_s) —

      one or more alternatives to select from

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

      whether the user is allowed to abort with 'Esc' or 'Ctrl+c'

    Returns:

    • (Integer) —

      index of selected choice

    • (nil) —

      when user aborted the selection

  • #choice(*choices, abortable: false) {|temp| ... } ⇒ Integer?

    Examples:

    Request a fruit

    ui.choice('Apple', 'Banana', 'Orange') { ui.puts 'What do you prefer?' }
# => 0, when user likes apples
# => 1, when bananas are user's favorite
# => 2, when user is a oranges lover

    Parameters:

    • choices (#to_s) —

      one or more alternatives to select from

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

      whether the user is allowed to abort with 'Esc' or 'Ctrl+c'

    Yield Parameters:

    • temp (Temporary) —

      temporary displayed section (section will be erased after input)

    Returns:

    • (Integer) —

      index of selected choice

    • (nil) —

      when user aborted the selection

  • #choice(**choices, abortable: false) ⇒ Object?

    Parameters:

    • choices (#to_s) —

      one or more alternatives to select from

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

      whether the user is allowed to abort with 'Esc' or 'Ctrl+c'

    • selected (#to_s, nil) —

      optionally pre-selected option

    Returns:

    • (Object) —

      key for selected choice

    • (nil) —

      when user aborted the selection

  • #choice(**choices, abortable: false) {|temp| ... } ⇒ Object?

    Examples:

    Request a preference

    ui.choice(
  k: 'Kitty',
  i: 'iTerm2',
  g: 'Ghostty',
  t: 'Tabby',
  r: 'Rio',
  abortable: true
) { ui.puts 'Which terminal emulator do you like?' }
# => wheter the user selected: :k, :i, :g, :t, :r
# => nil, when the user aborted

    Parameters:

    • choices (#to_s) —

      one or more alternatives to select from

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

      whether the user is allowed to abort with 'Esc' or 'Ctrl+c'

    • selected (Integer) —

      pre-selected option index

    Yield Parameters:

    • temp (Temporary) —

      temporary displayed section (section will be erased after input)

    Returns:

    • (Object) —

      key for selected choice

    • (nil) —

      when user aborted the selection



835
836
837
838
839
840
841
842
843
844
 
# File 'lib/natty-ui/features.rb', line 835

def choice(*choices, abortable: false, selected: nil, **kwchoices, &block)
  return if choices.empty? && kwchoices.empty?
  choice =
    if Terminal.ansi?
      Choice.new(self, choices, kwchoices, abortable, selected)
    else
      DumbChoice.new(self, choices, kwchoices, abortable)
    end
  __with(choice) { choice.select(&block) }
end

#cols(*columns, **attributes) {|row| ... } ⇒ Features

Print text in columns. This is a shorthand to define a Table with a single row.

Parameters:

  • columns (#to_s) —

    two or more convertible objects to print side by side

  • attributes ({Symbol => Object}) —

    attributes for the table and default attributes for table cells

Options Hash (**attributes):

  • :width (Integer) — default: nil —

    width of a column, see Attributes::Width

  • :border (Symbol) — default: nil —

    kind of border, see Table::Attributes

  • :border_style (Enumerable<Symbol>) — default: nil —

    style of border, see Table::Attributes

  • :border_around (true, false) — default: false —

    whether the table should have a border around, see Table::Attributes

  • :position (:left, :right, :centered) — default: false —

    where to align the table, see Table::Attributes

Yield Parameters:

  • row (Table::Row) —

    helper to define the row layout

Returns:



405
406
407
408
409
410
411
412
413
 
# File 'lib/natty-ui/features.rb', line 405

def cols(*columns, **attributes)
  tab_att, att = Utils.split_table_attr(attributes)
  table(**tab_att) do |table|
    table.add do |row|
      columns.each { row.add(_1, **att) }
      yield(row) if block_given?
    end
  end
end

#div(*text, **attributes) ⇒ Features

Print a text division with attributes. This is a shorthand to define a Table with a single cell.

Parameters:

  • attributes ({Symbol => Object}) —

    attributes for the division

  • text (#to_s) —

    one or more convertible objects to print line by line

Options Hash (**attributes):

  • :align (:left, :right, :centered) — default: :left —

    text alignment, see Attributes::Align

  • :padding (Integer, Enumerable<Integer>) — default: nil —

    text padding, see Attributes::Padding

  • :style (Enumerable<Symbol>) — default: nil —

    text style, see Attributes::Style

  • :width (Integer) — default: nil —

    width of the cell, see Attributes::Width

  • :border (Symbol) — default: nil —

    kind of border, see Table::Attributes

  • :border_style (Enumerable<Symbol>) — default: nil —

    style of border, see Table::Attributes

  • :border_around (true, false) — default: false —

    whether the table should have a border around, see Table::Attributes

  • :position (:left, :right, :centered) — default: false —

    where to align the table, see Table::Attributes

Returns:



436
437
438
439
440
441
 
# File 'lib/natty-ui/features.rb', line 436

def div(*text, **attributes)
  return self if text.empty?
  tab_att, att = Utils.split_table_attr(attributes)
  tab_att[:border_around] = true
  table(**tab_att) { |table| table.add { _1.add(*text, **att) } }
end

#error(title, *text) {|section| ... } ⇒ Object Also known as: err

Create a visually separated section marked as an error with a title for the output of text elements.

Parameters:

  • title (#to_s) —

    title to print as section head

  • text (#to_s) —

    convertible objects to print line by line

Yield Parameters:

Returns:

  • (Object) —

    the result of the given block

See Also:



655
 
# File 'lib/natty-ui/features.rb', line 655

def error(title, *text, &block) = __tsec(:error, title, text, &block)

#failed(title, *text) {|section| ... } ⇒ Object

Create a visually separated section marked as a failure with a title for the output of text elements.

Parameters:

  • title (#to_s) —

    title to print as section head

  • text (#to_s) —

    convertible objects to print line by line

Yield Parameters:

Returns:

  • (Object) —

    the result of the given block

See Also:



662
 
# File 'lib/natty-ui/features.rb', line 662

def failed(title, *text, &block) = __tsec(:failed, title, text, &block)

#framed(*text, align: :left, border: :default, border_style: nil) {|frame| ... } ⇒ Object

Create a framed section.

Parameters:

  • align (:left, :right, :centered) (defaults to: :left) —

    text alignment, see Attributes::Align

  • border (Symbol) (defaults to: :default) —

    kind of border, see Attributes::Border

  • border_style (Enumerable<Symbol>) (defaults to: nil) —

    style of border, see Attributes::BorderStyle

  • text (#to_s) —

    convertible objects to print line by line

Yield Parameters:

  • frame (Framed) —

    itself

Returns:

  • (Object) —

    the result of the given block



680
681
682
683
684
685
686
687
688
689
690
691
 
# File 'lib/natty-ui/features.rb', line 680

def framed(*text, align: :left, border: :default, border_style: nil, &block)
  __with(
    Framed.new(
      self,
      Utils.align(align),
      Theme.current.border(border),
      Utils.style(border_style),
      text
    ),
    &block
  )
end

#h1(*text) ⇒ Features

Print given text as a H1 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:



260
 
# File 'lib/natty-ui/features.rb', line 260

def h1(*text) = heading(1, *text)

#h2(*text) ⇒ Features

Print given text as a H2 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:



267
 
# File 'lib/natty-ui/features.rb', line 267

def h2(*text) = heading(2, *text)

#h3(*text) ⇒ Features

Print given text as a H3 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:



274
 
# File 'lib/natty-ui/features.rb', line 274

def h3(*text) = heading(3, *text)

#h4(*text) ⇒ Features

Print given text as a H4 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:



281
 
# File 'lib/natty-ui/features.rb', line 281

def h4(*text) = heading(4, *text)

#h5(*text) ⇒ Features

Print given text as a H5 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:



288
 
# File 'lib/natty-ui/features.rb', line 288

def h5(*text) = heading(5, *text)

#h6(*text) ⇒ Features

Print given text as a H6 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:



295
 
# File 'lib/natty-ui/features.rb', line 295

def h6(*text) = heading(6, *text)

#hbars(values, with_values: true, normalize: false, width: :auto, style: nil, text_style: nil) ⇒ Features

Dump given values as horizontal bars.

Examples:

Draw green bars

ui.hbars 1..10, style: :green

Draw bars in half sreen width

ui.hbars 1..10, style: :blue, width: 0.5

Parameters:

  • values (#to_a, Array<Numeric>) —

    values to print

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

    whether the values should be printed too

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

    whether the values should be normalized

  • height (Integer) —

    output height

  • bar_width (:auto, :min, Integer) —

    with of each bar

  • style (Symbol, Array<Symbol>, nil) (defaults to: nil) —

    bar drawing style

  • text_style (Symbol, Array<Symbol>, nil) (defaults to: nil) —

    text style

Returns:

Raises:

  • (ArgumentError) —

    if any value is negative



502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
 
# File 'lib/natty-ui/features.rb', line 502

def hbars(
  values,
  with_values: true,
  normalize: false,
  width: :auto,
  style: nil,
  text_style: nil
)
  return self if (values = values.to_a).empty?
  if values.any?(&:negative?)
    raise(ArgumentError, 'values can not be negative')
  end
  style = text_style = nil unless Terminal.ansi?
  size = Utils.as_size(3..columns, width)
  if with_values
    puts(*HBarsRenderer.lines(values, size, normalize, style, text_style))
  else
    puts(*HBarsRenderer.lines_bars_only(values, size, normalize, style))
  end
end

#heading(level, *text) ⇒ Features

Print given text as a heading.

There are specific shortcuts for heading levels: #h1, #h2, #h3, #h4, #h5, #h6.

Examples:

Print a level 1 heading

ui.heading(1, 'This is a H1 heading element')
# => ╴╶╴╶─═══ This is a H1 heading element ═══─╴╶╴╶

Parameters:

  • level (#to_i) —

    heading level, one of 1..6

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:



242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/natty-ui/features.rb', line 242

def heading(level, *text)
  prefix, suffix = Theme.current.heading(level)
  puts(
    *text,
    max_width: columns,
    prefix: prefix,
    prefix_width: prefix.width,
    suffix: suffix,
    suffix_width: suffix.width,
    align: :centered
  )
end

#hr(type = :default) ⇒ Features

Print a horizontal rule.

Examples:

Print double line

ui.hr :double

Parameters:

  • type (Symbol) (defaults to: :default) —

    border type

Returns:



306
307
308
309
310
 
# File 'lib/natty-ui/features.rb', line 306

def hr(type = :default)
  theme = Theme.current
  bc = theme.border(type)[10]
  puts("#{theme.heading_sytle}#{bc * columns}")
end

#information(title, *text) {|section| ... } ⇒ Object Also known as: info

Create a visually separated section marked as informational with a title for the output of text elements.

Parameters:

  • title (#to_s) —

    title to print as section head

  • text (#to_s) —

    convertible objects to print line by line

Yield Parameters:

Returns:

  • (Object) —

    the result of the given block

See Also:



639
640
641
 
# File 'lib/natty-ui/features.rb', line 639

def information(title, *text, &block)
  __tsec(:information, title, text, &block)
end

#ls(*items, compact: true, glyph: nil) ⇒ Features

Print given items as list (like 'ls' command).

Each list item will optionally be decorated with the given glyph as:

  • Integer as the start value for a numbered list
  • Symbol as the start symbol
  • :hex to create a hexadecimal numbered list
  • any text as prefix

Examples:

Print all Ruby files as a numbered list

ui.ls Dir['*/**/*.rb'], glyph: 1

Print all Ruby files as a bullet point list (with green bullets)

ui.ls Dir['*/**/*.rb'], glyph: '[green]•[/fg]'

Parameters:

  • items (#to_s) —

    one or more convertible objects to list

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

    whether the compact display format should be used

  • glyph (Integer, :hex, Symbol, #to_s) (defaults to: nil) —

    glyph to be used as prefix

Returns:



345
346
347
348
349
 
# File 'lib/natty-ui/features.rb', line 345

def ls(*items, compact: true, glyph: nil)
  return self if items.empty?
  renderer = compact ? CompactLSRenderer : LSRenderer
  puts(*renderer.lines(items, glyph, columns))
end

#mark(*text, mark: :default, **options) ⇒ Features

Print given text with a decoration mark.

Parameters:

  • mark (Symbol, #to_s) (defaults to: :default) —

    marker type

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:



181
182
183
184
185
186
 
# File 'lib/natty-ui/features.rb', line 181

def mark(*text, mark: :default, **options)
  mark = Theme.current.mark(mark)
  options[:first_line_prefix] = mark
  options[:first_line_prefix_width] = mark.width
  puts(*text, **options)
end

#message(title, *text) {|section| ... } ⇒ Object Also known as: msg

Create a visually separated section with a title for the output of text elements.

Parameters:

  • title (#to_s) —

    title to print as section head

  • text (#to_s) —

    convertible objects to print line by line

Yield Parameters:

Returns:

  • (Object) —

    the result of the given block

See Also:



632
 
# File 'lib/natty-ui/features.rb', line 632

def message(title, *text, &block) = __sec(:message, title, text, &block)

#options(abortable: false, selected: nil, **choices) {|temp| ... } ⇒ {#to_s => [true,false]}?

Allows the user to select from several options. All options are returned with their selection status.

Parameters:

  • choices ({#to_s => [true,false]}) —

    Hash of options and their selection state

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

    whether the user is allowed to abort with 'Esc' or 'Ctrl+c'

  • selected (#to_s, nil) (defaults to: nil) —

    optionally pre-selected key

Yield Parameters:

  • temp (Temporary) —

    temporary displayed section (section will be erased after input)

Returns:

  • ({#to_s => [true,false]}) —

    Hash of options and their selection state

  • (nil) —

    when user aborted the selection



863
864
865
866
867
868
869
870
871
872
 
# File 'lib/natty-ui/features.rb', line 863

def options(abortable: false, selected: nil, **choices, &block)
  return {} if choices.empty?
  options =
    if Terminal.ansi?
      Options.new(self, choices, abortable, selected)
    else
      DumbOptions.new(self, choices, abortable, selected)
    end
  __with(options) { options.select(&block) }
end

#pin(*text, mark: nil, **options) ⇒ Features

Print given text as lines like #puts. Used in elements with temporary output like #task the text will be kept ("pinned").

It can optionally have a decoration marker in first line like #mark.

Examples:

Print two lines decorated as information which are pinned

ui.task 'Do something important' do |task|
  # ...
  task.pin("This is text", "which is pinned", mark: :information)
  # ...
end
# => ✓ Do something important
# =>   𝒊 This is text
# =>     which is pinned.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

  • options ({Symbol => Object})
  • mark (Symbol, #to_s) (defaults to: nil) —

    marker type

Options Hash (**options):

  • :align (:left, :right, :centered) — default: :left —

    text alignment

  • :eol (true, false) — default: true —

    whether to respect newline characters

Returns:



208
209
210
 
# File 'lib/natty-ui/features.rb', line 208

def pin(*text, mark: nil, **options)
  mark(*text, mark: mark, pin: true, **options)
end

#progress(title, max: nil, pin: false) ⇒ ProgressHelper #progress(title, max: nil, pin: false) {|progress| ... } ⇒ Object

Dynamically display a task progress. When a max parameter is given the progress will be displayed as a progress bar below the title. Otherwise the progress is displayed just by accumulating dots.

Examples:

Display a progress bar

ui.progress('Download file', max: 1024) do |progress|
  while progress.value < progress.max
    # just to simulate the download
    sleep(0.1)
    bytes_read = rand(10..128)

    # here we actualize the progress
    progress.value += bytes_read
  end
end

Display simple progress

progress = ui.progress 'Check some stuff'
10.times do
  # simulate some work
  sleep 0.1

  # here we actualize the progress
  progress.step
end
progress.ok 'Stuff checked ok'

Overloads:

  • #progress(title, max: nil, pin: false) ⇒ ProgressHelper

    Returns itself.

    Parameters:

    • title (#to_s) —

      title text to display

    • max (#to_f) (defaults to: nil) —

      expected maximum value

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

      whether the final progress state should be "pinned" to parent element

    Returns:

  • #progress(title, max: nil, pin: false) {|progress| ... } ⇒ Object

    Returns the result of the given block.

    Parameters:

    • title (#to_s) —

      title text

    • max (#to_f) (defaults to: nil) —

      expected maximum value

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

      whether the final progress state should be "pinned" to parent element

    Yield Parameters:

    Returns:

    • (Object) —

      the result of the given block



575
576
577
578
579
580
581
582
583
 
# File 'lib/natty-ui/features.rb', line 575

def progress(title, max: nil, pin: false, &block)
  progress =
    if Terminal.ansi?
      Progress.new(self, title, max, pin)
    else
      DumbProgress.new(self, title, max)
    end
  block ? __with(progress, &block) : progress
end

#puts(*text, **options) ⇒ Features

Print given text as lines.

Examples:

Print two lines text, right aligned

ui.puts "Two lines", "of nice text", align: :right
# =>    Two lines
# => of nice text

Print two lines text, with a prefix

ui.puts "Two lines", "of nice text", prefix: ': '
# => : Two lines
# => : of nice text

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

  • options ({Symbol => Object})

Options Hash (**options):

  • :align (:left, :right, :centered) — default: :left —

    text alignment

  • :eol (true, false) — default: true —

    whether to respect newline characters

Returns:

See Also:



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/natty-ui/features.rb', line 39

def puts(*text, **options)
  if (ansi = Terminal.ansi?)
    @__eol ||= "\e[m\n"
  else
    @__eol ||= "\n"
  end

  if options.empty?
    bbcode = true
    max_width = Terminal.columns
  else
    bbcode = true if (bbcode = options[:bbcode]).nil?
    ignore_newline = options[:eol] == false || options[:ignore_newline]

    if (max_width = options[:max_width]).nil?
      return self if (max_width = Terminal.columns).zero?
    elsif max_width < 1
      if max_width > 0
        max_width *= Terminal.columns
      elsif max_width < 0
        max_width += Terminal.columns
      else
        return self
      end
    end

    prefix_width =
      if (prefix = options[:prefix])
        prefix = Ansi.bbcode(prefix) if bbcode
        options[:prefix_width] || Text.width(prefix, bbcode: false)
      else
        0
      end

    if (first_line = options[:first_line_prefix])
      first_line = Ansi.bbcode(first_line) if bbcode
      first_line_width =
        options[:first_line_prefix_width] ||
          Text.width(first_line, bbcode: false)

      if prefix_width < first_line_width
        prefix_next = "#{prefix}#{' ' * (first_line_width - prefix_width)}"
        prefix = first_line
        prefix_width = first_line_width
      else
        prefix_next = prefix
        prefix =
          if first_line_width < prefix_width
            first_line + (' ' * (prefix_width - first_line_width))
          else
            first_line
          end
      end
    end

    max_width -= prefix_width

    if (suffix = options[:suffix])
      suffix = Ansi.bbcode(suffix) if bbcode
      max_width -=
        options[:suffix_width] || Text.width(suffix, bbcode: false)
    end
  end

  return self if max_width <= 0

  lines =
    Text.each_line_with_size(
      *text,
      limit: max_width,
      bbcode: bbcode,
      ansi: ansi,
      ignore_newline: ignore_newline
    )

  if (align = options[:align]).nil?
    lines.each do |line|
      Terminal.print(prefix, line, suffix, @__eol, bbcode: false)
      @lines_written += 1
      prefix, prefix_next = prefix_next, nil if prefix_next
    end
    return self
  end

  unless options[:expand]
    lines = lines.to_a
    max_width = lines.max_by(&:last).last
  end

  case align
  when :right
    lines.each do |line, width|
      Terminal.print(
        prefix,
        ' ' * (max_width - width),
        line,
        suffix,
        @__eol,
        bbcode: false
      )
      @lines_written += 1
      prefix, prefix_next = prefix_next, nil if prefix_next
    end
  when :centered
    lines.each do |line, width|
      space = max_width - width
      Terminal.print(
        prefix,
        ' ' * (lw = space / 2),
        line,
        ' ' * (space - lw),
        suffix,
        @__eol,
        bbcode: false
      )
      @lines_written += 1
      prefix, prefix_next = prefix_next, nil if prefix_next
    end
  else
    lines.each do |line, width|
      Terminal.print(
        prefix,
        line,
        ' ' * (max_width - width),
        suffix,
        @__eol,
        bbcode: false
      )
      @lines_written += 1
      prefix, prefix_next = prefix_next, nil if prefix_next
    end
  end
  self
end

#quote(*text) ⇒ Features

Print given text as a quotation.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:



217
218
219
220
221
222
223
224
225
226
 
# File 'lib/natty-ui/features.rb', line 217

def quote(*text)
  width = columns * 0.75
  quote = Theme.current.mark(:quote)
  puts(
    *text,
    prefix: quote,
    prefix_width: quote.width,
    max_width: width < 20 ? nil : width.round
  )
end

#section(*text) {|section| ... } ⇒ Object

Create a visually separated section for the output of text elements. Like any other Element sections support all NattyUI::Features.

Examples:

ui.section do |section|
  section.h1 'About Sections'
  section.space
  section.puts 'Sections are areas of text elements.'
  section.puts 'You can use any other feature inside such an area.'
end
# => ╭────╶╶╶
# => │ ╴╶╴╶─═══ About Sections ═══─╴╶╴╶
# => │
# => │ Sections are areas of text elements.
# => │ You can use any other feature inside such an area.
# => ╰──── ─╶╶╶

Parameters:

  • text (#to_s) —

    convertible objects to print line by line

Yield Parameters:

Returns:

  • (Object) —

    the result of the given block



618
 
# File 'lib/natty-ui/features.rb', line 618

def section(*text, &block) = __sec(:default, nil, text, &block)

#select(*choices, abortable: false, selected: nil) {|temp| ... } ⇒ Array<#to_s>?

Allows the user to select from several options. The selected options are returned.

Examples:

Select a terminal

ui.select %w[Kitty iTerm2 Ghostty Tabby Rio] do
 ui.puts '[i]Which terminal applications did you already tested?[/i]'
end

Parameters:

  • choices (Array<#to_s>) —

    selectable options

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

    whether the user is allowed to abort with 'Esc' or 'Ctrl+c'

  • selected (Integer, :all, nil) (defaults to: nil) —

    optionally pre-selected option index or :all to pre-select all items

Yield Parameters:

  • temp (Temporary) —

    temporary displayed section (section will be erased after input)

Returns:

  • (Array<#to_s>) —

    selected options

  • (nil) —

    when user aborted the selection



895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
 
# File 'lib/natty-ui/features.rb', line 895

def select(*choices, abortable: false, selected: nil, &block)
  return [] if choices.empty?
  choices = choices[0] if choices.size == 1 && choices[0].is_a?(Enumerable)
  if selected == :all
    sel = true
  elsif selected
    selected = choices[selected.to_i]
  end
  options(
    abortable: abortable,
    selected: selected,
    **choices.to_h { [_1, sel] },
    &block
  ).filter_map { |key, selected| key if selected }
end

#space(count = 1) ⇒ Features

Print one or more space lines.

Parameters:

  • count (#to_i) (defaults to: 1) —

    lines to print

Returns:



318
319
320
 
# File 'lib/natty-ui/features.rb', line 318

def space(count = 1)
  (count = count.to_i).positive? ? puts("\n" * count) : self
end

#table(**attributes) {|table| ... } ⇒ Features

Generate and print a table. See Table for much more details about table generation.

Examples:

Draw a very simple 3x4 table with complete borders

ui.table(border: :default, border_around: true, padding: [0, 1]) do |table|
  table.add 1, 2, 3, 4
  table.add 5, 6, 7, 8
  table.add 9, 10, 11, 12
end

Parameters:

  • attributes ({Symbol => Object}) —

    attributes for the table and default attributes for table cells

Options Hash (**attributes):

  • :border (Symbol) — default: nil —

    kind of border, see Table::Attributes

  • :border_style (Enumerable<Symbol>) — default: nil —

    style of border, see Table::Attributes

  • :border_around (true, false) — default: false —

    whether the table should have a border around, see Table::Attributes

  • :position (:left, :right, :centered) — default: false —

    where to align the table, see Table::Attributes

Yield Parameters:

  • table (Table) —

    helper to define the table layout

Returns:



380
381
382
383
384
385
386
387
388
 
# File 'lib/natty-ui/features.rb', line 380

def table(**attributes)
  return self unless block_given?
  yield(table = Table.new(**attributes))
  puts(
    *TableRenderer[table, columns],
    align: table.attributes.position,
    expand: true
  )
end

#task(title, *text, pin: false) {|task| ... } ⇒ Object

Generate a task section.

Parameters:

  • title (#to_s) —

    task title text

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

    whether to keep text "pinned"

  • text (#to_s) —

    convertible objects to print line by line

Yield Parameters:

  • task (Task) —

    itself

Returns:

  • (Object) —

    the result of the given block



703
704
705
 
# File 'lib/natty-ui/features.rb', line 703

def task(title, *text, pin: false, &block)
  __with(Task.new(self, title, text, pin), &block)
end

#temporary {|temp| ... } ⇒ Object

Display some temporary content. The content displayed in the block will be erased after the block ends.

Examples:

Show tempoary information

ui.temporary do
  ui.info 'Information', 'This text will disappear when you pressed ENTER.'
  ui.await
end

Yield Parameters:

Returns:

  • (Object) —

    the result of the given block



935
 
# File 'lib/natty-ui/features.rb', line 935

def temporary(&block) = __with(Temporary.new(self), &block)

#vbars(values, normalize: false, height: 10, bar_width: :auto, style: nil) ⇒ Features

Dump given values as vertical bars.

Examples:

Draw green bars

ui.vbars 1..10, style: :green

Draw very big bars

ui.vbars 1..10, bar_width: 5, height: 20

Parameters:

  • values (#to_a, Array<Numeric>) —

    values to print

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

    whether the values should be normalized

  • height (Integer) (defaults to: 10) —

    output height

  • bar_width (:auto, :min, Integer) (defaults to: :auto) —

    with of each bar

  • style (Symbol, Array<Symbol>, nil) (defaults to: nil) —

    drawing style

Returns:

Raises:

  • (ArgumentError) —

    if any value is negative



460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
 
# File 'lib/natty-ui/features.rb', line 460

def vbars(
  values,
  normalize: false,
  height: 10,
  bar_width: :auto,
  style: nil
)
  return self if (values = values.to_a).empty?
  if values.any?(&:negative?)
    raise(ArgumentError, 'values can not be negative')
  end
  puts(
    *VBarsRenderer.lines(
      values,
      columns,
      height,
      normalize,
      bar_width,
      Terminal.ansi? ? style : nil
    )
  )
end

#warning(title, *text) {|section| ... } ⇒ Object Also known as: warn

Create a visually separated section marked as a warning with a title for the output of text elements.

Parameters:

  • title (#to_s) —

    title to print as section head

  • text (#to_s) —

    convertible objects to print line by line

Yield Parameters:

Returns:

  • (Object) —

    the result of the given block

See Also:



648
 
# File 'lib/natty-ui/features.rb', line 648

def warning(title, *text, &block) = __tsec(:warning, title, text, &block)