module ANSI::Code

ANSI Codes

Ansi::Code module makes it very easy to use ANSI codes. These are especially nice for beautifying shell output.

Ansi::Code.red + "Hello" + Ansi::Code.blue + "World"
=> "\e[31mHello\e[34mWorld"

Ansi::Code.red{ "Hello" } + Ansi::Code.blue{ "World" }
=> "\e[31mHello\e[0m\e[34mWorld\e[0m"

IMPORTANT! Do not mixin Ansi::Code, instead use {ANSI::Mixin}.

See {ANSI::CHART} for list of all supported codes.

Constants

ENDCODE

ANSI clear code.

PATTERN

Regexp for matching most ANSI codes.

Public Class Methods

colors() click to toggle source

List of primary colors.

# File lib/ansi/code.rb, line 55
def self.colors
  %w{black red green yellow blue magenta cyan white}
end
styles() click to toggle source

List of primary styles.

# File lib/ansi/code.rb, line 50
def self.styles
  %w{bold dark italic underline underscore blink rapid reverse negative concealed strike}
end

Public Instance Methods

[](*codes) click to toggle source

Return ANSI code given a list of symbolic names.

# File lib/ansi/code.rb, line 60
def [](*codes)
  code(*codes)
end
ansi(*codes) { || ... } click to toggle source

Apply ANSI codes to a first argument or block value.

@example

ansi("Valentine", :red, :on_white)

@example

ansi(:red, :on_white){ "Valentine" }

@return [String]

String wrapped ANSI code.
# File lib/ansi/code.rb, line 176
def ansi(*codes) #:yield:
  if block_given?
    string = yield.to_s
  else
    # first argument must be the string
    string = codes.shift.to_s
  end

  return string unless $ansi

  c = code(*codes)

  c + string.gsub(ENDCODE, ENDCODE + c) + ENDCODE
end
Also aliased as: style, color
back(spaces=1)
Alias for: left
code(*codes) click to toggle source

Look-up code from chart, or if Integer simply pass through. Also resolves :random and :on_random.

@param codes [Array<Symbol,Integer]

Symbols or integers to convert to ANSI code.

@return [String] ANSI code

# File lib/ansi/code.rb, line 241
def code(*codes)
  list = []
  codes.each do |code|
    list <<            case code
      when Integer
        code
      when Array
        rgb_code(*code)
      when :random, 'random'
        random
      when :on_random, 'on_random'
        random(true)
      when String
        # TODO: code =~ /\d\d\d\d\d\d/ ?
        if code.start_with?('#')
          hex_code(code)
        else
          CHART[code.to_sym]
        end
      else
        CHART[code.to_sym]
      end
  end
  "\e[" + (list * ";") + "m"
end
color(*codes)

Alternate term for ansi.

@deprecated

May change in future definition.
Alias for: ansi
display(line, column=0) { || ... } click to toggle source

Like move but returns to original position after yielding the block.

# File lib/ansi/code.rb, line 120
def display(line, column=0) #:yield:
  result = "\e[s"
  result << "\e[#{line.to_i};#{column.to_i}H"
  if block_given?
    result << yield
    result << "\e[u"
  #elsif string
  #  result << string
  #  result << "\e[u"
  end
  result
end
down(spaces=1) click to toggle source

Move cursor down a specified number of spaces.

# File lib/ansi/code.rb, line 144
def down(spaces=1)
  "\e[#{spaces.to_i}B"
end
forward(spaces=1)
Alias for: right
hex_code(string, background=false) click to toggle source

Creates an xterm-256 color code from a CSS-style color string.

@param string [String]

Hex string in CSS style, .e.g. `#5FA0C2`.

@param background [Boolean]

Use `true` for background color, otherwise foreground color.
# File lib/ansi/code.rb, line 325
def hex_code(string, background=false)
  string.tr!('#','')
  x = (string.size == 6 ? 2 : 1)
  r, g, b = [0,1,2].map{ |i| string[i*x,2].to_i(16) }
  rgb_code(r, g, b, background)
end
left(spaces=1) click to toggle source

Move cursor left a specified number of spaces.

# File lib/ansi/code.rb, line 149
def left(spaces=1)
  "\e[#{spaces.to_i}D"
end
Also aliased as: back
method_missing(code, *args) { || ... } click to toggle source

