highline 1.6.2 → 1.6.5

data/CHANGELOG

@@ -2,6 +2,30 @@
 
 Below is a complete listing of changes for each revision of HighLine.
 
+== 1.6.5
+
+* HighLine#list() now correctly handles empty lists (fix by Lachlan Dowding).
+* HighLine#list() now supports <tt>:uneven_columns_across</tt> and
+  <tt>:uneven_columns_down</tt> modes.
+
+== 1.6.4
+
+* Add introspection methods to color_scheme: definition, keys, to_hash.
+* Add tests for new methods.
+
+== 1.6.3
+
+* Add color NONE.
+* Add RGB color capability.
+* Made 'color' available as a class or instance method of HighLine, for
+  instance: HighLine.color("foo", :blue)) or highline_obj.color("foo", :blue)
+  are now both possible and equivalent.
+* Add HighLine::String class with convenience methods: #color (alias
+  #foreground), #on (alias #background), colors, and styles. See
+  lib/string_extensions.rb.
+* Add (optional) ability to extend String with the same convenience methods from
+  HighLine::String, using Highline.colorize_strings.
+
 == 1.6.2
 
 * Correctly handle STDIN being closed before we receive any data (fix by

data/Rakefile

@@ -1,6 +1,6 @@
-require "rake/rdoctask"
+require "rdoc/task"
 require "rake/testtask"
-require "rake/gempackagetask"
+require "rubygems/package_task"
 
 require "rubygems"
 
@@ -12,7 +12,7 @@ task :default => [:test]
 
 Rake::TestTask.new do |test|
   test.libs       << "test"
-  test.test_files =  [ "test/ts_all.rb" ]
+  test.test_files =  [ "test/ts_all.rb"]
   test.verbose    =  true
 end
 
@@ -63,7 +63,7 @@ minutes of work.
 END_DESC
 end
 
-Rake::GemPackageTask.new(spec) do |pkg|
+Gem::PackageTask.new(spec) do |pkg|
   pkg.need_zip = true
   pkg.need_tar = true
 end

data/lib/highline.rb

@@ -17,6 +17,7 @@ require "highline/system_extensions"
 require "highline/question"
 require "highline/menu"
 require "highline/color_scheme"
+require "highline/style"
 
 #
 # A HighLine object is a "high-level line oriented" shell over an input and an 
@@ -29,7 +30,7 @@ require "highline/color_scheme"
 #
 class HighLine
   # The version of the installed library.
-  VERSION = "1.6.2".freeze
+  VERSION = "1.6.5".freeze
   
   # An internal HighLine error.  User code does not need to trap this.
   class QuestionError < StandardError
@@ -49,6 +50,13 @@ class HighLine
     @@use_color
   end
   
+  # For checking if the current version of HighLine supports RGB colors
+  # Usage: HighLine.supports_rgb_color? rescue false   # rescue for compatibility with older versions
+  # Note: color usage also depends on HighLine.use_color being set
+  def self.supports_rgb_color?
+    true
+  end
+  
   # The setting used to disable EOF tracking.
   @@track_eof = true
   
@@ -83,62 +91,85 @@ class HighLine
   #
   # Embed in a String to clear all previous ANSI sequences.  This *MUST* be 
   # done before the program exits!
-  # 
-  CLEAR      = "\e[0m"
-  # An alias for CLEAR.
-  RESET      = CLEAR
-  # Erase the current line of terminal output.
-  ERASE_LINE = "\e[K"
-  # Erase the character under the cursor.
-  ERASE_CHAR = "\e[P"
-  # The start of an ANSI bold sequence.
-  BOLD       = "\e[1m"
-  # The start of an ANSI dark sequence.  (Terminal support uncommon.)
-  DARK       = "\e[2m"
-  # The start of an ANSI underline sequence.
-  UNDERLINE  = "\e[4m"
-  # An alias for UNDERLINE.
-  UNDERSCORE = UNDERLINE
-  # The start of an ANSI blink sequence.  (Terminal support uncommon.)
-  BLINK      = "\e[5m"
-  # The start of an ANSI reverse sequence.
-  REVERSE    = "\e[7m"
-  # The start of an ANSI concealed sequence.  (Terminal support uncommon.)
-  CONCEALED  = "\e[8m"
-
-  # Set the terminal's foreground ANSI color to black.
-  BLACK      = "\e[30m"
-  # Set the terminal's foreground ANSI color to red.
-  RED        = "\e[31m"
-  # Set the terminal's foreground ANSI color to green.
-  GREEN      = "\e[32m"
-  # Set the terminal's foreground ANSI color to yellow.
-  YELLOW     = "\e[33m"
-  # Set the terminal's foreground ANSI color to blue.
-  BLUE       = "\e[34m"
-  # Set the terminal's foreground ANSI color to magenta.
-  MAGENTA    = "\e[35m"
-  # Set the terminal's foreground ANSI color to cyan.
-  CYAN       = "\e[36m"
-  # Set the terminal's foreground ANSI color to white.
-  WHITE      = "\e[37m"
-
-  # Set the terminal's background ANSI color to black.
-  ON_BLACK   = "\e[40m"
-  # Set the terminal's background ANSI color to red.
-  ON_RED     = "\e[41m"
-  # Set the terminal's background ANSI color to green.
-  ON_GREEN   = "\e[42m"
-  # Set the terminal's background ANSI color to yellow.
-  ON_YELLOW  = "\e[43m"
-  # Set the terminal's background ANSI color to blue.
-  ON_BLUE    = "\e[44m"
-  # Set the terminal's background ANSI color to magenta.
-  ON_MAGENTA = "\e[45m"
-  # Set the terminal's background ANSI color to cyan.
-  ON_CYAN    = "\e[46m"
-  # Set the terminal's background ANSI color to white.
-  ON_WHITE   = "\e[47m"
+  #
+  
+  ERASE_LINE_STYLE = Style.new(:name=>:erase_line, :builtin=>true, :code=>"\e[K")  # Erase the current line of terminal output
+  ERASE_CHAR_STYLE = Style.new(:name=>:erase_char, :builtin=>true, :code=>"\e[P")  # Erase the character under the cursor.
+  CLEAR_STYLE      = Style.new(:name=>:clear,      :builtin=>true, :code=>"\e[0m") # Clear color settings 
+  RESET_STYLE      = Style.new(:name=>:reset,      :builtin=>true, :code=>"\e[0m") # Alias for CLEAR.
+  BOLD_STYLE       = Style.new(:name=>:bold,       :builtin=>true, :code=>"\e[1m") # Bold; Note: bold + a color works as you'd expect,
+                                                              # for example bold black. Bold without a color displays
+                                                              # the system-defined bold color (e.g. red on Mac iTerm)
+  DARK_STYLE       = Style.new(:name=>:dark,       :builtin=>true, :code=>"\e[2m") # Dark; support uncommon
+  UNDERLINE_STYLE  = Style.new(:name=>:underline,  :builtin=>true, :code=>"\e[4m") # Underline
+  UNDERSCORE_STYLE = Style.new(:name=>:underscore, :builtin=>true, :code=>"\e[4m") # Alias for UNDERLINE
+  BLINK_STYLE      = Style.new(:name=>:blink,      :builtin=>true, :code=>"\e[5m") # Blink; support uncommon
+  REVERSE_STYLE    = Style.new(:name=>:reverse,    :builtin=>true, :code=>"\e[7m") # Reverse foreground and background
+  CONCEALED_STYLE  = Style.new(:name=>:concealed,  :builtin=>true, :code=>"\e[8m") # Concealed; support uncommon
+  
+  STYLES = %w{CLEAR RESET BOLD DARK UNDERLINE UNDERSCORE BLINK REVERSE CONCEALED}
+
+  # These RGB colors are approximate; see http://en.wikipedia.org/wiki/ANSI_escape_code
+  BLACK_STYLE      = Style.new(:name=>:black,      :builtin=>true, :code=>"\e[30m", :rgb=>[  0,  0,  0])
+  RED_STYLE        = Style.new(:name=>:red,        :builtin=>true, :code=>"\e[31m", :rgb=>[128,  0,  0])
+  GREEN_STYLE      = Style.new(:name=>:green,      :builtin=>true, :code=>"\e[32m", :rgb=>[  0,128,  0])
+  BLUE_STYLE       = Style.new(:name=>:blue,       :builtin=>true, :code=>"\e[34m", :rgb=>[  0,  0,128])
+  YELLOW_STYLE     = Style.new(:name=>:yellow,     :builtin=>true, :code=>"\e[33m", :rgb=>[128,128,  0])
+  MAGENTA_STYLE    = Style.new(:name=>:magenta,    :builtin=>true, :code=>"\e[35m", :rgb=>[128,  0,128])
+  CYAN_STYLE       = Style.new(:name=>:cyan,       :builtin=>true, :code=>"\e[36m", :rgb=>[  0,128,128])
+  # On Mac OSX Terminal, white is actually gray
+  WHITE_STYLE      = Style.new(:name=>:white,      :builtin=>true, :code=>"\e[37m", :rgb=>[192,192,192]) 
+  # Alias for WHITE, since WHITE is actually a light gray on Macs
+  GRAY_STYLE       = Style.new(:name=>:gray,       :builtin=>true, :code=>"\e[37m", :rgb=>[192,192,192])
+  # On Mac OSX Terminal, this is black foreground, or bright white background. 
+  # Also used as base for RGB colors, if available
+  NONE_STYLE       = Style.new(:name=>:none,       :builtin=>true, :code=>"\e[38m", :rgb=>[  0,  0,  0]) 
+  
+  BASIC_COLORS = %w{BLACK RED GREEN YELLOW BLUE MAGENTA CYAN WHITE GRAY NONE}
+  
+  colors = BASIC_COLORS.dup
+  BASIC_COLORS.each do |color|
+    bright_color = "BRIGHT_#{color}"
+    colors << bright_color
+    const_set bright_color+'_STYLE', const_get(color + '_STYLE').bright
+  end
+  COLORS = colors
+  
+  colors.each do |color|
+    const_set color, const_get("#{color}_STYLE").code
+    const_set "ON_#{color}_STYLE", const_get("#{color}_STYLE").on
+    const_set "ON_#{color}", const_get("ON_#{color}_STYLE").code
+  end
+  ON_NONE_STYLE.rgb = [255,255,255] # Override; white background
+  
+  STYLES.each do |style|
+    const_set style, const_get("#{style}_STYLE").code
+  end
+  
+  # For RGB colors:
+  def self.const_missing(name)
+    if name.to_s =~ /^(ON_)?(RGB_)([A-F0-9]{6})(_STYLE)?$/ # RGB color
+      on = $1
+      suffix = $4
+      if suffix
+        code_name = $1.to_s + $2 + $3
+      else
+        code_name = name.to_s
+      end
+      style_name = code_name + '_STYLE'
+      style = Style.rgb($3)
+      style = style.on if on
+      const_set(style_name, style)
+      const_set(code_name, style.code)
+      if suffix
+        style
+      else
+        style.code
+      end
+    else
+      raise NameError, "Bad color or uninitialized constant #{name}"
+    end
+  end
 
   #
   # Create an instance of HighLine, connected to the streams _input_
@@ -328,19 +359,34 @@ class HighLine
   # This method returns the original _string_ unchanged if HighLine::use_color? 
   # is +false+.
   #
-  def color( string, *colors )
-    return string unless self.class.use_color?
-    
-    colors.map! do |c|
-      if self.class.using_color_scheme? and self.class.color_scheme.include? c
-        self.class.color_scheme[c]
-      elsif c.is_a? Symbol
-        self.class.const_get(c.to_s.upcase)
-      else
-        c
-      end
-    end
-    "#{colors.flatten.join}#{string}#{CLEAR}"
+  def self.color( string, *colors )
+    return string unless self.use_color?
+    Style(*colors).color(string)
+  end
+
+  # In case you just want the color code, without the embedding and the CLEAR
+  def self.color_code(*colors)
+    Style(*colors).code
+  end
+  
+  # Works as an instance method, same as the class method
+  def color_code(*colors)
+    self.class.color_code(*colors)
+  end
+  
+  # Works as an instance method, same as the class method
+  def color(*args)
+    self.class.color(*args)
+  end
+  
+  # Remove color codes from a string
+  def self.uncolor(string)
+    Style.uncolor(string)
+  end
+  
+  # Works as an instance method, same as the class method
+  def uncolor(string)
+    self.class.uncolor(string)
   end
   
   # 
@@ -352,20 +398,25 @@ class HighLine
   # to list.  A specified _mode_ controls how that list is formed and _option_
   # has different effects, depending on the _mode_.  Recognized modes are:
   #
-  # <tt>:columns_across</tt>::  _items_ will be placed in columns, flowing
-  #                             from left to right.  If given, _option_ is the
-  #                             number of columns to be used.  When absent, 
-  #                             columns will be determined based on _wrap_at_
-  #                             or a default of 80 characters.
-  # <tt>:columns_down</tt>::    Identical to <tt>:columns_across</tt>, save
-  #                             flow goes down.
-  # <tt>:inline</tt>::          All _items_ are placed on a single line.  The
-  #                             last two _items_ are separated by _option_ or
-  #                             a default of " or ".  All other _items_ are
-  #                             separated by ", ".
-  # <tt>:rows</tt>::            The default mode.  Each of the _items_ is
-  #                             placed on it's own line.  The _option_
-  #                             parameter is ignored in this mode.
+  # <tt>:columns_across</tt>::         _items_ will be placed in columns,
+  #                                    flowing from left to right.  If given,
+  #                                    _option_ is the number of columns to be
+  #                                    used.  When absent, columns will be
+  #                                    determined based on _wrap_at_ or a
+  #                                    default of 80 characters.
+  # <tt>:columns_down</tt>::           Identical to <tt>:columns_across</tt>,
+  #                                    save flow goes down.
+  # <tt>:uneven_columns_across</tt>::  Like <tt>:columns_across</tt> but each
+  #                                    column is sized independently.
+  # <tt>:uneven_columns_down</tt>::    Like <tt>:columns_down</tt> but each
+  #                                    column is sized independently.
+  # <tt>:inline</tt>::                 All _items_ are placed on a single line.
+  #                                    The last two _items_ are separated by
+  #                                    _option_ or a default of " or ".  All
+  #                                    other _items_ are separated by ", ".
+  # <tt>:rows</tt>::                   The default mode.  Each of the _items_ is
+  #                                    placed on it's own line.  The _option_
+  #                                    parameter is ignored in this mode.
   # 
   # Each member of the _items_ Array is passed through ERb and thus can contain
   # their own expansions.  Color escape expansions do not contribute to the 
@@ -376,58 +427,157 @@ class HighLine
       ERB.new(item, nil, "%").result(binding)
     end
     
-    case mode
-    when :inline
-      option = " or " if option.nil?
+    if items.empty?
+      ""
+    else
+      case mode
+      when :inline
+        option = " or " if option.nil?
+        
+        if items.size == 1
+          items.first
+        else
+          items[0..-2].join(", ") + "#{option}#{items.last}"
+        end
+      when :columns_across, :columns_down
+        max_length = actual_length(
+          items.max { |a, b| actual_length(a) <=> actual_length(b) }
+        )
+
+        if option.nil?
+          limit  = @wrap_at || 80
+          option = (limit + 2) / (max_length + 2)
+        end
+
+        items     = items.map do |item|
+          pad = max_length + (item.length - actual_length(item))
+          "%-#{pad}s" % item
+        end
+        row_count = (items.size / option.to_f).ceil
       
-      case items.size
-      when 0
-        ""
-      when 1
-        items.first
-      when 2
-        "#{items.first}#{option}#{items.last}"
-      else
-        items[0..-2].join(", ") + "#{option}#{items.last}"
-      end
-    when :columns_across, :columns_down
-      max_length = actual_length(
-        items.max { |a, b| actual_length(a) <=> actual_length(b) }
-      )
-
-      if option.nil?
-        limit  = @wrap_at || 80
-        option = (limit + 2) / (max_length + 2)
-      end
+        if mode == :columns_across
+          rows = Array.new(row_count) { Array.new }
+          items.each_with_index do |item, index|
+            rows[index / option] << item
+          end
 
-      items     = items.map do |item|
-        pad = max_length + (item.length - actual_length(item))
-        "%-#{pad}s" % item
-      end
-      row_count = (items.size / option.to_f).ceil
+          rows.map { |row| row.join("  ") + "\n" }.join
+        else
+          columns = Array.new(option) { Array.new }
+          items.each_with_index do |item, index|
+            columns[index / row_count] << item
+          end
       
-      if mode == :columns_across
-        rows = Array.new(row_count) { Array.new }
-        items.each_with_index do |item, index|
-          rows[index / option] << item
+          list = ""
+          columns.first.size.times do |index|
+            list << columns.map { |column| column[index] }.
+                            compact.join("  ") + "\n"
+          end
+          list
         end
+      when :uneven_columns_across
+        if option.nil?
+          limit = @wrap_at || 80
+          items.size.downto(1) do |column_count|
+            row_count = (items.size / column_count.to_f).ceil
+            rows      = Array.new(row_count) { Array.new }
+            items.each_with_index do |item, index|
+              rows[index / column_count] << item
+            end
 
-        rows.map { |row| row.join("  ") + "\n" }.join
-      else
-        columns = Array.new(option) { Array.new }
-        items.each_with_index do |item, index|
-          columns[index / row_count] << item
+            widths = Array.new(column_count, 0)
+            rows.each do |row|
+              row.each_with_index do |field, column|
+                size           = field.size
+                widths[column] = size if size > widths[column]
+              end
+            end
+
+            if column_count == 1 or
+               widths.inject(0) { |sum, n| sum + n + 2 } <= limit + 2
+              return rows.map { |row|
+                row.zip(widths).map { |field, i| "%-#{i}s" % field }.
+                                join("  ") + "\n"
+              }.join
+            end
+          end
+        else
+          row_count = (items.size / option.to_f).ceil
+          rows      = Array.new(row_count) { Array.new }
+          items.each_with_index do |item, index|
+            rows[index / option] << item
+          end
+
+          widths = Array.new(option, 0)
+          rows.each do |row|
+            row.each_with_index do |field, column|
+              size           = field.size
+              widths[column] = size if size > widths[column]
+            end
+          end
+
+          return rows.map { |row|
+            row.zip(widths).map { |field, i| "%-#{i}s" % field }.join("  ") +
+            "\n"
+          }.join
         end
-      
-        list = ""
-        columns.first.size.times do |index|
-          list << columns.map { |column| column[index] }.
-                          compact.join("  ") + "\n"
+      when :uneven_columns_down
+        if option.nil?
+          limit = @wrap_at || 80
+          items.size.downto(1) do |column_count|
+            row_count = (items.size / column_count.to_f).ceil
+            columns   = Array.new(column_count) { Array.new }
+            items.each_with_index do |item, index|
+              columns[index / row_count] << item
+            end
+
+            widths = Array.new(column_count, 0)
+            columns.each_with_index do |column, i|
+              column.each do |field|
+                size      = field.size
+                widths[i] = size if size > widths[i]
+              end
+            end
+
+            if column_count == 1 or
+               widths.inject(0) { |sum, n| sum + n + 2 } <= limit + 2
+              list = ""
+              columns.first.size.times do |index|
+                list << columns.zip(widths).
+                                map { |column, width| "%-#{width}s" %
+                                                      column[index] }.
+                                compact.join("  ").strip + "\n"
+              end
+              return list
+            end
+          end
+        else
+          row_count = (items.size / option.to_f).ceil
+          columns   = Array.new(option) { Array.new }
+          items.each_with_index do |item, index|
+            columns[index / row_count] << item
+          end
+
+          widths = Array.new(option, 0)
+          columns.each_with_index do |column, i|
+            column.each do |field|
+              size      = field.size
+              widths[i] = size if size > widths[i]
+            end
+          end
+
+          list = ""
+          columns.first.size.times do |index|
+            list << columns.zip(widths).
+                            map { |column, width| "%-#{width}s" %
+                                                  column[index] }.
+                            compact.join("  ").strip + "\n"
+          end
+          return list
         end
-        list
+      else
+        items.map { |i| "#{i}\n" }.join
       end
-    else
-      items.map { |i| "#{i}\n" }.join
     end
   end
   
@@ -540,11 +690,11 @@ class HighLine
         @answers  << ask(@question)
         @gather   -= 1
       end
-    when String, Regexp
+    when ::String, Regexp
       @answers << ask(@question)
 
       original_question.question = ""
-      until (@gather.is_a?(String) and @answers.last.to_s == @gather) or
+      until (@gather.is_a?(::String) and @answers.last.to_s == @gather) or
             (@gather.is_a?(Regexp) and @answers.last.to_s =~ @gather)
         @question =  original_question
         @answers  << ask(@question)
@@ -761,3 +911,6 @@ class HighLine
     string_with_escapes.gsub(/\e\[\d{1,2}m/, "").length
   end
 end
+
+require "highline/string_extensions"
+