Module: NattyUI::Ansi

Defined in:
lib/natty-ui/ansi.rb,
lib/natty-ui/ansi/constants.rb

Overview

Helper module for ANSI escape codes.

Constant Summary collapse

CURSOR_SHOW = 
"\e[?25h"
CURSOR_HIDE = 
"\e[?25l"
CURSOR_HOME = 
cursor_pos(nil, nil)
CURSOR_FIRST_ROW = 
cursor_pos(1).freeze
CURSOR_FIRST_COLUMN = 
cursor_column(1).freeze
CURSOR_SAFE_POS_SCO = 
"\e[s"
CURSOR_SAFE_POS_DEC = 
"\e7"
CURSOR_SAFE_POS = 
CURSOR_SAFE_POS_DEC
CURSOR_RESTORE_POS_SCO = 
"\e[u"
CURSOR_RESTORE_POS_DEC = 
"\e8"
CURSOR_RESTORE_POS = 
CURSOR_RESTORE_POS_DEC
SCREEN_ERASE = 
screen_erase(:entire)
SCREEN_SAVE = 
"\e[?47h"
SCREEN_RESTORE = 
"\e[?47l"
SCREEN_ALTERNATE = 
"\e[?1049h"
SCREEN_ALTERNATE_OFF = 
"\e[?1049l"
LINE_PREVIOUS = 
cursor_previous_line(1).freeze
LINE_NEXT = 
cursor_next_line(1).freeze
LINE_ERASE = 
line_erase(:entire)
RESET = 
self[:reset].freeze
BOLD = 
self[:bold].freeze
BOLD_OFF = 
self[:bold].freeze
FAINT = 
self[:faint].freeze
FAINT_OFF = 
self[:faint_off].freeze
ITALIC = 
self[:italic].freeze
ITALIC_OFF = 
self[:italic_off].freeze
STRIKE = 
self[:strike].freeze
STRIKE_OFF = 
self[:strike_off].freeze
UNDERLINE = 
self[:underline].freeze
DOUBLE_UNDERLINE = 
self[:double_underline].freeze
UNDERLINE_OFF = 
self[:underline_off].freeze
CURLY_UNDERLINE = 
self[:curly_underline].freeze
CURLY_UNDERLINE_OFF = 
self[:curly_underline_off].freeze
self[:blink].freeze
self[:blink_off].freeze
INVERT = 
self[:invert].freeze
INVERT_OFF = 
self[:invert_off].freeze
HIDE = 
self[:hide].freeze
REVEAL = 
self[:reveal].freeze

Class Attribute Summary collapse

Control functions collapse

Tool functions collapse

Class Attribute Details

.attribute_names ⇒ Array<Symbol> (readonly)

Supported attribute names.

Returns:

  • (Array<Symbol>) —

    supported attribute names

See Also:



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

def attribute_names = SATTR.keys.sort!

.color_names ⇒ Array<Symbol> (readonly)

Supported color names.

Returns:

  • (Array<Symbol>) —

    supported color names

See Also:



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

def color_names = SCLR.keys

Class Method Details

.[](*attributes) ⇒ String

Combine given ANSI attribute_names, color_names and color codes.

Colors can specified by their name for ANSI 3-bit and 4-bit colors. For 8-bit ANSI colors use 2-digit hexadecimal values 00...ff.

To use RGB ANSI colors (24-bit colors) specify 3-digit or 6-digit hexadecimal values 000...fff or 000000...ffffff. This represent the RRGGBB values (or RGB for short version) like you may known from CSS color notation.

To use a color as background color prefix the color attribute with bg_ or on_. To use a color as underline color prefix the color attribute with ul_. To clarify that a color attribute have to be used as foreground color use the prefix fg_.

Examples:

Valid Foreground Color Attributes

Ansi[:yellow]
Ansi['#fab']
Ansi['#00aa00']
Ansi[:fg_fab]
Ansi[:fg_00aa00]
Ansi[:af]
Ansi[:fg_af]

Valid Background Color Attributes

Ansi[:bg_yellow]
Ansi[:bg_fab]
Ansi[:bg_00aa00]
Ansi['bg#00aa00']
Ansi[:bg_af]

Ansi[:on_yellow]
Ansi[:on_fab]
Ansi[:on_00aa00]
Ansi['on#00aa00']
Ansi[:on_af]

Valid Underline Color Attributes

