README

Path: README
Last Update: Fri Jul 08 14:06:36 -0400 2011

ANSI escape sequences in Ruby

Description

This library can be used to color/decolor strings using ANSI escape sequences.

Installation

Just type into the command line as root:

# ruby install.rb

Or if you prefer using Rake, try:

# rake install

Or if you want to use rubygems just type this and rubygems fetches the gem and installs it for you:

# gem install term-ansicolor

Download

The latest version of this library can be downloaded at

The homepage of this library is located at

Examples

Additional to the two executables cdiff and decolor, the file examples/example.rb in the source/gem-distribution shows how this library can be used:

    require 'term/ansicolor'

    # Use this trick to work around namespace cluttering that
    # happens if you just include Term::ANSIColor:

    class Color
      extend Term::ANSIColor
    end

    print Color.red, Color.bold, "No Namespace cluttering:", Color.clear, "\n"
    print Color.green + "green" + Color.clear, "\n"
    print Color.on_red(Color.green("green")), "\n"
    print Color.yellow { Color.on_black { "yellow on_black" } }, "\n\n"

    # Or shortcut Term::ANSIColor by assignment:
    c = Term::ANSIColor

    print c.red, c.bold, "No Namespace cluttering (alternative):", c.clear, "\n"
    print c.green + "green" + c.clear, "\n"
    print c.on_red(c.green("green")), "\n"
    print c.yellow { c.on_black { "yellow on_black" } }, "\n\n"

    # Anyway, I don't define any of Term::ANSIColor's methods in this example
    # and I want to keep it short:
    include Term::ANSIColor

    print red, bold, "Usage as constants:", reset, "\n"
    print clear, "clear", reset, reset, "reset", reset,
      bold, "bold", reset, dark, "dark", reset,
      underscore, "underscore", reset, blink, "blink", reset,
      negative, "negative", reset, concealed, "concealed", reset, "|\n",
      black, "black", reset, red, "red", reset, green, "green", reset,
      yellow, "yellow", reset, blue, "blue", reset, magenta, "magenta", reset,
      cyan, "cyan", reset, white, "white", reset, "|\n",
      on_black, "on_black", reset, on_red, "on_red", reset,
      on_green, "on_green", reset, on_yellow, "on_yellow", reset,
      on_blue, "on_blue", reset, on_magenta, "on_magenta", reset,
      on_cyan, "on_cyan", reset, on_white, "on_white", reset, "|\n\n"

    print red, bold, "Usage as unary argument methods:", reset, "\n"
    print clear("clear"), reset("reset"), bold("bold"), dark("dark"),
      underscore("underscore"), blink("blink"), negative("negative"),
      concealed("concealed"), "|\n",
      black("black"), red("red"), green("green"), yellow("yellow"),
      blue("blue"), magenta("magenta"), cyan("cyan"), white("white"), "|\n",
      on_black("on_black"), on_red("on_red"), on_green("on_green"),#
      on_yellow("on_yellow"), on_blue("on_blue"), on_magenta("on_magenta"),
      on_cyan("on_cyan"), on_white("on_white"), "|\n\n"

    print red { bold { "Usage as block forms:" } }, "\n"
    print clear { "clear" }, reset { "reset" }, bold { "bold" },
      dark { "dark" }, underscore { "underscore" }, blink { "blink" },
      negative { "negative" }, concealed { "concealed" }, "|\n",
      black { "black" }, red { "red" }, green { "green" },
      yellow { "yellow" }, blue { "blue" }, magenta { "magenta" },
      cyan { "cyan" }, white { "white" }, "|\n",
      on_black { "on_black" }, on_red { "on_red" }, on_green { "on_green" },
      on_yellow { "on_yellow" }, on_blue { "on_blue" },
      on_magenta { "on_magenta" }, on_cyan { "on_cyan" },
      on_white { "on_white" }, "|\n\n"

    # Usage as Mixin into String or its Subclasses
    class String
      include Term::ANSIColor
    end

    print "Usage as String Mixins:".red.bold, "\n"
    print "clear".clear, "reset".reset, "bold".bold, "dark".dark,
      "underscore".underscore, "blink".blink, "negative".negative,
      "concealed".concealed, "|\n",
      "black".black, "red".red, "green".green, "yellow".yellow,
      "blue".blue, "magenta".magenta, "cyan".cyan, "white".white, "|\n",
      "on_black".on_black, "on_red".on_red, "on_green".on_green,
      "on_yellow".on_yellow, "on_blue".on_blue, "on_magenta".on_magenta,
      "on_cyan".on_cyan, "on_white".on_white, "|\n\n"

    symbols = Term::ANSIColor::attributes
    print red { bold { "All supported attributes = " } },
      blue { symbols.inspect }, "\n\n"

    print "Send symbols to strings:".send(:red).send(:bold), "\n"
    print symbols[12, 8].map { |c| c.to_s.send(c) }, "\n\n"

    print red { bold { "Make strings monochromatic again:" } }, "\n"
    print [
        "red".red,
        "not red anymore".red.uncolored,
        uncolored { "not red anymore".red },
        uncolored("not red anymore".red)
      ].map { |x| x + "\n" }

Author

Florian Frank flori@ping.de

License

This is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License Version 2 as published by the Free Software Foundation: www.gnu.org/copyleft/gpl.html

[Validate]