Class: NattyUI::Element

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

Overview

Base class for all UI container elements.

Instances are never created directly; they are returned (or yielded) by the section-opening methods on Features: Features#section, Features#frame, Features#task, Features#progress, Features#margin, Features#temporary, and their typed variants.

Every Element includes Features, so all output and section methods are available on the element itself.

Examples:

Using an element returned without a block

frm = ui.frame 'Progress'
frm.puts 'Loading…'
frm.end   # closes the frame

The element is also yielded inside a block

ui.section 'Summary' do |sec|
  sec.ok 'Done'
end

Direct Known Subclasses

Frame, Margin, Section, Temporary

Section elements collapse

User Interaction collapse

Output methods collapse

Utilities collapse

Instance Method Details

#await {|temp| ... } ⇒ nil Originally defined in module Features

Waits for the user to press any key.

Examples:

Plain wait

ui.puts 'Press any key to continue…'
ui.await

With temporary prompt

ui.await { ui.puts '[faint]Press any key to continue…' }

Yields:

Yield Parameters:

Returns:

  • (nil)

#choice(*items, abortable: false, selected: nil) ⇒ Object #choice(abortable: false, selected: nil, **pairs) ⇒ Object Originally defined in module Features

Presents a list of options and returns the one the user selects.

In ANSI mode the user navigates with arrow keys and confirms with Enter. In dumb mode items are numbered and the user types the item number.

Examples:

Positional items

answer = ui.choice 'Yes', 'No', 'Cancel'

Positional items

answer = ui.choice 'Yes', 'No', abortable: true do
  ui.puts 'Overwrite the file?'
end

Keyword pairs

action = ui.choice(overwrite: 'Overwrite', skip: 'Skip') do
  ui.puts 'File already exists.'
end

