ansi 1.4.3 → 1.6.0

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"
+

data/demo/10_bbcode.md

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

data/demo/11_terminal.md

@@ -0,0 +1,8 @@
+# ANSI::Terminal
+
+We should be able to get the terminal width via the `terminal_width` method.
+
+    width = ANSI::Terminal.terminal_width
+
+    Integer.assert === width
+

data/lib/ansi/chart.rb

@@ -1,7 +1,5 @@
 module ANSI
 
-  require 'ansi/version'
-
   # Table of codes used throughout the system.
   #
   # @see http://en.wikipedia.org/wiki/ANSI_escape_code
@@ -9,7 +7,7 @@ module ANSI
     :clear            => 0,
     :reset            => 0,
     :bright           => 1,
-    :bold             => 1, 
+    :bold             => 1,
     :faint            => 2,
     :dark             => 2,
     :italic           => 3,
@@ -23,7 +21,6 @@ module ANSI
     :inverse          => 7,
     :reverse          => 7,
     :negative         => 7,
-    :concealed        => 8,
     :swap             => 7,
     :conceal          => 8,
     :concealed        => 8,
@@ -87,12 +84,17 @@ module ANSI
 
   #
   SPECIAL_CHART = {
-    :save             => "\e[s",   # Save current cursor positon.
-    :restore          => "\e[u",   # Restore saved cursor positon.
-    :clear_line       => "\e[K",   # Clear to the end of the current line.
-    :clr              => "\e[K",   # Clear to the end of the current line.
-    :clear_screen     => "\e[2J",  # Clear the screen and move cursor to home.
-    :cls              => "\e[2J",  # Clear the screen and move cursor to home.
+    :save             => "\e[s",     # Save current cursor positon.
+    :restore          => "\e[u",     # Restore saved cursor positon.
+    :clear_eol        => "\e[K",     # Clear to the end of the current line.
+    :clr              => "\e[K",     # Clear to the end of the current line.
+    :clear_right      => "\e[0K",    # Clear to the end of the current line.
+    :clear_left       => "\e[1K",    # Clear to the start of the current line.
+    :clear_line       => "\e[2K",    # Clear the entire current line.
+    :clear_screen     => "\e[2J",    # Clear the screen and move cursor to home.
+    :cls              => "\e[2J",    # Clear the screen and move cursor to home.
+    :cursor_hide      => "\e[?25l",  # Hide the cursor.
+    :cursor_show      => "\e[?25h"   # Show the cursor.
   }
 
 end

data/lib/ansi/code.rb

@@ -1,5 +1,11 @@
 module ANSI
 
+  # Global variable can be used to prevent ANSI codes
+  # from being used in ANSI's methods that do so to string.
+  #
+  # NOTE: This has no effect on methods that return ANSI codes.
+  $ansi = true
+
   if RUBY_PLATFORM =~ /(win32|w32)/
     begin
       require 'Win32/Console/ANSI'
@@ -11,18 +17,12 @@ module ANSI
 
   require 'ansi/constants'
 
-  # Global variialbe can be used to prevent ANSI codes
-  # from being used in ANSI's methods that do so to string.
-  #
-  # NOTE: This has no effect of methods that return ANSI codes.
-  $ansi = true
-
   # TODO: up, down, right, left, etc could have yielding methods too?
 
   # ANSI Codes
   #
   # Ansi::Code module makes it very easy to use ANSI codes.
-  # These are esspecially nice for beautifying shell output.
+  # These are especially nice for beautifying shell output.
   #
   #   Ansi::Code.red + "Hello" + Ansi::Code.blue + "World"
   #   => "\e[31mHello\e[34mWorld"
@@ -32,7 +32,7 @@ module ANSI
   #
   # IMPORTANT! Do not mixin Ansi::Code, instead use {ANSI::Mixin}.
   #
-  # See {ANSI::Code::CHART} for list of all supported codes.
+  # See {ANSI::CHART} for list of all supported codes.
   #
   module Code
     extend self
@@ -56,59 +56,6 @@ module ANSI
       %w{black red green yellow blue magenta cyan white}
     end
 
-=begin
-    styles.each do |style|
-      module_eval <<-END, __FILE__, __LINE__
-        def #{style}(string=nil)
-          if string
-            return string unless $ansi
-            #warn "use ANSI block notation for future versions"
-            return "\#{#{style.upcase}}\#{string}\#{ENDCODE}"
-          end
-          if block_given?
-            return yield unless $ansi
-            return "\#{#{style.upcase}}\#{yield}\#{ENDCODE}"
-          end
-          #{style.upcase}
-        end
-      END
-    end
-=end
-
-=begin
-    # Dynamically create color methods.
-
-    colors.each do |color|
-      module_eval <<-END, __FILE__, __LINE__
-        def #{color}(string=nil)
-          if string
-            return string unless $ansi
-            #warn "use ANSI block notation for future versions"
-            return "\#{#{color.upcase}}\#{string}\#{ENDCODE}"
-          end
-          if block_given?
-            return yield unless $ansi
-            return "\#{#{color.upcase}}\#{yield}\#{ENDCODE}"
-          end
-          #{color.upcase}
-        end
-
-        def on_#{color}(string=nil)
-          if string
-            return string unless $ansi
-            #warn "use ANSI block notation for future versions"
-            return "\#{ON_#{color.upcase}}\#{string}\#{ENDCODE}"
-          end
-          if block_given?
-            return yield unless $ansi
-            return "\#{ON_#{color.upcase}}\#{yield}\#{ENDCODE}"
-          end
-          ON_#{color.upcase}
-        end
-      END
-    end
-=end
-
     # Return ANSI code given a list of symbolic names.
     def [](*codes)
       code(*codes)
