Class: NattyUI::Wrapper::Element

Inherits:

Object

• Object
• NattyUI::Wrapper::Element

Includes:

Features

Defined in:

lib/natty-ui/wrapper/element.rb

Overview

Basic visual element.

Direct Known Subclasses

Ask, Heading, HorizontalRule, ListInColumns, Pairs, Progress, Query, Request, Section, Table

Instance Attribute Summary

• #available_width ⇒ Integer readonly

  Available columns count within the element.

• #closed? ⇒ Boolean readonly

  Whether its closed or not.

• #parent ⇒ Section, Wrapper readonly

  Parent element.

• #status ⇒ Symbol^? readonly

  Status when closed.

• #wrapper ⇒ Wrapper readonly

  Assigned output stream wrapper.

Instance Method Summary

• #animate(..., animation: :default) ⇒ Wrapper::Section, Wrapper included from Features

  Print given arguments line-wise with animation.

• #ask(question, yes: "jotsyd\r\n", no: 'n') ⇒ Boolean^? included from Features

  Ask a yes/no question from user.

• #close ⇒ Element

  Close the element.

• #completed(title, *args) {|message| ... } ⇒ Object, Wrapper::Message (also: #done, #ok) included from Features

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

• #error(title, *args) {|message| ... } ⇒ Object, Wrapper::Message (also: #err) included from Features

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

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

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

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

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

• #h1(title, space: 0) ⇒ Wrapper::Section, Wrapper included from Features

  Prints a H1 title.

• #h2(title, space: 0) ⇒ Wrapper::Section, Wrapper included from Features

  Prints a H2 title.

• #h3(title, space: 0) ⇒ Wrapper::Section, Wrapper included from Features

  Prints a H3 title.

• #h4(title, space: 0) ⇒ Wrapper::Section, Wrapper included from Features

  Prints a H4 title.

• #h5(title, space: 0) ⇒ Wrapper::Section, Wrapper included from Features

  Prints a H5 title.

• #hr(symbol = '─') ⇒ Wrapper::Section, Wrapper included from Features

  Print a horizontal rule.

• #information(title, *args) {|message| ... } ⇒ Object, Wrapper::Message (also: #info) included from Features

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

• #ls(*args, compact: true, glyph: nil) ⇒ Wrapper, Wrapper::Element included from Features

  Print items of a given list as columns.

• #message(title, *args, glyph: :default) {|message| ... } ⇒ Object, Wrapper::Message (also: #msg) included from Features

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

• #pairs(seperator = ': ', **kwargs) ⇒ Wrapper::Section, Wrapper included from Features

  Table-like display of key/value pairs.

• #progress(title, max_value: nil, spinner: :default) ⇒ Wrapper::Progress included from Features

  Creates progress element implementing additional ProgressAttributes.

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

  Request a choice from user.

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

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

• #request(question, password: false) ⇒ String^? included from Features

  Request user input.

• #section(*args, prefix: ' ', suffix: ' ') {|section| ... } ⇒ Object, Wrapper::Section (also: #sec) included from Features

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

• #table(*table, type: :default, expand: false) {|Table| ... } ⇒ Wrapper::Section, Wrapper included from Features

  Table view of data.

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

  Creates task section implementing additional ProgressAttributes.

• #warning(title, *args) {|message| ... } ⇒ Object, Wrapper::Message (also: #warn) included from Features

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

Instance Attribute Details

#available_width ⇒ Integer (readonly)

Returns available columns count within the element.

Returns:

• (Integer) —

  available columns count within the element

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

def available_width = @parent.available_width

#closed? ⇒ Boolean (readonly)

Returns whether its closed or not.

Returns:

• (Boolean) —

  whether its closed or not

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

def closed? = (@status != nil)

#parent ⇒ Section, Wrapper (readonly)

Returns parent element.

Returns:

• (Section, Wrapper) —

  parent element

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

def parent
  @parent
end

#status ⇒ Symbol^? (readonly)

Returns status when closed.

Returns:

• (Symbol, nil) —

  status when closed

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

def status
  @status
end

#wrapper ⇒ Wrapper (readonly)

Returns assigned output stream wrapper.

Returns:

• (Wrapper) —

  assigned output stream wrapper

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

def wrapper
  return @wrapper if @wrapper
  @wrapper = @parent
  @wrapper = @wrapper.parent until @wrapper.is_a?(Wrapper)
  @wrapper
end

Instance Method Details

#animate(..., animation: :default) ⇒ Wrapper::Section, Wrapper Originally defined in module Features

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:

• (Wrapper::Section, Wrapper) —

  it's parent object

#ask(question, yes: "jotsyd\r\n", no: 'n') ⇒ Boolean^? Originally defined in module Features

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:

• NattyUI.in_stream

#close ⇒ Element