Overloads:

  • #choice(*items, abortable: false, selected: nil) ⇒ Object

    Items are passed as positional arguments; the selected item itself is returned.

    Parameters:

    • items (#to_s, ...) —

      options to choose from

    • abortable (Boolean) (defaults to: false) —

      when true the user can press Esc to cancel

    • selected (defaults to: nil) —

      pre-selected item value, or nil

  • #choice(abortable: false, selected: nil, **pairs) ⇒ Object

    Items are passed as keyword pairs { return_value => label }; the matching key is returned.

    Parameters:

    • abortable (Boolean) (defaults to: false) —

      when true the user can press Esc to cancel

    • selected (defaults to: nil) —

      pre-selected return value, or nil

    • pairs (Hash{Object => #to_s}) —

      map of return values to display labels

Yields:

Yield Parameters:

Returns:

  • (Object) —

    the key of the selected pair, or nil if aborted

#end ⇒ Features

Closes this element and returns the parent element.

Calling end on an already-closed element is a no-op. All output methods on this element become no-ops after end is called.

Examples:

frm = ui.frame 'Results'
ui.puts 'Content'
frm.end   # closes the frame, returns NattyUI (or the parent element)

Returns:

  • (Features) —

    the parent element (or NattyUI if this was the outermost element)



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

def end = NattyUI.__send__(:_end, self)

#error(title, border: :default) {|section| ... } ⇒ Object, Section Originally defined in module Features

Creates a Section with :error styling.

Parameters:

  • title (#to_s) —

    header text

  • border (:default, :rounded, :single, :double, :heavy) (defaults to: :default) —

    border style

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Section) —

    itself, if no block is specified

#fatal(title, border: :default) {|section| ... } ⇒ Object, Section Originally defined in module Features

Creates a Section with :fatal styling.

Parameters:

  • title (#to_s) —

    header text

  • border (:default, :rounded, :single, :double, :heavy) (defaults to: :default) —

    border style

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Section) —

    itself, if no block is specified

#frame(title = nil, border: :default, style: nil) {|frame| ... } ⇒ Object, Frame Originally defined in module Features

Creates a NattyUI::Frame element — a bordered box with an optional title.

Examples:

Manual close

frm = ui.frame 'Preview'
ui.puts 'Content inside the frame.'
frm.end

Block form with title and custom border

ui.frame 'Results', border: :double do
  ui.puts 'All checks passed.'
end

Block form without a title

ui.frame do
  ui.puts 'Framed content.'
end

Parameters:

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

    ANSI style applied to the frame

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

    optional header text

  • border (:default, :rounded, :single, :double, :heavy) (defaults to: :default) —

    border style

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Frame) —

    itself, if no block is specified

#h1(title) ⇒ Features Originally defined in module Features

Prints a level-1 heading.

Parameters:

  • title (#to_s) —

    heading text

Returns:

#h2(title) ⇒ Features Originally defined in module Features

Prints a level-2 heading.

Parameters:

  • title (#to_s) —

    heading text

Returns:

#h3(title) ⇒ Features Originally defined in module Features

Prints a level-3 heading.

Parameters:

  • title (#to_s) —

    heading text

Returns:

#h4(title) ⇒ Features Originally defined in module Features

Prints a level-4 heading.

Parameters:

  • title (#to_s) —

    heading text

Returns:

#h5(title) ⇒ Features Originally defined in module Features

Prints a level-5 heading.

Parameters:

  • title (#to_s) —

    heading text

Returns:

#h6(title) ⇒ Features Originally defined in module Features

Prints a level-6 heading.

Parameters:

  • title (#to_s) —

    heading text

Returns:

#hbars(values, min: nil, max: nil, normalize: false, width: :auto, style: nil, text: true, text_style: nil) ⇒ Features Originally defined in module Features

Prints a horizontal bar chart.

All values must be non-negative.

Examples:

Simple horizontal chart

ui.hbars [3, 7, 2, 9, 5]

Chart without value labels

ui.hbars [10, 40, 25, 60], text: false, normalize: true

Parameters:

  • width (#to_int, Float, :auto) (defaults to: :auto) —

    maximum bar width in characters; a Float is a fraction of available width; :auto fills available width

  • text (Boolean) (defaults to: true) —

    when true prints the numeric value next to each bar

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

    ANSI style applied to the value labels

  • values (#each) —

    collection of non-negative Numeric values

  • min (Numeric, nil) (defaults to: nil) —

    lower bound for scaling; nil uses the data minimum

  • max (Numeric, nil) (defaults to: nil) —

    upper bound for scaling; nil uses the data maximum

  • normalize (Boolean) (defaults to: false) —

    when true applies min-max normalization; when false scales each bar relative to the maximum value

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

    ANSI style applied to the bars

Returns:

Raises:

  • (ArgumentError)

#heading(level, title) ⇒ Features Originally defined in module Features

Prints a heading at the given level.

Six heading levels are supported (similarly to HTML <h1>–<h6>). Use the shorthand helpers #h1–#h6 for convenience.

Examples:

Large heading

ui.heading 1, 'Chapter One'

Sub-heading

ui.heading 3, 'Section [i]Overview[/i]'

Parameters:

  • level (#to_int) —

    heading level, 1 (largest) to 6 (smallest)

  • title (#to_s) —

    heading text

Returns:

#hr(kind = nil) ⇒ Features Originally defined in module Features

Prints a horizontal rule spanning the available width.

Examples:

Default rule

ui.hr

Named style

ui.hr :double

Repeated string

ui.hr '+-'

Parameters:

  • kind (Symbol, #to_s, nil) (defaults to: nil) —
    • nil — default style
    • Symbol — named style: :single, :double, :heavy
    • #to_s — string repeated to fill the available width

Returns:

#information(title, border: :default) {|section| ... } ⇒ Object, Section Also known as: info Originally defined in module Features

Creates a Section with :information styling.

Parameters:

  • title (#to_s) —

    header text

  • border (:default, :rounded, :single, :double, :heavy) (defaults to: :default) —

    border style

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Section) —

    itself, if no block is specified

#ls(*items, compact: true, glyph: nil) ⇒ Features Originally defined in module Features

Prints a multi-column list.

Items are arranged in columns to fit the terminal width.

Examples:

Plain list

ui.ls 'Alice', 'Bob', 'Carol'

Hex-numbered list

ui.ls 'red', 'green', 'blue', glyph: :hex

Parameters:

  • items (#to_s, ...) —

    items to list; nested arrays are flattened

  • compact (Boolean) (defaults to: true) —

    true = ordered in columns, false = ordered left to right per row

  • glyph (defaults to: nil) —

    prefix applied to every item:

    • nil / false — no prefix
    • Integer — decimal counter starting at the given number
    • Symbol — alphabetic sequence starting at the given symbol (e.g. :a → a, b, c, …)
    • :hex — zero-based hex counter (01, 02, …)
    • a #to_s value matching a hex value — hex counter at the given offset (e.g. "0x0a" starts at 0a)
    • any other #to_s value — used as a literal prefix for every item

Returns:

#margin(value) ⇒ Object, Margin #margin(vertical = 0, horizontal = 1) ⇒ Object, Margin #margin(top, horizontal, bottom) ⇒ Object, Margin #margin(top, right, bottom, left) ⇒ Object, Margin #margin(top: 0, right: 0, bottom: 0, left: 0) ⇒ Object, Margin Originally defined in module Features

Creates a Margin element that adds horizontal and vertical whitespace.

Examples:

ui.margin 0, 0.25 do
  ui.puts 'This text has 25% width horizontal margin.'
end

Overloads:

  • #margin(value) ⇒ Object, Margin

    Margin for all sides.

    Parameters:

    • value (#to_int, Float) —

      margin of all four sides

  • #margin(vertical = 0, horizontal = 1) ⇒ Object, Margin

    Seperate vertical and horizontal margin.

    Parameters:

    • vertical (#to_int) (defaults to: 0) —

      top and bottom margin

    • horizontal (#to_int, Float) (defaults to: 1) —

      left and right margin

  • #margin(top, horizontal, bottom) ⇒ Object, Margin

    Seperate top, bottom and horizontal margin.

    Parameters:

    • top (#to_int) —

      top margin

    • horizontal (#to_int, Float) —

      left and right margin

    • bottom (#to_int) —

      bottom margin

  • #margin(top, right, bottom, left) ⇒ Object, Margin

    Seperate margins.

    Parameters:

    • top (#to_int) —

      top margin

    • right (#to_int, Float) —

      right margin

    • bottom (#to_int) —

      bottom margin

    • left (#to_int, Float) —

      left margin

  • #margin(top: 0, right: 0, bottom: 0, left: 0) ⇒ Object, Margin

    Specific margin.

    Parameters:

    • top (#to_int) (defaults to: 0) —

      top margin

    • right (#to_int, Float) (defaults to: 0) —

      right margin

    • bottom (#to_int) (defaults to: 0) —

      bottom margin

    • left (#to_int, Float) (defaults to: 0) —

      left margin

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Margin) —

    itself, if no block is specified

#mark(*text, mark: :default, **popts) ⇒ Features Originally defined in module Features

Prints text with a leading mark symbol.

Examples:

Default mark

ui.mark 'Item one'

Named symbol mark

ui.mark 'Done!', mark: :checkmark

Custom string mark

ui.mark 'Warning', mark: '[bright_red]!'

Parameters:

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

    mark to use as prefix:

    • :default — blue bullet •
    • :checkmark — green check mark ✓
    • :item — dim bullet •
    • any other object — converted via #to_s and used as the literal prefix
  • popts (Hash) —

    a customizable set of print options, see #puts

  • text (#to_s, ...) —

    one or more text values to print

Returns:

#message(title, border: :default) {|section| ... } ⇒ Object, Section Also known as: msg Originally defined in module Features

Creates a Section with :message styling.

Parameters:

  • title (#to_s) —

    header text

  • border (:default, :rounded, :single, :double, :heavy) (defaults to: :default) —

    border style

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Section) —

    itself, if no block is specified

#ok(*text, **popts) ⇒ Features Originally defined in module Features

Prints text with a green check-mark prefix.

Shorthand for mark(*text, mark: :checkmark, **options).

Examples:

ui.ok 'All tests passed'

Parameters:

  • text (#to_s, ...) —

    one or more text values to print

  • popts (Hash) —

    a customizable set of print options, see #puts

Returns:

#pin(*text, mark: :default, **popts) ⇒ Features Originally defined in module Features

Prints text with a mark that persists after a Temporary element closes.

Identical to #mark but survives when the surrounding Temporary element (see #temporary, #task, #progress) is erased.

Examples:

Pin a success note inside a task

ui.task 'Deploy' do
  do_deploy
  ui.pin 'Deployed to production', mark: :checkmark
end

Parameters:

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

    mark to use as prefix:

    • :default — blue bullet •
    • :checkmark — green check mark ✓
    • :item — dim bullet •
    • any other object — converted via #to_s and used as the literal prefix
  • popts (Hash) —

    a customizable set of print options, see #puts

  • text (#to_s, ...) —

    one or more text values to print

Returns:

#progress(*title, max: nil, **popts) {|progress| ... } ⇒ Object, Progress Originally defined in module Features

Creates a Progress element for tracking incremental work.

When max is given the progress is displayed as a percentage bar. When max is nil an open-ended dot animation is shown instead.

Examples:

Bounded progress

ui.progress 'Processing', max: items.size do |bar|
  items.each { process(it); bar.step }
end

Open-ended progress

ui.progress 'Working…' do |bar|
  loop { bar.step; break if done? }
end

Parameters:

  • max (Numeric, nil) (defaults to: nil) —

    maximum value

  • title (#to_s, nil) —

    optional header text

  • popts (Hash) —

    a customizable set of print options, see #puts

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Progress) —

    itself when no block is given

#query(**options) {|temp| ... } ⇒ Object Originally defined in module Features

Waits for a key event and returns information about it.

Key names are strings such as "a", "Enter", "Esc", "Back", "Shift+Alt+F1".

Examples:

answer = ui.query yes: 'y', no: 'n'
ui.puts answer == :yes ? 'Confirmed!' : 'Cancelled.'

With a temporary prompt

answer = ui.query(yes: 'y', no: 'n') do
  ui.puts 'Continue? ([b]y[/b]/[b]n[/b])'
end

Parameters:

  • options (Hash<Object => String, #each>) —

    map of return values to key names or enumerables of key names; e.g. { yes: 'y', no: %w[n Esc] }

Yields:

Yield Parameters:

Returns:

  • (Object) —

    matched option key

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

Prints text with a left-side quotation border.

Examples:

ui.quote "To be or not to be,\nthat is the question."

Parameters:

  • text (#to_s, ...) —

    one or more text values to print

  • popts (Hash) —

    a customizable set of print options

Returns:

#run(*cmd, env = {}, shell: false, input: nil, max_lines: 10, **spawn_options) ⇒ Array(Process::Status, Array<String>, Array<String>)? Originally defined in module Features

Executes a shell command, captures its output, and returns it.

Stdout and stderr lines are displayed in a scrolling region limited to max_lines. All other arguments are identical to #sh.

Examples:

Capture and inspect output

status, out, err = ui.run 'ls', '-la'
ui.puts "exit #{status.exitstatus}"

Limit displayed lines and pipe input

File.open('data.txt') { |f| ui.run 'wc', '-l', input: f, max_lines: 5 }

Parameters:

  • max_lines (#to_int) (defaults to: 10) —

    maximum number of output lines shown at once

Returns:

  • (Array(Process::Status, Array<String>, Array<String>)) —

    three-element array of exit status, stdout lines, and stderr lines

  • (nil) —

    when the command could not be started

#section(title = nil, type: :default, border: :default) {|section| ... } ⇒ Object, Section Also known as: begin Originally defined in module Features

Creates a Section element — a bordered container with an optional title.

Examples:

Manual close

sec = ui.section 'Results'
ui.ok 'All good'
sec.end

Block form with title

ui.section 'Summary' do
  ui.puts '3 files processed.'
end

Block form without title

ui.section do
  ui.puts 'Anonymous section content.'
end

Parameters:

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

    optional header text

  • type (:default, :message, :information, :warning, :error, :fatal) (defaults to: :default) —

    visual style of the section

  • border (:default, :rounded, :single, :double, :heavy) (defaults to: :default) —

    border style

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Section) —

    itself, if no block is specified

#select(*items, abortable: false, selected: nil) ⇒ Array #select(abortable: false, selected: nil, **pairs) ⇒ Array Originally defined in module Features

Presents a list of options and returns all items the user selects.

In ANSI mode the user toggles items with Space and confirms with Enter. In dumb mode items are numbered and the user types item numbers.

Examples:

Positional items

picks = ui.select 'Kitty', 'iTerm2', 'Ghostty'

Positional items with all pre-selected

picks = ui.select 'A', 'B', 'C', selected: :all do
  ui.puts 'Choose features to enable:'
end

Keyword pairs

flags = ui.select verbose: 'Verbose', debug: 'Debug', trace: 'Trace'

Overloads:

  • #select(*items, abortable: false, selected: nil) ⇒ Array

    Items are passed as positional arguments; the selected items themselves are returned.

    Parameters:

    • items (#to_s, ...) —

      options to choose from

    • abortable (Boolean) (defaults to: false) —

      when true the user can press Esc to cancel

    • selected (nil, :all, #each) (defaults to: nil) —

      pre-selected items: nil = none, :all = all, or an enumerable of item values to pre-select

  • #select(abortable: false, selected: nil, **pairs) ⇒ Array

    Items are passed as keyword pairs { return_value => label }; the matching keys are returned.

    Parameters:

    • abortable (Boolean) (defaults to: false) —

      when true the user can press Esc to cancel

    • selected (nil, :all, #each) (defaults to: nil)
    • pairs (Hash{Object => #to_s}) —

      map of return values to labels

Yields:

Yield Parameters:

Returns:

  • (Array) —

    keys of selected pairs, or nil if aborted

#sh(*cmd, env = {}, shell: false, input: nil, **spawn_options) ⇒ Object Originally defined in module Features

Executes a shell command and prints its output to the terminal.

All arguments and options are forwarded to Terminal.sh, which in turn uses Process.spawn.

Examples:

Run a simple command

ui.sh 'echo "Hello Ruby!"'

Pipe a string as stdin

ui.sh 'cat', input: 'Hello from stdin'

Parameters:

  • cmd (#to_s, ...) —

    command and arguments, same as Process.spawn

  • env (Hash, nil) (defaults to: {}) —

    additional environment variables

  • shell (Boolean) (defaults to: false) —

    when true runs the command through a system shell

  • input (defaults to: nil) —

    piped standard input; accepts any object with #readpartial, #to_io, #each, #to_a, or anything IO.write accepts (e.g. a String)

  • spawn_options (Hash) —

    additional options forwarded to Process.spawn

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

Prints one or more blank lines.

Examples:

Print a single blank line

ui.space

Print three blank lines

ui.space 3

Parameters:

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

    number of blank lines to print

Returns:

#table(**options) {|table| ... } ⇒ Features Originally defined in module Features

Renders a Table to the terminal.

The method yields a Table object for population; if no block is given nothing is rendered.

Border name symbols: :rounded (default), :single, :double, :heavy, :single_double, :double_single, :single_heavy, :heavy_single

Examples:

Simple table with a double outer frame

ui.table border_frame: :double do |t|
  t.add_row '[b]Name', '[b]Score', align: :center
  t.add_row 'Alice', 42
  t.add_row 'Bob',   17
end

Parameters:

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :border (:default, :none, :single, :double, :heavy) — default: :default —

    default border used for all border parts

  • :border_frame (nil, :none, :single, :double, :heavy) —

    outer frame; falls back to :border

  • :border_vertical (nil, :none, :single, :double, :heavy) —

    vertical column separators; falls back to :border

  • :border_horizontal (nil, :none, :single, :double, :heavy) —

    horizontal row separators; falls back to :border

  • :border_style (Symbol, String, Array<Style>, Array<String>, nil) —

    ANSI style applied to all borders

  • :frame (Symbol, Array<Symbol>) — default: :all —

    which frame sides to draw: :all or an enumerable of :top, :right, :bottom, :left

  • :width (#to_int, Float, :max, nil) —

    :max expands to the full terminal width; a negative #to_int is an offset from the terminal width; a Float is a fraction of the terminal width

Yields:

  • (table) —

    a Table instance to populate with rows and cells

Yield Parameters:

  • table (Table) —

    the table

Returns:

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

Creates a Task element — a labelled step that shows a spinner while running and a check mark on success.

Examples:

Manual close

t = ui.task 'Installing dependencies'
run_install
t.end

Block form

ui.task 'Installing dependencies' do
  run_install
end

Parameters:

  • title (#to_s) —

    task description

  • pin (Boolean) (defaults to: false) —

    whether the task title should be pinned

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Task) —

    itself, if no block is specified

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

Creates a Temporary element whose output is erased when it closes.

Examples:

Manual close

tmp = ui.temporary
ui.puts 'Loading…'
sleep 1
tmp.end   # erases "Loading…"

Block form

ui.temporary do
  ui.puts 'Thinking…'
  sleep 2
end  # "Thinking…" is erased here

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Temporary) —

    itself, if no block is specified

#vbars(values, min: nil, max: nil, normalize: false, height: 10, bar_width: 3, style: nil) ⇒ Features Originally defined in module Features

Prints a vertical bar chart.

All values must be non-negative.

Examples:

Simple bar chart

ui.vbars [3, 7, 2, 9, 5]

Normalised chart with custom height

ui.vbars [10, 40, 25, 60], normalize: true, height: 15

Parameters:

  • values (#each) —

    collection of non-negative Numeric values

  • min (Numeric, nil) (defaults to: nil) —

    lower bound for scaling; nil uses the data minimum

  • max (Numeric, nil) (defaults to: nil) —

    upper bound for scaling; nil uses the data maximum

  • normalize (Boolean) (defaults to: false) —

    when true applies min-max normalization; when false scales each bar relative to the maximum value

  • height (#to_int) (defaults to: 10) —

    chart height in lines (minimum 3; default: 10)

  • bar_width (#to_int, :auto) (defaults to: 3) —

    width of each bar in characters; :auto fits the graph in available terminal width

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

    ANSI style applied to the bars

Returns:

Raises:

  • (ArgumentError)

#warning(title, border: :default) {|section| ... } ⇒ Object, Section Also known as: warn Originally defined in module Features

Creates a Section with :warning styling.

Parameters:

  • title (#to_s) —

    header text

  • border (:default, :rounded, :single, :double, :heavy) (defaults to: :default) —

    border style

Yields:

Yield Parameters:

Returns:

  • (Object) —

    return value of the block

  • (Section) —

    itself, if no block is specified