# ANSI::Code

Require the library.

    require 'ansi/code'

ANSI::Code can be used as a functions module.

    str = ANSI::Code.red + "Hello" + ANSI::Code.blue + "World"
    str.assert == "\e[31mHello\e[34mWorld"

If a block is supplied to each method then yielded value will
be wrapped in the ANSI code and clear code. 

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

More conveniently the ANSI::Code module extends ANSI itself.

    str = ANSI.red + "Hello" + ANSI.blue + "World"
    str.assert == "\e[31mHello\e[34mWorld"

    str = ANSI.red{ "Hello" } + ANSI.blue{ "World" }
    str.assert == "\e[31mHello\e[0m\e[34mWorld\e[0m"

In the appropriate context the ANSI::Code module can also be
included, making its methods directly accessible.

    include ANSI::Code

    str = red + "Hello" + blue + "World"
    str.assert == "\e[31mHello\e[34mWorld"

    str = red{ "Hello" } + blue{ "World" }
    str.assert == "\e[31mHello\e[0m\e[34mWorld\e[0m"

Along with the single font colors, the library include background colors.

    str = on_red + "Hello"
    str.assert == "\e[41mHello"

As well as combined color methods.

    str = white_on_red + "Hello"
    str.assert == "\e[37m\e[41mHello"

The ANSI::Code module supports most standard ANSI codes, though
not all platforms support every code, so YMMV.


# String Extensions

In addition the library offers an extension to String class
called #ansi, which allows some of the ANSI::Code methods
to be called in a more object-oriented fashion.

    require 'ansi/core'

    str = "Hello".ansi(:red) + "World".ansi(:blue)
    str.assert == "\e[31mHello\e[0m\e[34mWorld\e[0m"


# ANSI::Logger

Require the ANSI::Logger library.

    require 'ansi/logger'

Create a new ANSI::Logger

    log = ANSI::Logger.new(STDOUT)

Info logging appears normal.

    log.info{"Info logs are green.\n"}

Warn logging appears yellow.

    log.warn{"Warn logs are yellow.\n"}

Debug logging appears cyan.

    log.debug{"Debug logs are cyan.\n"}

Error logging appears red.

    log.error{"Error logs are red.\n"}

Fatal logging appears bright red.

    log.fatal{"Fatal logs are bold red!\n"}


# ANSI::Progressbar

Pretty progress bars are easy to construct.

    require 'ansi/progressbar'

    pbar = ANSI::Progressbar.new("Test Bar", 100)

Running the bar simply requires calling the #inc method during
a loop and calling #finish when done.

    100.times do |i|
      sleep 0.01
      pbar.inc
    end
    pbar.finish

We will use this same rountine in all the examples below, so lets
make a quick macro for it. Notice we have to use #reset first
before reusing the same progress bar.

    def run(pbar)
      pbar.reset
      100.times do |i|
        sleep 0.01
        pbar.inc
      end
      pbar.finish
      puts
    end

The progress bar can be stylized in almost any way.
The #format setter provides control over the parts
that appear on the line. For example, by default the
format is:

    pbar.format("%-14s %3d%% %s %s", :title, :percentage, :bar, :stat)

So lets vary it up to demonstrate the case.

    pbar.format("%-14s %3d%% %s %s", :title, :percentage, :stat, :bar)
    run(pbar)

The progress bar has an extra build in format intended for use with
file downloads called #transer_mode.

    pbar.transfer_mode
    run(pbar)

Calling this methods is the same as calling:

    pbar.format("%-14s %3d%% %s %s",:title, :percentage, :bar, :stat_for_file_transfer)
    run(pbar)

The #style setter allows each part of the line be modified with ANSI codes. And the
#bar_mark writer can be used to change the character used to make the bar.

    pbar.standard_mode
    pbar.style(:title => [:red], :bar=>[:blue])
    pbar.bar_mark = "="
    run(pbar)


# ANSI::Mixin

The ANSI::Mixin module is design for including into
String-like classes. It will support any class that defines
a #to_s method.

    require 'ansi/mixin'

In this demonstration we will simply include it in the
core String class.

    class ::String
      include ANSI::Mixin
    end

Now all strings will have access to ANSI's style and color
codes via simple method calls.

    "roses".red.assert == "\e[31mroses\e[0m"

    "violets".blue.assert == "\e[34mviolets\e[0m"

    "sugar".italic.assert == "\e[3msugar\e[0m"

The method can be combined, of course.

    "you".italic.bold.assert == "\e[1m\e[3myou\e[0m\e[0m"

The mixin also supports background methods.

    "envy".on_green.assert == "\e[42menvy\e[0m"

And it also supports the combined foreground-on-background 
methods.

    "b&w".white_on_black.assert == "\e[37m\e[40mb&w\e[0m"


# ANSI::String

The ANSI::String class is a very sophisticated implementation
of Ruby's standard String class, but one that can handle
ANSI codes seamlessly.

    require 'ansi/string'

    flower1 = ANSI::String.new("Roses")
    flower2 = ANSI::String.new("Violets")

Like any other string.

    flower1.to_s.assert == "Roses"
    flower2.to_s.assert == "Violets"

Bet now we can add color.

    flower1.red!
    flower2.blue!

    flower1.to_s.assert == "\e[31mRoses\e[0m"
    flower2.to_s.assert == "\e[34mViolets\e[0m"

Despite that the string representation now contains ANSI codes,
we can still manipulate the string in much the same way that
we manipulate an ordinary string.

    flower1.size.assert == 5
    flower2.size.assert == 7

Like ordinary strings we can concatenate the two strings

    flowers = flower1 + ' ' + flower2
    flowers.to_s.assert == "\e[31mRoses\e[0m \e[34mViolets\e[0m"

    flowers.size.assert == 13

