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

    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

    Yield Parameters:

    • temp (Temporary) —

      temporary displayed section (section will be erased after input)

    Returns:

    • (true, false) —

      wheter the user inputs a positive result



639
640
641
642
643
644
645
646
647
648
649
650
651
 
# File 'lib/natty-ui/features.rb', line 639

def await(yes: 'Enter', no: 'Esc')
  temporary do |arg|
    yield(arg) if block_given?
    while (key = Terminal.read_key)
      if (no == key) || (no.is_a?(Enumerable) && no.include?(key))
        return false
      end
      if (yes == key) || (yes.is_a?(Enumerable) && yes.include?(key))
        return true
      end
    end
  end
end

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

Request a user's chocie.

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'

    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'

    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



722
723
724
725
726
727
728
729
730
731
732
733
734
 
# File 'lib/natty-ui/features.rb', line 722

def choice(*choices, abortable: false, **kwchoices, &block)
  return if choices.empty? && kwchoices.empty?
  choice =
    case NattyUI.input_mode
    when :default
      Choice.new(self, choices, kwchoices, abortable)
    when :dumb
      DumbChoice.new(self, choices, kwchoices, abortable)
    else
      return
    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):

Yield Parameters:

  • row (Table::Row) —

    helper to define the row layout

Returns:



374
375
376
377
378
379
380
381
 
# File 'lib/natty-ui/features.rb', line 374

def cols(*columns, **attributes)
  table(**attributes) do |table|
    table.add do |row|
      columns.each { row.add(_1, **attributes) }
      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):

Returns:



404
405
406
407
408
409
 
# File 'lib/natty-ui/features.rb', line 404

def div(*text, **attributes)
  return self if text.empty?
  table(border_around: true, **attributes) do |table|
    table.add { _1.add(*text, **attributes) }
  end
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:



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

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:



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

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:

Returns:

  • (Object) —

    the result of the given block



568
569
570
571
572
573
574
575
576
577
578
579
 
# File 'lib/natty-ui/features.rb', line 568

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:



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

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:



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

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:



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

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:



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

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:



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

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:



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

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

#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:



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

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:

ui.hr(:heavy)

Parameters:

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

    border type

Returns:



282
283
284
285
286
 
# File 'lib/natty-ui/features.rb', line 282

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:



527
528
529
 
# File 'lib/natty-ui/features.rb', line 527

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:



321
322
323
324
325
 
# File 'lib/natty-ui/features.rb', line 321

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) ⇒ 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:



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

def mark(*text, mark: :default)
  mark = Theme.current.mark(mark)
  puts(*text, first_line_prefix: mark, first_line_prefix_width: mark.width)
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:



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

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

#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

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

    whether to igniore newline characters

Returns:



170
171
172
173
174
 
# File 'lib/natty-ui/features.rb', line 170

def pin(*text, mark: nil, **options)
  options[:pin] = true
  options[:first_line_prefix] = Theme.current.mark(mark) if mark
  puts(*text, **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



463
464
465
466
467
468
469
470
471
 
# File 'lib/natty-ui/features.rb', line 463

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

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

    whether to igniore 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
 
# File 'lib/natty-ui/features.rb', line 39

def puts(*text, **options)
  bbcode = true if (bbcode = options[:bbcode]).nil?
  max_width = options[:max_width] || Terminal.columns

  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

  return self if max_width <= 0

  lines =
    Text.each_line_with_size(
      *text,
      limit: max_width,
      bbcode: bbcode,
      ansi: Terminal.ansi?,
      ignore_newline: options[: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:



193
194
195
196
197
198
199
200
201
202
 
# File 'lib/natty-ui/features.rb', line 193

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



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

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

#space(count = 1) ⇒ Features

Print one or more space lines.

Parameters:

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

    lines to print

Returns:



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

def space(count = 1)
  puts("\n" * count) if (count = count.to_i).positive?
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):

Yield Parameters:

  • table (Table) —

    helper to define the table layout

Returns:



353
354
355
356
357
 
# File 'lib/natty-ui/features.rb', line 353

def table(**attributes)
  return self unless block_given?
  yield(table = Table.new(**attributes))
  puts(*TableRenderer[table, columns])
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



591
592
593
 
# File 'lib/natty-ui/features.rb', line 591

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



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

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

#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:



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

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