ansi 1.4.3 → 1.5.0

data/demo/01_ansicode.md

@@ -0,0 +1,65 @@
+# 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"
+
+ANSI also supports XTerm 256 color mode using red, blue and green values
+with the `#rgb` method.
+
+    str = ANSI::Code.rgb(0, 255, 0)
+    str.assert == "\e[38;5;46m"
+
+Or using CSS style hex codes as well.
+
+    str = ANSI::Code.rgb("#00FF00")
+    str.assert == "\e[38;5;46m"
+
+Both of these methods can take blocks to wrap text in the color and clear codes.
+
+    str = ANSI::Code.rgb("#00FF00"){ "Hello" }
+    str.assert == "\e[38;5;46mHello\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.
+

data/demo/{02_core.rdoc → 02_core.md}

@@ -1,11 +1,11 @@
-= String Extensions
+# 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'
+    require 'ansi/core'
 
-  str = "Hello".ansi(:red) + "World".ansi(:blue)
-  str.assert == "\e[31mHello\e[0m\e[34mWorld\e[0m"
+    str = "Hello".ansi(:red) + "World".ansi(:blue)
+    str.assert == "\e[31mHello\e[0m\e[34mWorld\e[0m"
 

data/demo/03_logger.md

@@ -0,0 +1,30 @@
+# 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"}
+

data/demo/04_progressbar.md

@@ -0,0 +1,62 @@
+# 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)
+

data/demo/{05_mixin.rdoc → 05_mixin.md}

@@ -1,37 +1,37 @@
-= ANSI::Mixin
+# 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'
+    require 'ansi/mixin'
 
 In this demonstration we will simply include it in the
 core String class.
 
-  class ::String
-    include ANSI::Mixin
-  end
+    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"
+    "roses".red.assert == "\e[31mroses\e[0m"
 
-  "violets".blue.assert == "\e[34mviolets\e[0m"
+    "violets".blue.assert == "\e[34mviolets\e[0m"
 
-  "sugar".italic.assert == "\e[3msugar\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"
+    "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"
+    "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"
+    "b&w".white_on_black.assert == "\e[37m\e[40mb&w\e[0m"
 

data/demo/{06_string.rdoc → 06_string.md}

@@ -1,52 +1,52 @@
-= ANSI::String
+# 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'
+    require 'ansi/string'
 
-  flower1 = ANSI::String.new("Roses")
-  flower2 = ANSI::String.new("Violets")
+    flower1 = ANSI::String.new("Roses")
+    flower2 = ANSI::String.new("Violets")
 
 Like any other string.
 
-  flower1.to_s.assert == "Roses"
-  flower2.to_s.assert == "Violets"
+    flower1.to_s.assert == "Roses"
+    flower2.to_s.assert == "Violets"
 
 Bet now we can add color.
 
-  flower1.red!
-  flower2.blue!
+    flower1.red!
+    flower2.blue!
 
-  flower1.to_s.assert == "\e[31mRoses\e[0m"
-  flower2.to_s.assert == "\e[34mViolets\e[0m"
+    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
+    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 = flower1 + ' ' + flower2
+    flowers.to_s.assert == "\e[31mRoses\e[0m \e[34mViolets\e[0m"
 
-  flowers.size.assert == 13
+    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"
+    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"
+    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

data/demo/07_columns.md

@@ -0,0 +1,89 @@
+# 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"
+    )
+

data/demo/08_table.md

@@ -0,0 +1,28 @@
+# 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 |
+    +----+----+----+
+
+

data/demo/09_diff.md

@@ -0,0 +1,47 @@
+# 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"
+