Module: JustAnsi

Defined in:
lib/just-ansi.rb,
lib/just-ansi/version.rb,
lib/just-ansi/attributes.rb,
lib/just-ansi/named_colors.rb

Overview

Simple and fast ANSI control code processing.

Constant Summary collapse

VERSION =

The version number of the gem.

'1.0.0'

Class Attribute Summary collapse

Control functions collapse

Class Method Summary collapse

Class Attribute Details

.attributes ⇒ Array<Symbol> (readonly)

Supported attribute names.

Returns:

  • (Array<Symbol>) —

    all attribute names

See Also:



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

def attributes = ATTRIBUTES_S.keys

.colors ⇒ Array<Symbol> (readonly)

Supported 3/4-bit color names.

Returns:

  • (Array<Symbol>) —

    all color names

See Also:



22
 
# File 'lib/just-ansi.rb', line 22

def colors = COLORS_S.keys

.named_colors ⇒ Array<Symbol> (readonly)

Supported basic 24-bit color names.

Returns:

  • (Array<Symbol>) —

    all basic named_colors names

See Also:



30
 
# File 'lib/just-ansi.rb', line 30

def named_colors = NAMED_COLORS.keys.map!(&:to_sym)

Class Method Details

.[](*attributes) ⇒ String

Combine given ANSI attributes, colors, named_colors 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

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

Valid Background Color Attributes

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

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

Valid Underline Color Attributes

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

Combined attributes:

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

Parameters:

  • attributes (Array<Symbol, String>) —

    attribute names to be used

Returns:

  • (String) —

    combined ANSI attributes



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/just-ansi.rb', line 88

def [](*attributes)
  return +'' if attributes.empty?
  "\e[#{
    attributes
      .map do |arg|
        case arg
        when Symbol
          ATTRIBUTES_S[arg] || COLORS_S[arg] || _color(arg) || _invalid(arg)
        when String
          ATTRIBUTES[arg] || COLORS[arg] || _color(arg) || _invalid(arg)
        when (0..255)
          "38;5;#{arg}"
        when (256..511)
          "48;5;#{arg - 256}"
        when (512..767)
          "58;5;#{arg - 512}"
        else
          _invalid(arg)
        end
      end
      .join(';')
  }m"
end

.ansi?(str) ⇒ true, false

Test if given String contains ANSI codes.

