Module: NattyUI::Features

Included in:
Wrapper, Wrapper::Element
Defined in:
lib/natty-ui/wrapper/features.rb,
lib/natty-ui/wrapper/ask.rb,
lib/natty-ui/wrapper/task.rb,
lib/natty-ui/wrapper/query.rb,
lib/natty-ui/wrapper/quote.rb,
lib/natty-ui/wrapper/table.rb,
lib/natty-ui/wrapper/framed.rb,
lib/natty-ui/wrapper/animate.rb,
lib/natty-ui/wrapper/heading.rb,
lib/natty-ui/wrapper/message.rb,
lib/natty-ui/wrapper/request.rb,
lib/natty-ui/wrapper/section.rb,
lib/natty-ui/wrapper/progress.rb,
lib/natty-ui/wrapper/horizontal_rule.rb,
lib/natty-ui/wrapper/list_in_columns.rb

Overview

Features of NattyUI - methods to display natty elements.

Defined Under Namespace

Classes: Table

Instance Method Summary collapse

Instance Method Details

#animate(..., animation: :default) ⇒ Wrapper::Section, Wrapper

Print given arguments line-wise with animation.

Returns it's parent object.

Parameters:

  • ... (#to_s) —

    objects to print

  • animation (:binary, :default, :matrix, :rainbow, :type_writer) (defaults to: :default) —

    type of animation

Returns:



12
13
14
15
 
# File 'lib/natty-ui/wrapper/animate.rb', line 12

def animate(*args, **kwargs)
  kwargs[:animation] ||= :default
  puts(*args, **kwargs)
end

#ask(question, yes: "jotsyd\r\n", no: 'n') ⇒ Boolean?

Ask a yes/no question from user.

The defaults for yes and no will work for Afrikaans, Dutch, English, French, German, Italian, Polish, Portuguese, Romanian, Spanish and Swedish.

The default for yes includes ENTER and RETURN key

Examples:

case ui.ask('Do you like the NattyUI gem?')
when true
  ui.info('Yeah!!')
when false
  ui.write("That's pity!")
else
  ui.failed('You should have an opinion!')
end

Parameters:

  • question (#to_s) —

    Question to display

  • yes (#to_s) (defaults to: "jotsyd\r\n") —

    chars which will be used to answer 'Yes'

  • no (#to_s) (defaults to: 'n') —

    chars which will be used to answer 'No'

Returns:

  • (Boolean) —

    whether the answer is yes or no

  • (nil) —

    when input was aborted with ^C or ^D

See Also:



32
33
34
 
# File 'lib/natty-ui/wrapper/ask.rb', line 32

def ask(question, yes: "jotsyd\r\n", no: 'n')
  _element(:Ask, question, yes, no)
end

#completed(title, *args) {|message| ... } ⇒ Object, Wrapper::Message Also known as: done, ok

Creates a completion message section with a highlighted title and prints given additional arguments as lines into the section.

When used for a #task section it closes this section with status :ok.

Parameters:

  • title (#to_s) —

    object to print as section title

  • args (Array<#to_s>) —

    more objects to print

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Message) —

    itself, when no code block is given



63
64
65
 
# File 'lib/natty-ui/wrapper/message.rb', line 63

def completed(title, *args, &block)
  _section(:Message, args, title: title, glyph: :completed, &block)
end

#error(title, *args) {|message| ... } ⇒ Object, Wrapper::Message Also known as: err

Creates a error message section with a highlighted title and prints given additional arguments as lines into the section.

Parameters:

  • title (#to_s) —

    object to print as section title

  • args (Array<#to_s>) —

    more objects to print

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Message) —

    itself, when no code block is given



50
51
52
 
# File 'lib/natty-ui/wrapper/message.rb', line 50

def error(title, *args, &block)
  _section(:Message, args, title: title, glyph: :error, &block)
end

#failed(title, *args) {|message| ... } ⇒ Object, Wrapper::Message

Creates a failure message section with a highlighted title and prints given additional arguments as lines into the section.

When used for a #task section it closes this section with status :failed.

Parameters:

  • title (#to_s) —

    object to print as section title

  • args (Array<#to_s>) —

    more objects to print

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Message) —

    itself, when no code block is given



78
79
80
 
# File 'lib/natty-ui/wrapper/message.rb', line 78

def failed(title, *args, &block)
  _section(:Message, args, title: title, glyph: :failed, &block)
end

#framed(*args, type: :default) {|framed| ... } ⇒ Object, Wrapper::Framed

Creates frame-enclosed section with a highlighted title and prints given additional arguments as lines into the section.

When no block is given, the section must be closed, see Wrapper::Element#close.

Parameters:

  • args (Array<#to_s>) —

    more objects to print

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

    frame type; see NattyUI::Frame

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Framed) —

    itself, when no code block is given



18
19
20
 
# File 'lib/natty-ui/wrapper/framed.rb', line 18

def framed(*args, type: :default, &block)
  _section(:Framed, args, type: NattyUI::Frame[type], &block)
end

#h1(title, space: 0) ⇒ Wrapper::Section, Wrapper

Prints a H1 title.

Parameters:

  • title (#to_s) —

    text

  • space (#to_i) (defaults to: 0) —

    space around the heading

Returns:



12
 
# File 'lib/natty-ui/wrapper/heading.rb', line 12

def h1(title, space: 0) = _element(:Heading, title, space, '═══════')

#h2(title, space: 0) ⇒ Wrapper::Section, Wrapper

Prints a H2 title.

Parameters:

  • title (#to_s) —

    text

  • space (#to_i) (defaults to: 0) —

    space around the heading

Returns:



18
 
# File 'lib/natty-ui/wrapper/heading.rb', line 18

def h2(title, space: 0) = _element(:Heading, title, space, '━━━━━')

#h3(title, space: 0) ⇒ Wrapper::Section, Wrapper

Prints a H3 title.

Parameters:

  • title (#to_s) —

    text

  • space (#to_i) (defaults to: 0) —

    space around the heading

Returns:



24
 
# File 'lib/natty-ui/wrapper/heading.rb', line 24

def h3(title, space: 0) = _element(:Heading, title, space, '━━━')

#h4(title, space: 0) ⇒ Wrapper::Section, Wrapper

Prints a H4 title.

Parameters:

  • title (#to_s) —

    text

  • space (#to_i) (defaults to: 0) —

    space around the heading

Returns:



30
 
# File 'lib/natty-ui/wrapper/heading.rb', line 30

def h4(title, space: 0) = _element(:Heading, title, space, '───')

#h5(title, space: 0) ⇒ Wrapper::Section, Wrapper

Prints a H5 title.

Parameters:

  • title (#to_s) —

    text

  • space (#to_i) (defaults to: 0) —

    space around the heading

Returns:



36
 
# File 'lib/natty-ui/wrapper/heading.rb', line 36

def h5(title, space: 0) = _element(:Heading, title, space, '──')

#hr(symbol = '─') ⇒ Wrapper::Section, Wrapper

Print a horizontal rule

Parameters:

  • symbol (#to_s) (defaults to: '─') —

    string to build the horizontal rule

Returns:



11
 
# File 'lib/natty-ui/wrapper/horizontal_rule.rb', line 11

def hr(symbol = '─') = _element(:HorizontalRule, symbol)

#information(title, *args) {|message| ... } ⇒ Object, Wrapper::Message Also known as: info

Creates a informational message section with a highlighted title and prints given additional arguments as lines into the section.

Parameters:

  • title (#to_s) —

    object to print as section title

  • args (Array<#to_s>) —

    more objects to print

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Message) —

    itself, when no code block is given



28
29
30
 
# File 'lib/natty-ui/wrapper/message.rb', line 28

def information(title, *args, &block)
  _section(:Message, args, title: title, glyph: :information, &block)
end

#ls(*args, compact: true, glyph: nil) ⇒ Wrapper, Wrapper::Element

Print items of a given list as columns. In the default compact format columns may have diffrent widths and the list items are ordered column-wise. The non-compact format prints all columns in same width and order the list items row-wise.

Examples:

simple compact list

ui.ls('apple', 'banana', 'blueberry', 'pineapple', 'strawberry')
# => apple   banana   blueberry   pineapple   strawberry

(unordered) list with red dot

ui.ls('apple', 'banana', 'blueberry', 'pineapple', 'strawberry', glyph: '[red]•[/]')
# => • apple   • banana   • blueberry   • pineapple   • strawberry

ordered list

ui.ls('apple', 'banana', 'blueberry', 'pineapple', 'strawberry', glyph: 1)
# => 1 apple   2 banana   3 blueberry   4 pineapple   5 strawberry

ordered list, start at 100

ui.ls('apple', 'banana', 'blueberry', 'pineapple', 'strawberry', glyph: 100)
# => 100 apple   101 banana   102 blueberry   103 pineapple   104 strawberry

ordered list using, uppercase characters

ui.ls('apple', 'banana', 'blueberry', 'pineapple', 'strawberry', glyph: :A)
# => A apple   B banana   C blueberry   D pineapple   E strawberry

ordered list, using lowercase characters

ui.ls('apple', 'banana', 'blueberry', 'pineapple', 'strawberry', glyph: :a)
# => a apple   b banana   c blueberry   d pineapple   e strawberry

Parameters:

  • args (Array<#to_s>) —

    items to print

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

    whether to use compact format

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

    optional glyph used as element prefix

Returns:



43
44
45
 
# File 'lib/natty-ui/wrapper/list_in_columns.rb', line 43

def ls(*args, compact: true, glyph: nil)
  _element(:ListInColumns, args, compact, glyph)
end

#message(title, *args, glyph: :default) {|message| ... } ⇒ Object, Wrapper::Message Also known as: msg

Creates a section with a highlighted title and prints given additional arguments as lines into the section.

Parameters:

  • title (#to_s) —

    object to print as section title

  • args (Array<#to_s>) —

    more objects to print

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

    used for the title; see Glyph

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Message) —

    itself, when no code block is given



16
17
18
 
# File 'lib/natty-ui/wrapper/message.rb', line 16

def message(title, *args, glyph: :default, &block)
  _section(:Message, args, title: title, glyph: glyph, &block)
end

#pairs(seperator = ': ', **kwargs) ⇒ Wrapper::Section, Wrapper

Table-like display of key/value pairs.

Examples:

ui.pairs(apple: '1$', banana: '2$', kiwi: '1.5$')

# output:
#  apple: 1$
# banana: 2$
#   kiwi: 1.5$

Parameters:

  • seperator (#to_s) (defaults to: ': ')
  • kwargs (Hash<#to_s,#to_s>)

Returns:



80
81
82
 
# File 'lib/natty-ui/wrapper/table.rb', line 80

def pairs(seperator = ': ', **kwargs)
  kwargs.empty? ? self : _element(:Pairs, kwargs, seperator)
end

#progress(title, max_value: nil, spinner: :default) ⇒ Wrapper::Progress

Creates progress element implementing additional ProgressAttributes.

When a max_value is given, the progress will by displayed as a bar. Otherwise the spinner is used for a little animation.

When no pre-defined spinner is specified then spinner will be used char-wise as a string for the progress animation.

A progress element has additional states and can be closed with #completed or #failed.

Parameters:

  • title (#to_s) —

    object to print as progress title

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

    maximum value of the progress

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

    spinner type; see Spinner

Returns:



23
24
25
 
# File 'lib/natty-ui/wrapper/progress.rb', line 23

def progress(title, max_value: nil, spinner: :default)
  _element(:Progress, title, max_value, )
end

#query(question, *choices, result: :char, display: :list, **kw_choices) ⇒ Char, ...

Request a choice from user.

Examples:

Select by Index

choice = ui.query(
  'Which fruits do you prefer?',
  'Apples',
  'Bananas',
  'Cherries'
)
# => '1' or '2' or '3' or nil if user aborted

Select by given char

choice = ui.query(
  'Which fruits do you prefer?',
  a: 'Apples',
  b: 'Bananas',
  c: 'Cherries'
)
# => 'a' or 'b' or 'c' or nil if user aborted

Parameters:

  • question (#to_s) —

    Question to display

  • choices (#to_s) —

    choices selectable via index (0..9)

  • result (Symbol) (defaults to: :char) —

    defines how the result will be returned

  • display (Symbol) (defaults to: :list) —

    display choices as :list or :compact

  • kw_choices ({Char => #to_s}) —

    choices selectable with given char

Returns:

  • (Char) —

    when result is configured as :char

  • (#to_s) —

    when result is configured as :choice

  • ([Char, #to_s]) —

    when result is configured as :both

  • (nil) —

    when input was aborted with ^C or ^D

See Also:



38
39
40
 
# File 'lib/natty-ui/wrapper/query.rb', line 38

def query(question, *choices, result: :char, display: :list, **kw_choices)
  _element(:Query, question, choices, kw_choices, result, display)
end

#quote(*args) {|section| ... } ⇒ Object, Wrapper::Quote

Creates a quotation section and prints given arguments as lines into the section.

Parameters:

  • args (Array<#to_s>) —

    optional objects to print

  • prefix (String) —

    used for each printed line

  • suffix (String) —

    used for each printed line

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Quote) —

    itself, when no code block is given



14
 
# File 'lib/natty-ui/wrapper/quote.rb', line 14

def quote(*args, &block) = _section(:Quote, args, prefix: '▍ ', &block)

#request(question, password: false) ⇒ String?

Request user input.

Parameters:

  • question (#to_s) —

    Question to display

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

    whether to hide the input

Returns:

  • (String) —

    the user input

  • (nil) —

    when input was aborted with ^C or ^D



13
14
15
 
# File 'lib/natty-ui/wrapper/request.rb', line 13

def request(question, password: false)
  _element(:Request, question, password)
end

#section(*args, prefix: ' ', suffix: ' ') {|section| ... } ⇒ Object, Wrapper::Section Also known as: sec

Creates a default section and prints given arguments as lines into the section.

Parameters:

  • args (Array<#to_s>) —

    optional objects to print

  • prefix (String) (defaults to: ' ') —

    used for each printed line

  • suffix (String) (defaults to: ' ') —

    used for each printed line

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Section) —

    itself, when no code block is given



16
17
18
 
# File 'lib/natty-ui/wrapper/section.rb', line 16

def section(*args, prefix: '  ', suffix: '  ', &block)
  _section(:Section, args, prefix: prefix, suffix: suffix, &block)
end

#table(*args, type: :default, expand: false) ⇒ Wrapper::Section, Wrapper #table(type: :default, expand: false) ⇒ Wrapper::Section, Wrapper

Table view of data.

Overloads:

  • #table(*args, type: :default, expand: false) ⇒ Wrapper::Section, Wrapper

    Display the given arrays as rows of a table.

    Examples:

    ui.table(
  %w[name price origin],
  %w[apple 1$ California],
  %w[banana 2$ Brasil],
  %w[kiwi 1.5$ Newzeeland]
)

# name   │ price │ origin
# ───────┼───────┼───────────
# apple  │ 1$    │ California
# ───────┼───────┼───────────
# banana │ 2$    │ Brasil
# ───────┼───────┼───────────
# kiwi   │ 1.5$  │ Newzeeland

    Parameters:

    • args (#map<#map<#to_s>>) —

      one or more arrays representing rows of the table

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

      frame type; see NattyUI::Frame

    • expand (false, true. :equal) (defaults to: false)
  • #table(type: :default, expand: false) ⇒ Wrapper::Section, Wrapper

    Construct and display a table.

    Examples:

    ui.table(type: :heavy, expand: true) do |table|
  table.add('name', 'price', 'origin', style: 'bold green')
  table.add('apple', '1$', 'California')
  table.add('banana', '2$', 'Brasil')
  table.add('kiwi', '1.5$', 'Newzeeland')
  table.align_column(0, :right).align_row(0, :center)
end

#       name       ┃      price     ┃            origin
# ━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#            apple ┃ 1$             ┃ California
# ━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#           banana ┃ 2$             ┃ Brasil
# ━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#             kiwi ┃ 1.5$           ┃ Newzeeland

    Parameters:

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

      frame type; see NattyUI::Frame

    • expand (false, true. :equal) (defaults to: false)

Yields:

  • (Table) —

    table construction helper

Returns:



58
59
60
61
62
63
 
# File 'lib/natty-ui/wrapper/table.rb', line 58

def table(*table, type: :default, expand: false)
  type = NattyUI::Frame[type]
  table = Table.create(*table)
  yield(table) if block_given?
  _element(:Table, table, type, expand)
end

#task(title, *args) {|task| ... } ⇒ Object, Wrapper::Task

Creates task section implementing additional ProgressAttributes.

A task section has additional states and can be closed with #completed or #failed.

Parameters:

  • title (#to_s) —

    object to print as section title

  • args (Array<#to_s>) —

    more objects to print

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Task) —

    itself, when no code block is given



17
18
19
 
# File 'lib/natty-ui/wrapper/task.rb', line 17

def task(title, *args, &block)
  _section(:Task, args, title: title, &block)
end

#warning(title, *args) {|message| ... } ⇒ Object, Wrapper::Message Also known as: warn

Creates a warning message section with a highlighted title and prints given additional arguments as lines into the section.

Parameters:

  • title (#to_s) —

    object to print as section title

  • args (Array<#to_s>) —

    more objects to print

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Message) —

    itself, when no code block is given



39
40
41
 
# File 'lib/natty-ui/wrapper/message.rb', line 39

def warning(title, *args, &block)
  _section(:Message, args, title: title, glyph: :warning, &block)
end