@@ -165,10 +112,10 @@ module ANSI
     end
 
     # TODO: How to deal with position codes when $ansi is false?
-    # Should we reaise an error or just not push the codes?
+    # Should we raise an error or just not push the codes?
     # For now, we will leave this it as is.
 
-    # Like +move+ but returns to original positon after
+    # Like +move+ but returns to original position after
     # yielding the block.
     def display(line, column=0) #:yield:
       result = "\e[s"
@@ -188,25 +135,27 @@ module ANSI
       "\e[#{line.to_i};#{column.to_i}H"
     end
 
-    # Move cursor up a specificed number of spaces.
+    # Move cursor up a specified number of spaces.
     def up(spaces=1)
       "\e[#{spaces.to_i}A"
     end
 
-    # Move cursor down a specificed number of spaces.
+    # Move cursor down a specified number of spaces.
     def down(spaces=1)
       "\e[#{spaces.to_i}B"
     end
 
-    # Move cursor left a specificed number of spaces.
+    # Move cursor left a specified number of spaces.
     def left(spaces=1)
       "\e[#{spaces.to_i}D"
     end
+    alias :back :left
 
-    # Move cursor right a specificed number of spaces.
+    # Move cursor right a specified number of spaces.
     def right(spaces=1)
       "\e[#{spaces.to_i}C"
     end
+    alias :forward :right
 
     ##
     #def position
@@ -228,6 +177,7 @@ module ANSI
       if block_given?
         string = yield.to_s
       else
+        # first argument must be the string
         string = codes.shift.to_s
       end
 
@@ -260,7 +210,7 @@ module ANSI
     # Alias for #ansi method.
     #
     # @deprecated
-    #   Here for backward scompatibility.
+    #   Here for backward compatibility.
     alias_method :style, :ansi
 
     # Alias for #unansi method.
@@ -285,7 +235,7 @@ module ANSI
     # Also resolves :random and :on_random.
     #
     # @param codes [Array<Symbol,Integer]
-    #   Symbols or integers to covnert to ANSI code.
+    #   Symbols or integers to convert to ANSI code.
     #
     # @return [String] ANSI code
     def code(*codes)
@@ -296,11 +246,18 @@ module ANSI
           when Integer
             code
           when Array
-            rgb(*code)
-          when :random
+            rgb_code(*code)
+          when :random, 'random'
             random
-          when :on_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
@@ -318,30 +275,69 @@ module ANSI
       (background ? 40 : 30) + rand(8)
     end
 
+    # 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.
+    #
+    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
+
+  #private
+
     # Creates an xterm-256 color from rgb value.
     #
     # @param background [Boolean]
     #   Use `true` for background color, otherwise foreground color.
     #
-    def rgb(red, green, blue, background=false)
-      "#{background ? 48 : 38};5;#{rgb_value(red, green, blue)}"
+    def rgb_code(red, green, blue, background=false)
+      "#{background ? 48 : 38};5;#{rgb_256(red, green, blue)}"
     end
 
-    # Creates an xterm-256 color from a CSS-style color string.
-    def hex(string, background=false)
+    # 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.
+    #
+    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(r, g, b, background)
+      rgb_code(r, g, b, background)
     end
 
-    private
-
-    # Gets closest xterm-256 color.
+    # Given red, green and blue values between 0 and 255, this method
+    # returns the closest XTerm 256 color value.
+    #
     def rgb_256(r, g, b)
-      r, g, b = [r, g, b].map{ |c| rgb_valid(c); (6 * (c.to_f / 256.0)).to_i }
+      # 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 outside 0-255 range" if v > 255
+      raise ArgumentError, "RGB value is outside 0-255 range -- #{v}" if v > 255
       v
     end
 

data/lib/ansi/columns.rb

@@ -1,4 +1,3 @@
-require 'ansi'
 require 'ansi/terminal'
 
 module ANSI

data/lib/ansi/terminal/curses.rb

@@ -10,14 +10,13 @@ module ANSI
     #
     # Curses savvy getc().
     #
-    #
     def get_character(input = STDIN)
       Curses.getch()
     end
 
     def terminal_size
       Curses.init_screen
-      w, r = Curses.cols, Curses.rows
+      w, r = Curses.cols, Curses.lines
       Curses.close_screen
       return w, r
     end

data/lib/ansi/terminal/stty.rb

@@ -9,11 +9,11 @@ module ANSI
     #CHARACTER_MODE = "stty"    # For Debugging purposes only.
 
     #
-    # Unix savvy getc().  (Second choice.)
+    # Unix savvy getc().  (second choice)
     #
     # *WARNING*:  This method requires the external "stty" program!
     #
-    def get_character( input = STDIN )
+    def get_character(input = STDIN)
       raw_no_echo_mode
 
       begin

data/lib/ansi/terminal.rb

@@ -22,7 +22,7 @@ module ANSI
     # Be warned: Here be dragons!
     #
     begin
-      require 'ansi/terminal/' + (mode = modes.pop)
+      require 'ansi/terminal/' + (mode = modes.shift)
       CHARACTER_MODE = mode
     rescue LoadError
       retry