Parameters:

  • str (#to_s) —

    object to be tested

Returns:

  • (true, false) —

    whether if attributes are found



137
 
# File 'lib/just-ansi.rb', line 137

def ansi?(str) = TEST.match?(str.to_s)

.bbcode(str) ⇒ String

Replace embedded BBCode-like attributes with ANSI codes.

Examples:

JustAnsi.bbcode "[b]Bold[/b] Text"
# "\e[1mBold\e[22m Text"

Parameters:

  • str (#to_s) —

    string to be modified

Returns:

  • (String) —

    string with ANSI attributes



197
198
199
200
201
202
203
204
205
 
# File 'lib/just-ansi.rb', line 197

def bbcode(str)
  str
    .to_s
    .gsub(BBCODE) do |match_str|
      match = Regexp.last_match[1]
      next "[#{match[1..]}]" if match[0] == '\\'
      try_convert(match) || match_str
    end
end

.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



278
 
# File 'lib/just-ansi.rb', line 278

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



297
 
# File 'lib/just-ansi.rb', line 297

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



266
 
# File 'lib/just-ansi.rb', line 266

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



272
 
# File 'lib/just-ansi.rb', line 272

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

.cursor_hide ⇒ String

Hide cursor.

Returns:

  • (String) —

    ANSI control code



317
 
# File 'lib/just-ansi.rb', line 317

def cursor_hide = +CURSOR_HIDE

.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



284
 
# File 'lib/just-ansi.rb', line 284

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



304
305
306
307
 
# File 'lib/just-ansi.rb', line 304

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

.cursor_pos_restore ⇒ String

Restore safed cursor position.

Returns:

  • (String) —

    ANSI control code



327
 
# File 'lib/just-ansi.rb', line 327

def cursor_pos_restore = +CURSOR_POS_RESTORE

.cursor_pos_safe ⇒ String

Safe current cursor position.

Returns:

  • (String) —

    ANSI control code



322
 
# File 'lib/just-ansi.rb', line 322

def cursor_pos_safe = +CURSOR_POS_SAFE

.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



290
 
# File 'lib/just-ansi.rb', line 290

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

.cursor_show ⇒ String

Show cursor.

Returns:

  • (String) —

    ANSI control code



312
 
# File 'lib/just-ansi.rb', line 312

def cursor_show = +CURSOR_SHOW

.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



260
 
# File 'lib/just-ansi.rb', line 260

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

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

Decorate given str with ANSI attributes and colors.

Parameters:

  • str (#to_s) —

    object to be decorated

  • attributes (Array<Symbol, String>) —

    attribute names to be used

  • reset (true, false) (defaults to: true) —

    whether to include reset code for ANSI attributes

Returns:

  • (String) —

    str converted and decorated with the ANSI attributes

See Also:



148
149
150
151
 
# File 'lib/just-ansi.rb', line 148

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

.line_delete(lines = 1) ⇒ String

Delete given numbers of lines.

Parameters:

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

    number of lines to move

Returns:

  • (String) —

    ANSI control code



394
 
# File 'lib/just-ansi.rb', line 394

def line_delete(lines = 1) = "\e[#{lines}M"

.line_erase ⇒ String

Erase current line.

Returns:

  • (String) —

    ANSI control code



382
 
# File 'lib/just-ansi.rb', line 382

def line_erase = _line_erase(2)

.line_erase_to_end ⇒ String

Erase line from current column to end of line.

Returns:

  • (String) —

    ANSI control code



372
 
# File 'lib/just-ansi.rb', line 372

def line_erase_to_end = _line_erase(0)

.line_erase_to_start ⇒ String

Erase line from current column to start of line.

Returns:

  • (String) —

    ANSI control code



377
 
# File 'lib/just-ansi.rb', line 377

def line_erase_to_start = _line_erase(1)

.line_insert(lines = 1) ⇒ String

Insert given numbers of lines.

Parameters:

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

    number of lines to move

Returns:

  • (String) —

    ANSI control code



388
 
# File 'lib/just-ansi.rb', line 388

def line_insert(lines = 1) = "\e[#{lines}L"

.link(url, text) ⇒ Object

Create a hyperlink. This is not widely supported.



424
 
# File 'lib/just-ansi.rb', line 424

def link(url, text) = "\e]8;;#{url}\a#{text}\e]8;;\a"

.plain(str) ⇒ String

Remove any BBCode-like and/or ANSI attributes.

Parameters:

  • str (#to_s) —

    string to be modified

Returns:

  • (String) —

    string without BBCode and ANSI control codes.



231
 
# File 'lib/just-ansi.rb', line 231

def plain(str) = unbbcode(str).gsub(TEST, '')

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

Create nice colored text.

Parameters:

  • str (#to_s) —

    string to enrich with color

  • 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



240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/just-ansi.rb', line 240

def rainbow(str, frequence: 0.3, spread: 0.8, seed: 1.1)
  pos = -1
  str
    .to_s
    .chars
    .map! do |char|
      i = (seed + ((pos += 1) / spread)) * frequence
      "\e[38;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 << RESET
end

.screen_alternate ⇒ String

Use alternative screen buffer.

Returns:

  • (String) —

    ANSI control code



362
 
# File 'lib/just-ansi.rb', line 362

def screen_alternate = +SCREEN_ALTERNATE

.screen_alternate_off ⇒ String

Do not longer use alternative screen buffer.

Returns:

  • (String) —

    ANSI control code



367
 
# File 'lib/just-ansi.rb', line 367

def screen_alternate_off = +SCREEN_ALTERNATE_OFF

.screen_erase ⇒ String

Erase complete screen.

Returns:

  • (String) —

    ANSI control code



342
 
# File 'lib/just-ansi.rb', line 342

def screen_erase = _screen_erase(2)

.screen_erase_above ⇒ String

Erase screen above current cursor line.

Returns:

  • (String) —

    ANSI control code



337
 
# File 'lib/just-ansi.rb', line 337

def screen_erase_above = _screen_erase(1)

.screen_erase_below ⇒ String

Erase screen below current cursor line.

Returns:

  • (String) —

    ANSI control code



332
 
# File 'lib/just-ansi.rb', line 332

def screen_erase_below = _screen_erase(0)

.screen_erase_scrollback ⇒ String

Erase screen scrollback buffer.

Returns:

  • (String) —

    ANSI control code



347
 
# File 'lib/just-ansi.rb', line 347

def screen_erase_scrollback = _screen_erase(3)

.screen_restore ⇒ String

Restore current screen.

Returns:

  • (String) —

    ANSI control code



357
 
# File 'lib/just-ansi.rb', line 357

def screen_restore = +SCREEN_RESTORE

.screen_save ⇒ String

Safe current screen.

Returns:

  • (String) —

    ANSI control code



352
 
# File 'lib/just-ansi.rb', line 352

def screen_save = +SCREEN_SAVE

.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



406
 
# File 'lib/just-ansi.rb', line 406

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



400
 
# File 'lib/just-ansi.rb', line 400

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

.tab_title(title) ⇒ String

Change tab title. This is not widely supported.

Parameters:

  • title (String) —

    text

Returns:

  • (String) —

    ANSI control code



420
 
# File 'lib/just-ansi.rb', line 420

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

.try_convert(attributes, seperator: ' ') ⇒ String?

Try to combine given ANSI attributes and colors. The attributes and colors have to be seperated by given seperator`.

Examples:

Valid Attribute String

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

Invalid Attribute String

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

Parameters:

  • attributes (#to_s) —

    attributes separated by given seperator

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

    attribute seperator char

Returns:

  • (String) —

    combined ANSI attributes

  • (nil) —

    when string does not contain valid attributes

See Also:



179
180
181
182
183
184
185
186
187
 
# File 'lib/just-ansi.rb', line 179

def try_convert(attributes, seperator: ' ')
  return unless attributes
  return if (attributes = attributes.to_s.split(seperator)).empty?
  "\e[#{
    attributes
      .map! { ATTRIBUTES[_1] || COLORS[_1] || _color(_1) || return }
      .join(';')
  }m"
end

.unbbcode(str) ⇒ String

Remove embedded BBCode-like attributes.

Examples:

JustAnsi.unbbcode "[b]Bold[/b] Text"
# "Bold Text"

Parameters:

  • str (#to_s) —

    string to be modified

Returns:

  • (String) —

    string without BBCode



215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/just-ansi.rb', line 215

def unbbcode(str)
  str
    .to_s
    .gsub(BBCODE) do |match_str|
      next match_str if (match = Regexp.last_match[1]).empty?
      next "[#{match[1..]}]" if match[0] == '\\'
      next match_str if (match = match.split).empty?
      next if match.all? { ATTRIBUTES[_1] || COLORS[_1] || _color(_1) }
      match_str
    end
end

.undecorate(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:



159
 
# File 'lib/just-ansi.rb', line 159

def undecorate(str) = str.to_s.gsub(TEST, '')

.valid?(*attributes) ⇒ true, false

Test if all given attributes are valid.

Parameters:

  • attributes (Array<Symbol, String>) —

    attribute names to be used

Returns:

  • (true, false) —

    whether if all given attributes are valid

See Also:



118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/just-ansi.rb', line 118

def valid?(*attributes)
  attributes.all? do |arg|
    case arg
    when Symbol
      ATTRIBUTES_S[arg] || COLORS_S[arg] || _color(arg) || false
    when String
      ATTRIBUTES[arg] || COLORS[arg] || _color(arg) || false
    when (0..767)
      true
    else
      false
    end
  end
end

.window_title(title) ⇒ String

Change window title. This is not widely supported.

Parameters:

  • title (String) —

    text

Returns:

  • (String) —

    ANSI control code



413
 
# File 'lib/just-ansi.rb', line 413

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