Class: NattyUI::Element

Inherits:
Object
  • Object
show all
Includes:
Features
Defined in:
lib/natty-ui/element.rb

Overview

Base element class supporting all Features.

Direct Known Subclasses

Section, Temporary

User Interaction collapse

Printing Methods collapse

Sub-Elements collapse

Utilities collapse

Instance 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

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