Use method missing to dispatch ANSI code methods.

Calls superclass method
# File lib/ansi/code.rb, line 89
def method_missing(code, *args, &blk)
  esc = nil

  if CHART.key?(code)
    esc = "\e[#{CHART[code]}m"
  elsif SPECIAL_CHART.key?(code)
    esc = SPECIAL_CHART[code]
  end

  if esc
    if string = args.first
      return string unless $ansi
      #warn "use ANSI block notation for future versions"
      return "#{esc}#{string}#{ENDCODE}"
    end
    if block_given?
      return yield unless $ansi
      return "#{esc}#{yield}#{ENDCODE}"
    end
    esc
  else
    super(code, *args, &blk)
  end
end
move(line, column=0) click to toggle source

Move cursor to line and column.

# File lib/ansi/code.rb, line 134
def move(line, column=0)
  "\e[#{line.to_i};#{column.to_i}H"
end
random(background=false) click to toggle source

Provides a random primary ANSI color.

@param background [Boolean]

Use `true` for background color, otherwise foreground color.

@return [Integer] ANSI color number

# File lib/ansi/code.rb, line 274
def random(background=false)
  (background ? 40 : 30) + rand(8)
end
rgb(*args) { || ... } click to toggle source

Creates an XTerm 256 color escape code from RGB value(s). The RGB value can be three arguments red, green and blue respectively each from 0 to 255, or the RGB value can be a single CSS-style hex string.

@param background [Boolean]

Use `true` for background color, otherwise foreground color.
# File lib/ansi/code.rb, line 286
def rgb(*args)
  case args.size
  when 1, 2
    hex, background = *args
    esc = "\e[" + hex_code(hex, background) + "m"
  when 3, 4
    red, green, blue, background = *args
    esc = "\e[" + rgb_code(red, green, blue, background) + "m"
  else
    raise ArgumentError
  end

  if block_given?
    return yield.to_s unless $ansi
    return "#{esc}#{yield}#{ENDCODE}"
  else
    return esc
  end
end
rgb_256(r, g, b) click to toggle source

Given red, green and blue values between 0 and 255, this method returns the closest XTerm 256 color value.

# File lib/ansi/code.rb, line 335
def rgb_256(r, g, b)
  # TODO: what was rgb_valid for?
  #r, g, b = [r, g, b].map{ |c| rgb_valid(c); (6 * (c.to_f / 256.0)).to_i }
  r, g, b = [r, g, b].map{ |c| (6 * (c.to_f / 256.0)).to_i }
  v = (r * 36 + g * 6 + b + 16).abs
  raise ArgumentError, "RGB value is outside 0-255 range -- #{v}" if v > 255
  v
end
rgb_code(red, green, blue, background=false) click to toggle source

Creates an xterm-256 color from rgb value.

@param background [Boolean]

Use `true` for background color, otherwise foreground color.
# File lib/ansi/code.rb, line 313
def rgb_code(red, green, blue, background=false)
  "#{background ? 48 : 38};5;#{rgb_256(red, green, blue)}"
end
right(spaces=1) click to toggle source

Move cursor right a specified number of spaces.

# File lib/ansi/code.rb, line 155
def right(spaces=1)
  "\e[#{spaces.to_i}C"
end
Also aliased as: forward
style(*codes)

Alias for ansi method.

@deprecated

Here for backward compatibility.
Alias for: ansi
unansi(string=nil) { || ... } click to toggle source

Remove ANSI codes from string or block value.

@param [String] string

String from which to remove ANSI codes.

@return [String]

String wrapped ANSI code.
# File lib/ansi/code.rb, line 201
def unansi(string=nil) #:yield:
  if block_given?
    string = yield.to_s
  else
    string = string.to_s
  end
  string.gsub(PATTERN, '')
end
Also aliased as: unstyle, uncolor
uncolor(string=nil)

Alias for unansi.

@deprecated

May change in future definition.
Alias for: unansi
unstyle(string=nil)

Alias for unansi method.

@deprecated

Here for backwards compatibility.
Alias for: unansi
up(spaces=1) click to toggle source

Move cursor up a specified number of spaces.

# File lib/ansi/code.rb, line 139
def up(spaces=1)
  "\e[#{spaces.to_i}A"
end