Standard case conversion such as #upcase and #downcase work.

    flower1.upcase.to_s.assert == "\e[31mROSES\e[0m"
    flower1.downcase.to_s.assert == "\e[31mroses\e[0m"

Some of the most difficult methods to re-implement were the 
substitution methods such as #sub and #gsub. They are still
somewhat more limited than the original string methods, but
their primary functionality should work.

    flower1.gsub('s', 'z').to_s.assert == "\e[31mRozez\e[0m"

There are still a number of methods that need implementation.
ANSI::String is currently a very partial implementation. But
as you can see from the methods it does currently support,
is it already useful.


# ANSI::Columns

The +Columns+ class makes it easy to create nice looking text columns,
sorted from top to bottom, right to left (as opposed to the other way
around).

    require 'ansi/columns'

    list = %w{a b c d e f g h i j k l}

    columns = ANSI::Columns.new(list)

    columns.to_s(4)

The output will be:

    a d g j
    b e h k
    c f i l

Besides an array of elements, Columns.new can take a string in which
the elements are divided by newlines characters. The default column
size can also be given to the initializer.

    list = "a\nb\nc\nd\ne\nf\ng\nh\ni\nj\nk\nl"

    columns = ANSI::Columns.new(list, :columns=>6)

    columns.to_s

The output will be:

    a c e g i k
    b d f h j l

If the column count is +nil+, then the number of columns will be calculated
as a best fit for the current terminal window.

## Padding

Columns can adjust the padding between cells.

    list = %w{a b c d e f g h i j k l}

    columns = ANSI::Columns.new(list, :padding=>2)

    columns.to_s(4)

The output will be:

    a  d  g  j
    b  e  h  k
    c  f  i  l

## Alignment

Columns can also be aligned either left or right.

    list = %w{xx xx xx yy y yy z zz z}

    columns = ANSI::Columns.new(list, :align=>:right)

    columns.to_s(3)

The output will be:

    xx yy  z
    xx  y zz
    xx yy  z

## Format

Lastly, columns can be augmented with ANSI codes. This is done through
a formatting block. The block can take up to three parameters, the cell
content, the column and row numbers, or the cell and the column and row
numbers.

    list = %w{a b c d e f g h i j k l}

    columns = ANSI::Columns.new(list){ |c,r| r % 2 == 0 ? :red : :blue }

    out = columns.to_s(4)

    out.assert == (
      "\e[31ma \e[0m\e[31md \e[0m\e[31mg \e[0m\e[31mj \e[0m\n" +
      "\e[34mb \e[0m\e[34me \e[0m\e[34mh \e[0m\e[34mk \e[0m\n" +
      "\e[31mc \e[0m\e[31mf \e[0m\e[31mi \e[0m\e[31ml \e[0m\n"
    )


# ANSI::Table

The ANSI::Table class can be used to output tabular data with nicely
formated ASCII cell borders.

    require 'ansi/table'

The constructor takes an 2-dimensional array.

    data = [
      [ 10, 20, 30 ],
      [ 20, 10, 20 ],
      [ 50, 40, 20 ]
    ]

    table = ANSI::Table.new(data)

    table.to_s

The output will be:

    +----+----+----+
    | 10 | 20 | 30 |
    | 20 | 10 | 20 |
    | 50 | 40 | 20 |
    +----+----+----+



# ANSI::Diff

    require 'ansi/diff'

    a = 'abcYefg'
    b = 'abcXefg'

    diff = ANSI::Diff.new(a,b)

    diff.to_s.assert == "\e[31mabc\e[0m\e[33mYefg\e[0m\n\e[31mabc\e[0mXefg"

Try another.

    a = 'abc'
    b = 'abcdef'

    diff = ANSI::Diff.new(a,b)

    diff.to_s.assert == "\e[31mabc\e[0m\n\e[31mabc\e[0mdef"

And another.

    a = 'abcXXXghi'
    b = 'abcdefghi'

    diff = ANSI::Diff.new(a,b)

    diff.to_s.assert == "\e[31mabc\e[0m\e[33mXXXghi\e[0m\n\e[31mabc\e[0mdefghi"

And another.

    a = 'abcXXXdefghi'
    b = 'abcdefghi'

    diff = ANSI::Diff.new(a,b)

    diff.to_s.assert == "\e[31mabc\e[0m\e[33mXXX\e[0m\e[35mdefghi\e[0m\n\e[31mabc\e[0m\e[35mdefghi\e[0m"

Comparison that is mostly different.

    a = 'abcpppz123'
    b = 'abcxyzzz43'

    diff = ANSI::Diff.new(a,b)

    diff.to_s.assert == "\e[31mabc\e[0m\e[33mpppz123\e[0m\n\e[31mabc\e[0mxyzzz43"


# ANSI::BBCode

The BBCode module provides methods for converting between
BBCodes, basic HTML and ANSI codes.

    require 'ansi/bbcode'

BBCodes are color and style codes in square brackets, quite
popular with on line forums.

    bbcode = "this is [COLOR=red]red[/COLOR], this is [B]bold[/B]"

We can convert this to ANSI code simply enough:

    ansi = ANSI::BBCode.bbcode_to_ansi(bbcode)

    ansi.assert == "this is \e[0;31mred\e[0m, this is \e[1mbold\e[0m\n"

In addition the BBCode module supports conversion to simple HTML.

    html = ANSI::BBCode.bbcode_to_html(bbcode)

    html.assert == "this is <font color=\"red\">red</font>, this is <strong>bold</strong><br />\n"


# ANSI::Terminal

We should be ables to get the terminal width via the `terminal_width` method.

    width = ANSI::Terminal.terminal_width

    Fixnum.assert === width