Module: NattyUI

Defined in:
lib/natty-ui.rb,
lib/natty-ui/ansi.rb,
lib/natty-ui/text.rb,
lib/natty-ui/frame.rb,
lib/natty-ui/glyph.rb,
lib/natty-ui/key_map.rb,
lib/natty-ui/preload.rb,
lib/natty-ui/spinner.rb,
lib/natty-ui/version.rb,
lib/natty-ui/wrapper.rb,
lib/natty-ui/animation.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/mixins.rb,
lib/natty-ui/wrapper/animate.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/animation/binary.rb,
lib/natty-ui/animation/matrix.rb,
lib/natty-ui/wrapper/features.rb,
lib/natty-ui/wrapper/progress.rb,
lib/natty-ui/animation/default.rb,
lib/natty-ui/animation/rainbow.rb,
lib/natty-ui/animation/type_writer.rb,
lib/natty-ui/text/east_asian_width.rb,
lib/natty-ui/wrapper/horizontal_rule.rb,
lib/natty-ui/wrapper/list_in_columns.rb

Overview

Module to create beautiful, nice, nifty, fancy, neat, pretty, cool, rich, lovely, natty user interfaces for your CLI application.

It creates Wrapper instances which can optionally support ANSI. The UI consists of Wrapper::Elements and Wrapper::Sections for different Features.

Defined Under Namespace

Modules: Ansi, Features, Frame, Glyph, ProgressAttributes, Spinner, ValueAttributes Classes: Wrapper

Constant Summary collapse

StdOut =

Instance for standard output.

new(STDOUT)
StdErr =

Instance for standard error output.

stderr_is_stdout? ? StdOut : new(STDERR)
VERSION =

The version number of the gem.

'0.12.1'

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.element ⇒ Wrapper, Wrapper::Element (readonly)

Returns active UI element.

Returns:



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

def element
  @element
end

.in_stream ⇒ IO

Returns IO stream used to read input.

Returns:

  • (IO) —

    IO stream used to read input

Raises:

  • (TypeError) —

    when a non-readable stream will be assigned

See Also:



20
21
22
 
# File 'lib/natty-ui.rb', line 20

def in_stream
  @in_stream
end

Class Method Details

.display_width(str) ⇒ Integer

Calculate monospace (display) width of given String. It respects Unicode character sizes inclusive emoji.

Parameters:

  • str (#to_s) —

    string to calculate

Returns:

  • (Integer) —

    the display size



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

def display_width(str) = Text.width(str)

.each_line(..., max_width: nil) {|line| ... } ⇒ nil .each_line(..., max_width: nil) ⇒ Enumerator

Convert given arguments into strings and yield each line. Optionally limit the line width to given max_width.

Overloads:

  • .each_line(..., max_width: nil) {|line| ... } ⇒ nil

    Parameters:

    • ... (#to_s) —

      objects converted to text lines

    • max_width (#to_i, nil) (defaults to: nil) —

      maximum line width

    Yield Parameters:

    • line (String) —

      string line

    Returns:

    • (nil)
  • .each_line(..., max_width: nil) ⇒ Enumerator

    Returns line enumerator.

    Parameters:

    • ... (#to_s) —

      objects converted to text lines

    • max_width (#to_i, nil) (defaults to: nil) —

      maximum line width

    Returns:

    • (Enumerator) —

      line enumerator



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

def each_line(*strs, max_width: nil, &block)
  return to_enum(__method__, *strs, max_width: max_width) unless block
  return Text.simple_each_line(strs, &block) unless max_width
  Text.each_line(strs, max_width, &block)
end

.embellish(str) ⇒ String

Translate embedded attribute descriptions into ANSI control codes.

Parameters:

  • str (#to_s) —

    string to edit

Returns:

  • (String) —

    edited string



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

def embellish(str) = Text.embellish(str)

.plain(str, ansi: :keep) ⇒ String

Remove embedded attribute descriptions from given string.

Parameters:

  • str (#to_s) —

    string to edit

  • ansi (:keep, :remove) (defaults to: :keep) —

    keep or remove ANSI codes too

Returns:

  • (String) —

    edited string



82
83
84
 
# File 'lib/natty-ui.rb', line 82

def plain(str, ansi: :keep)
  ansi == :keep ? Text.plain_but_ansi(str) : Text.plain(str)
end

.read_key(mode: :named) ⇒ String

Read next raw key (keyboard input) from in_stream.

The input will be returned as named key codes like "Ctrl+C" by default. This can be changed by the mode parameter:

  • :named - name if available (fallback to raw)
  • :raw - key code "as is"
  • :both - key code and name if available

Parameters:

  • mode (:named, :raw, :both) (defaults to: :named) —

    modfies the result

Returns:

  • (String) —

    read key



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/natty-ui.rb', line 122

def read_key(mode: :named)
  return @in_stream.getch unless defined?(@in_stream.getc)
  return @in_stream.getc unless defined?(@in_stream.raw)
  @in_stream.raw do |raw_stream|
    key = raw_stream.getc
    while (nc = raw_stream.read_nonblock(1, exception: false))
      nc.is_a?(String) ? key += nc : break
    end
    return key if mode == :raw
    return key, KEY_MAP[key]&.dup if mode == :both
    KEY_MAP[key]&.dup || key
  end
rescue Interrupt, SystemCallError
  nil
end

.valid_in?(stream) ⇒ Boolean

Test if the given stream can be used for input

Parameters:

  • stream (IO) —

    IO instance to test

Returns:

  • (Boolean) —

    whether if the given stream is usable



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

def valid_in?(stream)
  (stream.is_a?(IO) && !stream.closed? && stream.stat.readable?) ||
    (stream.is_a?(StringIO) && !stream.closed_read?)
rescue StandardError
  false
end

.valid_out?(stream) ⇒ Boolean

Test if the given stream can be used for output

Parameters:

  • stream (IO) —

    IO instance to test

Returns:

  • (Boolean) —

    whether if the given stream is usable



64
65
66
67
68
69
 
# File 'lib/natty-ui.rb', line 64

def valid_out?(stream)
  (stream.is_a?(IO) && !stream.closed? && stream.stat.writable?) ||
    (stream.is_a?(StringIO) && !stream.closed_write?)
rescue StandardError
  false
end