Close the element.

Returns:

• (Element) —

  itself

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

def close = _close(:closed)

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

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:

• message (Wrapper::Message) —

  the created section

Returns:

• (Object) —

  the result of the code block

• (Wrapper::Message) —

  itself, when no code block is given

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

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:

• message (Wrapper::Message) —

  the created section

Returns:

• (Object) —

  the result of the code block

• (Wrapper::Message) —

  itself, when no code block is given

#failed(title, *args) {|message| ... } ⇒ Object, Wrapper::Message Originally defined in module Features

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:

• message (Wrapper::Message) —

  the created section

Returns:

• (Object) —

  the result of the code block

• (Wrapper::Message) —

  itself, when no code block is given

#framed(*args, type: :default) {|framed| ... } ⇒ Object, Wrapper::Framed Originally defined in module Features

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:

• framed (Wrapper::Framed) —

  the created section

Returns:

• (Object) —

  the result of the code block

• (Wrapper::Framed) —

  itself, when no code block is given

#h1(title, space: 0) ⇒ Wrapper::Section, Wrapper Originally defined in module Features

Prints a H1 title.

Parameters:

• title (#to_s) —

  text

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

  space around the heading

Returns:

• (Wrapper::Section, Wrapper) —

  it's parent object

#h2(title, space: 0) ⇒ Wrapper::Section, Wrapper Originally defined in module Features

Prints a H2 title.

Parameters:

• title (#to_s) —

  text

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

  space around the heading

Returns:

• (Wrapper::Section, Wrapper) —

  it's parent object

#h3(title, space: 0) ⇒ Wrapper::Section, Wrapper Originally defined in module Features

Prints a H3 title.

Parameters:

• title (#to_s) —

  text

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

  space around the heading

Returns:

• (Wrapper::Section, Wrapper) —

  it's parent object

#h4(title, space: 0) ⇒ Wrapper::Section, Wrapper Originally defined in module Features

Prints a H4 title.

Parameters:

• title (#to_s) —

  text

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

  space around the heading

Returns:

• (Wrapper::Section, Wrapper) —

  it's parent object

#h5(title, space: 0) ⇒ Wrapper::Section, Wrapper Originally defined in module Features

Prints a H5 title.

Parameters:

• title (#to_s) —

  text

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

  space around the heading

Returns:

• (Wrapper::Section, Wrapper) —

  it's parent object

#hr(symbol = '─') ⇒ Wrapper::Section, Wrapper Originally defined in module Features

Print a horizontal rule

Parameters:

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

  string to build the horizontal rule

Returns:

• (Wrapper::Section, Wrapper) —

  it's parent object

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

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:

• message (Wrapper::Message) —

  the created section

Returns:

• (Object) —

  the result of the code block

• (Wrapper::Message) —

  itself, when no code block is given

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

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:

• (Wrapper, Wrapper::Element) —

  itself

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

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:

• message (Wrapper::Message) —

  the created section

Returns:

• (Object) —

  the result of the code block

• (Wrapper::Message) —

  itself, when no code block is given

#pairs(seperator = ': ', **kwargs) ⇒ Wrapper::Section, Wrapper Originally defined in module Features

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:

• (Wrapper::Section, Wrapper) —

  it's parent object

#progress(title, max_value: nil, spinner: :default) ⇒ Wrapper::Progress Originally defined in module Features

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:

• (Wrapper::Progress) —

  the created progress element

#query(question, *choices, result: :char, display: :list, **kw_choices) ⇒ Char, ... Originally defined in module Features

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:

• NattyUI.in_stream

#quote(*args) {|section| ... } ⇒ Object, Wrapper::Quote Originally defined in module Features

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:

• section (Wrapper::Section) —

  the created section

Returns:

• (Object) —

  the result of the code block

• (Wrapper::Quote) —

  itself, when no code block is given

#request(question, password: false) ⇒ String^? Originally defined in module Features

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

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

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:

• section (Wrapper::Section) —

  the created section

Returns:

• (Object) —

  the result of the code block

• (Wrapper::Section) —

  itself, when no code block is given

#table(*args, type: :default, expand: false) ⇒ Wrapper::Section, Wrapper #table(type: :default, expand: false) ⇒ Wrapper::Section, Wrapper Originally defined in module Features

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:

• (Wrapper::Section, Wrapper) —

  it's parent object

#task(title, *args) {|task| ... } ⇒ Object, Wrapper::Task Originally defined in module Features

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:

• task (Wrapper::Task) —

  the created section

Returns:

• (Object) —

  the result of the code block

• (Wrapper::Task) —

  itself, when no code block is given

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

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:

• message (Wrapper::Message) —

  the created section

Returns:

• (Object) —

  the result of the code block

• (Wrapper::Message) —

  itself, when no code block is given