Module: NattyUI

Extended by:
Features
Defined in:
lib/natty-ui.rb,
lib/natty-ui/task.rb,
lib/natty-ui/table.rb,
lib/natty-ui/theme.rb,
lib/natty-ui/utils.rb,
lib/natty-ui/choice.rb,
lib/natty-ui/framed.rb,
lib/natty-ui/element.rb,
lib/natty-ui/options.rb,
lib/natty-ui/section.rb,
lib/natty-ui/version.rb,
lib/natty-ui/features.rb,
lib/natty-ui/progress.rb,
lib/natty-ui/temporary.rb,
lib/natty-ui/attributes.rb,
lib/natty-ui/dumb_choice.rb,
lib/natty-ui/ls_renderer.rb,
lib/natty-ui/dumb_options.rb,
lib/natty-ui/width_finder.rb,
lib/natty-ui/hbars_renderer.rb,
lib/natty-ui/table_renderer.rb,
lib/natty-ui/vbars_renderer.rb

Overview

This is the beautiful, nice, nifty, fancy, neat, pretty, cool, rich, lovely, natty user interface you like to have for your command line applications.

The NattyUI ​ᓚᕠᗢ main module implements all Features.

Defined Under Namespace

Modules: Attributes, Features, ProgressHelper, WithStatus Classes: Element, Section, Table, Task, Temporary, Theme

Constant Summary collapse

Ansi =

Uses the ANSI tools of the Terminal.rb gem

Terminal::Ansi
Text =

Uses the Text tools of the Terminal.rb gem

Terminal::Text
VERSION =

The version number of the gem.

'0.30.0'

Class Attribute Summary collapse

User Interaction collapse

Printing Methods collapse

Sub-Elements collapse

Utilities collapse

Class Attribute Details

.element ⇒ Features (readonly)

Current used Element (or NattyUI as top element) supporting all Features.

Returns:

  • (Features) —

    current element or itself



26
27
28
 
# File 'lib/natty-ui.rb', line 26

def element
  @element
end

.input_mode ⇒ :default, ... (readonly)

Supported input mode.

Returns:

  • (:default) —

    when terminal uses ANSI

  • (:dumb) —

    when terminal does not support ANSI or interactive input

  • (nil) —

    when terminal inoput is not supported



37
38
39
40
41
42
43
44
 
# File 'lib/natty-ui.rb', line 37

def input_mode
  case Terminal.input_mode
  when :csi_u, :legacy
    :default
  when :dumb
    :dumb
  end
end

.title ⇒ String?

Terminal title.

Returns:

  • (String) —

    configured title

  • (nil) —

    when no title was set



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

def title = @title_stack.last

Class Method Details

#await(yes: 'Enter', no: 'Esc') ⇒ true, false #await(yes: 'Enter', no: 'Esc') {|temp| ... } ⇒ true, false Originally defined in module Features

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

#choice(*choices, abortable: false) ⇒ Integer? #choice(*choices, abortable: false) {|temp| ... } ⇒ Integer? #choice(**choices, abortable: false) ⇒ Object? #choice(**choices, abortable: false) {|temp| ... } ⇒ Object? Originally defined in module Features

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

.cols(*columns, **attributes) {|row| ... } ⇒ Features Originally defined in module 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:

.div(*text, **attributes) ⇒ Features Originally defined in module 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:

.error(title, *text) {|section| ... } ⇒ Object Also known as: err Originally defined in module Features

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:

.failed(title, *text) {|section| ... } ⇒ Object Originally defined in module Features

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:

.framed(*text, align: :left, border: :default, border_style: nil) {|frame| ... } ⇒ Object Originally defined in module Features

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

.h1(*text) ⇒ Features Originally defined in module Features

Print given text as a H1 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:

.h2(*text) ⇒ Features Originally defined in module Features

Print given text as a H2 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:

.h3(*text) ⇒ Features Originally defined in module Features

Print given text as a H3 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:

.h4(*text) ⇒ Features Originally defined in module Features

Print given text as a H4 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:

.h5(*text) ⇒ Features Originally defined in module Features

Print given text as a H5 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:

.h6(*text) ⇒ Features Originally defined in module Features

Print given text as a H6 #heading.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:

.hbars(values, with_values: true, normalize: false, width: :auto, style: nil, text_style: nil) ⇒ Features Originally defined in module 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

.heading(level, *text) ⇒ Features Originally defined in module 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:

.hr(type = :default) ⇒ Features Originally defined in module Features

Print a horizontal rule.

Examples:

Print double line

ui.hr :double

Parameters:

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

    border type

Returns:

.information(title, *text) {|section| ... } ⇒ Object Also known as: info Originally defined in module Features

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:

.ls(*items, compact: true, glyph: nil) ⇒ Features Originally defined in module 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:

.mark(*text, mark: :default, **options) ⇒ Features Originally defined in module 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:

.message(title, *text) {|section| ... } ⇒ Object Also known as: msg Originally defined in module Features

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:

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

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

.pin(*text, mark: nil, **options) ⇒ Features Originally defined in module 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:

#progress(title, max: nil, pin: false) ⇒ ProgressHelper #progress(title, max: nil, pin: false) {|progress| ... } ⇒ Object Originally defined in module Features

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

.puts(*text, **options) ⇒ Features Originally defined in module 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:

.quote(*text) ⇒ Features Originally defined in module Features

Print given text as a quotation.

Parameters:

  • text (#to_s) —

    one or more convertible objects to print line by line

Returns:

.section(*text) {|section| ... } ⇒ Object Originally defined in module Features

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

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

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

.space(count = 1) ⇒ Features Originally defined in module Features

Print one or more space lines.

Parameters:

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

    lines to print

Returns:

.table(**attributes) {|table| ... } ⇒ Features Originally defined in module 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:

.task(title, *text, pin: false) {|task| ... } ⇒ Object Originally defined in module Features

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

.temporary {|temp| ... } ⇒ Object Originally defined in module Features

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

.vbars(values, normalize: false, height: 10, bar_width: :auto, style: nil) ⇒ Features Originally defined in module 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

.warning(title, *text) {|section| ... } ⇒ Object Also known as: warn Originally defined in module Features

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: