Class: NattyUI::Wrapper

Inherits:
Object
  • Object
show all
Includes:
Features
Defined in:
lib/natty-ui/wrapper.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/element.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

Helper class to wrap an output stream and implement all Features.

Defined Under Namespace

Classes: Ask, Element, Framed, Heading, HorizontalRule, ListInColumns, Message, Pairs, Progress, Query, Quote, Request, Section, Table, Task

Instance Attribute Summary collapse

Tool functions collapse

Instance Method Summary collapse

Instance Attribute Details

#ansi? ⇒ Boolean (readonly)

Returns whether ANSI is supported.

Returns:

  • (Boolean) —

    whether ANSI is supported



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

def ansi? = false

#screen_columns ⇒ Integer (readonly) Also known as: available_width, rcol

Returns number of screen columns.

Returns:

  • (Integer) —

    number of screen columns



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

def screen_columns = screen_size[1]

#screen_rows ⇒ Integer (readonly)

Returns number of screen rows.

Returns:

  • (Integer) —

    number of screen rows



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

def screen_rows = screen_size[0]

#screen_size ⇒ [Integer, Integer] (readonly)

Returns screen size as rows and columns.

Returns:

  • ([Integer, Integer]) —

    screen size as rows and columns



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

def screen_size = (@screen_size ||= determine_screen_size)

#stream ⇒ IO (readonly)

Returns IO stream used for output.

Returns:

  • (IO) —

    IO stream used for output



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

def stream
  @stream
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:

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

#cls ⇒ Wrapper

Clear Screen

Returns:



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

def cls = self

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

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:

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:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Message) —

    itself, when no code block is given

#framed(*args, type: :rounded) {|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 (:double, :heavy, :rounded, :semi, :simple) (defaults to: :rounded) —

    frame type

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Framed) —

    itself, when no code block is given

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

Prints a H1 title.

Parameters:

  • title (#to_s) —

    text

Returns:

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

Prints a H2 title.

Parameters:

  • title (#to_s) —

    text

Returns:

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

Prints a H3 title.

Parameters:

  • title (#to_s) —

    text

Returns:

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

Prints a H4 title.

Parameters:

  • title (#to_s) —

    text

Returns:

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

Prints a H5 title.

Parameters:

  • title (#to_s) —

    text

Returns:

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

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

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:

#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 (#to_s) (defaults to: :default) —

    glyph/prefix used for the title

Yield Parameters:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Message) —

    itself, when no code block is given

#page {|Wrapper| ... } ⇒ Object

Note:

The screen manipulation is only available in ANSI mode see #ansi?

Saves current screen, deletes all screen content and moves the cursor to the top left screen corner. It restores the screen after the block.

Examples:

UI.page do |page|
  page.info('This message will disappear in 5 seconds!')
  sleep 5
end

Yields:

Returns:

  • (Object) —

    block result



106
107
108
109
110
 
# File 'lib/natty-ui/wrapper.rb', line 106

def page
  block_given? ? yield(self) : self
ensure
  @stream.flush
end

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

#print(*args, **options) ⇒ Wrapper

Print given arguments to the output stream.

Parameters:

  • args (#to_s) —

    objects to print

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :align (:left, :right, :center) —

    text alignment

Returns:



67
68
69
70
71
72
73
74
75
 
# File 'lib/natty-ui/wrapper.rb', line 67

def print(*args, **options)
  pprint(args, options) do |line|
    @stream.print(line)
    @lines_written += 1
  end
  @lines_written -= 1
  @stream.flush
  self
end

#progress(title, max_value: nil, spinner: :pulse) ⇒ 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 (:bar, :blink, :blocks, :braile, :circle, :colors, :pulse, :snake, :swap, :triangles, :vintage, #to_s) (defaults to: :pulse) —

    type of spinner or spinner elements

Returns:

#puts(*args, **options) ⇒ Wrapper

Print given arguments line-wise to the output stream.

Parameters:

  • args (#to_s) —

    objects to print

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :align (:left, :right, :center) —

    text alignment

Returns:



53
54
55
56
57
58
59
60
 
# File 'lib/natty-ui/wrapper.rb', line 53

def puts(*args, **options)
  pprint(args, options) do |line|
    @stream.puts(line)
    @lines_written += 1
  end
  @stream.flush
  self
end

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

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

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:

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Section) —

    itself, when no code block is given

#space(lines = 1) ⇒ Wrapper

Add at least one empty line

Parameters:

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

    count of lines

Returns:



81
82
83
84
85
86
 
# File 'lib/natty-ui/wrapper.rb', line 81

def space(lines = 1)
  lines = [1, lines.to_i].max
  (@stream << ("\n" * lines)).flush
  @lines_written += lines
  self
end

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

Table view of data.

Defined values for type are :double, :heavy, :semi, :simple

Overloads:

  • #table(*args, type: simple, 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) (defaults to: simple) —

      frame type

    • expand (false, true. :equal) (defaults to: false)
  • #table(type: simple, 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) (defaults to: simple) —

      frame type

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

Yields:

  • (Table) —

    table construction helper

Returns:

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

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Task) —

    itself, when no code block is given

#temporary ⇒ Proc #temporary {|Wrapper| ... } ⇒ Object

Note:

The screen manipulation is only available in ANSI mode see #ansi?

Resets the part of the screen written below the current output line when the given block ended.

Examples:

UI.temporary do |temp|
  temp.info('This message will disappear in 5 seconds!')
  sleep 5
end

Overloads:

  • #temporary ⇒ Proc

    Returns a function to reset the screen.

    Returns:

    • (Proc) —

      a function to reset the screen

  • #temporary {|Wrapper| ... } ⇒ Object

    Returns block result.

    Yields:

    Returns:

    • (Object) —

      block result



129
130
131
132
133
134
135
136
137
 
# File 'lib/natty-ui/wrapper.rb', line 129

def temporary
  func = temp_func
  return func unless block_given?
  begin
    yield(self)
  ensure
    func.call
  end
end

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

Returns:

  • (Object) —

    the result of the code block

  • (Wrapper::Message) —

    itself, when no code block is given