Ansi[:underline, :ul_yellow]
Ansi[:underline, :ul_fab]
Ansi[:underline, :ul_00aa00]
Ansi[:underline, 'ul#00aa00']
Ansi[:underline, :ul_fa]
Ansi[:underline, :ul_bright_yellow]

Combined attributes:

Ansi[:bold, :italic, :bright_white, :on_0000cc]

Parameters:

  • attributes (Array<Symbol, String>) —

    attribute names to be used

Returns:

  • (String) —

    combined ANSI attributes



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/natty-ui/ansi.rb', line 198

def [](*attributes)
  return '' if attributes.empty?
  "\e[#{
    attributes
      .map do |arg|
        case arg
        when Symbol
          SATTR[arg] || SCLR[arg] || color(arg.to_s) ||
            invalid_argument(arg)
        when String
          ATTR[arg] || CLR[arg] || color(arg) || invalid_argument(arg)
        when (0..255)
          "38;5;#{arg}"
        when (256..511)
          "48;5;#{arg - 256}"
        when (512..767)
          "58;5;#{arg - 512}"
        else
          invalid_argument(arg)
        end
      end
      .join(';')
  }m"
end

.blemish(str) ⇒ String

Remove ANSI functions, attributes and colors from given string.

Parameters:

  • str (#to_s) —

    string to be modified

Returns:

  • (String) —

    string without ANSI attributes

See Also:



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

def blemish(str) = str.to_s.gsub(ESC, '')

.cursor_back(columns = 1) ⇒ String

Move cursor given colums back.

Parameters:

  • columns (Integer) (defaults to: 1) —

    number of columns to move

Returns:

  • (String) —

    ANSI control code



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

def cursor_back(columns = 1) = "\e[#{columns}D"

.cursor_column(column = 1) ⇒ String

Move cursor to given column in the current row.

Parameters:

  • column (Integer) (defaults to: 1) —

    column index

Returns:

  • (String) —

    ANSI control code



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

def cursor_column(column = 1) = "\e[#{column}G"

.cursor_down(lines = 1) ⇒ String

Move cursor given lines down.

Parameters:

  • lines (Integer) (defaults to: 1) —

    number of lines to move

Returns:

  • (String) —

    ANSI control code



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

def cursor_down(lines = 1) = "\e[#{lines}B"

.cursor_forward(columns = 1) ⇒ String

Move cursor given colums forward.

Parameters:

  • columns (Integer) (defaults to: 1) —

    number of columns to move

Returns:

  • (String) —

    ANSI control code



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

def cursor_forward(columns = 1) = "\e[#{columns}C"

.cursor_next_line(lines = 1) ⇒ String

Move cursor of beginning of the given next line.

Parameters:

  • lines (Integer) (defaults to: 1) —

    number of lines to move

Returns:

  • (String) —

    ANSI control code



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

def cursor_next_line(lines = 1) = "\e[#{lines}E"

.cursor_pos(row, column = nil) ⇒ String

Move cursor to given row and column counting from the top left corner.

Parameters:

  • row (Integer) —

    row index

  • column (Integer) (defaults to: nil) —

    column index

Returns:

  • (String) —

    ANSI control code



73
74
75
76
 
# File 'lib/natty-ui/ansi.rb', line 73

def cursor_pos(row, column = nil)
  return column ? "\e[#{row};#{column}H" : "\e[#{row}H" if row
  column ? "\e[;#{column}H" : "\e[H"
end

.cursor_previous_line(lines = 1) ⇒ String Also known as: cursor_prev_line

Move cursor of beginning of the given previous line.

Parameters:

  • lines (Integer) (defaults to: 1) —

    number of lines to move

Returns:

  • (String) —

    ANSI control code



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

def cursor_previous_line(lines = 1) = "\e[#{lines}F"

.cursor_up(lines = 1) ⇒ String

Move cursor given lines up.

Parameters:

  • lines (Integer) (defaults to: 1) —

    number of lines to move

Returns:

  • (String) —

    ANSI control code



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

def cursor_up(lines = 1) = "\e[#{lines}A"

.embellish(str, *attributes, reset: true) ⇒ String

Decorate given str with ANSI attributes and colors.

Parameters:

  • str (#to_s) —

    object to be decorated

  • attributes (Symbol, String) —

    attribute names to be used

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

    whether to include reset code for ANSI attributes

Returns:

  • (String) —

    str converted and decorated with the ANSI attributes

See Also:



231
232
233
234
 
# File 'lib/natty-ui/ansi.rb', line 231

def embellish(str, *attributes, reset: true)
  attributes = self[*attributes]
  attributes.empty? ? str.to_s : "#{attributes}#{str}#{"\e[0m" if reset}"
end

.line_erase(part = :entire) ⇒ String

Clear part of current line.

Parameters:

  • part (:to_end, :to_start, :entire) (defaults to: :entire) —

    part to delete

Returns:

  • (String) —

    ANSI control code



95
96
97
98
99
 
# File 'lib/natty-ui/ansi.rb', line 95

def line_erase(part = :entire)
  return "\e[0K" if part == :to_end
  return "\e[1K" if part == :to_start
  "\e[2K"
end

.rainbow(str, type: :foreground, frequence: 0.3, spread: 0.8, seed: 1.1) ⇒ String

Returns fancy text.

Parameters:

  • str (#to_s) —

    plain text string to enrich with color

  • type (:foreground, :background, :underline) (defaults to: :foreground) —

    type of coloring

  • frequence (Float) (defaults to: 0.3) —

    color change frequency

  • spread (Float) (defaults to: 0.8) —

    number of chars with same color

  • seed (Float) (defaults to: 1.1) —

    start index on sinus curve

Returns:

  • (String) —

    fancy text



274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/natty-ui/ansi.rb', line 274

def rainbow(
  str,
  type: :foreground,
  frequence: 0.3,
  spread: 0.8,
  seed: 1.1
)
  type = color_type(type)
  pos = -1
  str
    .to_s
    .chars
    .map! do |char|
      i = (seed + ((pos += 1) / spread)) * frequence
      "\e[#{type};2;#{(Math.sin(i) * 255).abs.to_i};" \
        "#{(Math.sin(i + PI2_THIRD) * 255).abs.to_i};" \
        "#{(Math.sin(i + PI4_THIRD) * 255).abs.to_i}m#{char}"
    end
    .join
end

.screen_erase(part = :entire) ⇒ String

Erase screen.

Parameters:

  • part (:below, :above, :scrollback, :entire) (defaults to: :entire) —

    part to erase

Returns:

  • (String) —

    ANSI control code



84
85
86
87
88
89
 
# File 'lib/natty-ui/ansi.rb', line 84

def screen_erase(part = :entire)
  return "\e[0J" if part == :below
  return "\e[1J" if part == :above
  return "\e[3J" if part == :scrollback
  "\e[2J"
end

.scroll_down(lines = 1) ⇒ String

Scroll window given lines down.

Parameters:

  • lines (Integer) (defaults to: 1) —

    number of lines to scroll

Returns:

  • (String) —

    ANSI control code



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

def scroll_down(lines = 1) = "\e[;#{lines}T"

.scroll_up(lines = 1) ⇒ String

Scroll window given lines up.

Parameters:

  • lines (Integer) (defaults to: 1) —

    number of lines to scroll

Returns:

  • (String) —

    ANSI control code



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

def scroll_up(lines = 1) = "\e[;#{lines}S"

.tab_title(title) ⇒ String

Change tab title. This is not widely supported but by iTerm.

Parameters:

  • title (String) —

    text

Returns:

  • (String) —

    ANSI control code



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

def tab_title(title) = "\e]0;#{title}\a"

.try_convert(attributes) ⇒ String?

Try to combine given ANSI attributes and colors. The attributes and colors have to be seperated by space char (" ").

Examples:

Valid Attribute String

Ansi.try_convert('bold italic blink red on#00ff00')
# => ANSI attribute string for bold, italic text which blinks red on
#    green background

Invalid Attribute String

Ansi.try_convert('cool bold on green')
# => nil

Parameters:

  • attributes (#to_s) —

    attributes separated by space char (" ")

Returns:

  • (String) —

    combined ANSI attributes

  • (nil) —

    when string does not contain valid attributes



259
260
261
262
263
264
265
266
 
# File 'lib/natty-ui/ansi.rb', line 259

def try_convert(attributes)
  return if !attributes || (attributes = attributes.to_s.split).empty?
  "\e[#{
    attributes
      .map! { ATTR[_1] || CLR[_1] || color(_1) || return }
      .join(';')
  }m"
end

.window_title(title) ⇒ String

Change window title. This is not widely supported but by XTerm and iTerm.

Parameters:

  • title (String) —

    text

Returns:

  • (String) —

    ANSI control code



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

def window_title(title) = "\e]2;#{title}\e\\"