highline 2.0.0.pre.develop.2 → 2.0.0.pre.develop.4

data/lib/highline/builtin_styles.rb

@@ -1,11 +1,16 @@
 #coding: utf-8
 
 class HighLine
+  # Builtin Styles that are included at HighLine initialization.
+  # It has the basic styles like :bold and :underline.
   module BuiltinStyles
+    # Included callback
+    # @param base [Class, Module] base class
     def self.included(base)
       base.extend ClassMethods
     end
 
+    # Basic styles' ANSI escape codes like :bold => "\e[1m"
     STYLE_LIST = {
       erase_line: "\e[K",
       erase_char: "\e[P",
@@ -27,8 +32,10 @@ class HighLine
      const_set style + "_STYLE", Style.new(name: style_name, code: code, builtin: true)
     end
 
+    # Basic Style names like CLEAR, BOLD, UNDERLINE
     STYLES = %w{CLEAR RESET BOLD DARK UNDERLINE UNDERSCORE BLINK REVERSE CONCEALED}
 
+    # A Hash with the basic colors an their ANSI escape codes.
     COLOR_LIST = {
       black:   { code: "\e[30m", rgb: [0, 0, 0] },
       red:     { code: "\e[31m", rgb: [128, 0, 0] },
@@ -56,6 +63,7 @@ class HighLine
      const_set color + "_STYLE", style
     end
 
+    # The builtin styles basic colors like black, red, green.
     BASIC_COLORS = %w{BLACK RED GREEN YELLOW BLUE MAGENTA CYAN WHITE GRAY GREY NONE}
 
     colors = BASIC_COLORS.dup
@@ -68,6 +76,8 @@ class HighLine
       colors << light_color
       const_set light_color + '_STYLE', const_get(color + '_STYLE').light
     end
+
+    # The builtin styles' colors like LIGHT_RED and BRIGHT_BLUE.
     COLORS = colors
 
     colors.each do |color|
@@ -78,11 +88,17 @@ class HighLine
 
     ON_NONE_STYLE.rgb = [255,255,255] # Override; white background
 
+    # BuiltinStyles class methods to be extended.
     module ClassMethods
-      RGB_COLOR = /^(ON_)?(RGB_)([A-F0-9]{6})(_STYLE)?$/
 
+      # Regexp to match against RGB style constant names.
+      RGB_COLOR_PATTERN = /^(ON_)?(RGB_)([A-F0-9]{6})(_STYLE)?$/
+
+      # const_missing callback for automatically respond to
+      # builtin constants (without explicitly defining them)
+      # @param name [Symbol] missing constant name
       def const_missing(name)
-        if name.to_s =~ RGB_COLOR
+        if name.to_s =~ RGB_COLOR_PATTERN
           on = $1
           suffix = $4
 

data/lib/highline/color_scheme.rb

@@ -8,19 +8,18 @@
 #
 # This is Free Software.  See LICENSE and COPYING for details
 
+
 class HighLine
   #
   # ColorScheme objects encapsulate a named set of colors to be used in the
-  # HighLine.colors() method call.  For example, by applying a ColorScheme that
+  # {HighLine.color} method call.  For example, by applying a ColorScheme that
   # has a <tt>:warning</tt> color then the following could be used:
   #
-  #   colors("This is a warning", :warning)
+  #   color("This is a warning", :warning)
   #
   # A ColorScheme contains named sets of HighLine color constants.
   #
-  # Example: Instantiating a color scheme, applying it to HighLine,
-  # and using it:
-  #
+  # @example Instantiating a color scheme, applying it to HighLine, and using it:
   #   ft = HighLine::ColorScheme.new do |cs|
   #          cs[:headline]        = [ :bold, :yellow, :on_black ]
   #          cs[:horizontal_line] = [ :bold, :white ]
@@ -49,6 +48,7 @@ class HighLine
     # converted to <tt>:symbols</tt> and values are converted to HighLine
     # constants.
     #
+    # @param h [Hash]
     def initialize( h = nil )
       @scheme = Hash.new
       load_from_hash(h) if h
@@ -56,6 +56,7 @@ class HighLine
     end
 
     # Load multiple colors from key/value pairs.
+    # @param h [Hash]
     def load_from_hash( h )
       h.each_pair do |color_tag, constants|
         self[color_tag] = constants
@@ -63,33 +64,42 @@ class HighLine
     end
 
     # Does this color scheme include the given tag name?
+    # @param color_tag [#to_sym]
+    # @return [Boolean]
     def include?( color_tag )
       @scheme.keys.include?(to_symbol(color_tag))
     end
 
     # Allow the scheme to be accessed like a Hash.
+    # @param color_tag [#to_sym]
+    # @return [Style]
     def []( color_tag )
       @scheme[to_symbol(color_tag)]
     end
 
     # Retrieve the original form of the scheme
+    # @param color_tag [#to_sym]
     def definition( color_tag )
       style = @scheme[to_symbol(color_tag)]
       style && style.list
     end
 
     # Retrieve the keys in the scheme
+    # @return [Array] of keys
     def keys
       @scheme.keys
     end
 
     # Allow the scheme to be set like a Hash.
+    # @param color_tag [#to_sym]
+    # @param constants [Array<Symbol>] Array of Style symbols
     def []=( color_tag, constants )
       @scheme[to_symbol(color_tag)] = HighLine::Style.new(:name=>color_tag.to_s.downcase.to_sym,
                                                           :list=>constants, :no_index=>true)
     end
 
     # Retrieve the color scheme hash (in original definition format)
+    # @return [Hash] scheme as Hash. It may be reused in a new ColorScheme.
     def to_hash
       @scheme.inject({}) { |hsh, pair| key, value = pair; hsh[key] = value.list; hsh }
     end

data/lib/highline/compatibility.rb

@@ -1,18 +1,23 @@
 # coding: utf-8
 
 unless STDIN.respond_to? :getbyte
+  # HighLine adds #getbyte alias to #getc when #getbyte is not available.
   class IO
+    # alias to #getc when #getbyte is not available
     alias_method :getbyte, :getc
   end
 
+  # HighLine adds #getbyte alias to #getc when #getbyte is not available.
   class StringIO
+    # alias to #getc when #getbyte is not available
     alias_method :getbyte, :getc
   end
 end
 
 unless "".respond_to? :each_line
-  # Not a perfect translation, but sufficient for our needs.
+  # HighLine adds #each_line alias to #each when each_line is not available.
   class String
+    # alias to #each when each_line is not available.
     alias_method :each_line, :each
   end
 end

data/lib/highline/custom_errors.rb

@@ -1,19 +1,56 @@
 class HighLine
+
+  # Internal HighLine errors.
   module CustomErrors
-    # Internal HighLine errors.
-    class QuestionError < StandardError
+    # An error that responds to :explanation_key
+    class ExplainableError < StandardError
+      # Explanation key as Symbol or nil. Used to
+      # select the proper error message to be displayed.
+      # @return [nil, Symbol] explanation key to get the
+      #   proper error message.
+      def explanation_key
+        nil
+      end
+    end
+
+    # Bare Question error
+    class QuestionError < ExplainableError
+      # (see ExplainableError#explanation_key)
+      def explanation_key
+        nil
+      end
     end
 
-    class NotValidQuestionError < QuestionError
+    # Invalid Question error
+    class NotValidQuestionError < ExplainableError
+      # (see ExplainableError#explanation_key)
+      def explanation_key
+        :not_valid
+      end
     end
 
-    class NotInRangeQuestionError < QuestionError
+    # Out of Range Question error
+    class NotInRangeQuestionError < ExplainableError
+      # (see ExplainableError#explanation_key)
+      def explanation_key
+        :not_in_range
+      end
     end
 
-    class NoConfirmationQuestionError < QuestionError
+    # Unconfirmed Question error
+    class NoConfirmationQuestionError < ExplainableError
+      # (see ExplainableError#explanation_key)
+      def explanation_key
+        nil
+      end
     end
 
-    class NoAutoCompleteMatch < StandardError
+    # Unavailable auto complete error
+    class NoAutoCompleteMatch < ExplainableError
+      # (see ExplainableError#explanation_key)
+      def explanation_key
+        :no_completion
+      end
     end
   end
 end

data/lib/highline/import.rb

@@ -14,11 +14,12 @@ $terminal = HighLine.new
 
 #
 # <tt>require "highline/import"</tt> adds shortcut methods to Kernel, making
-# agree(), ask(), choose() and say() globally available.  This is handy for
+# {HighLine#agree}, {HighLine#ask}, {HighLine#choose} and {HighLine#say}
+# globally available.  This is handy for
 # quick and dirty input and output.  These methods use the HighLine object in
-# the global variable <tt>$terminal</tt>, which is initialized to used
+# the global variable <tt>$terminal</tt>, which is initialized to use
 # <tt>$stdin</tt> and <tt>$stdout</tt> (you are free to change this).
-# Otherwise, these methods are identical to their HighLine counterparts, see that
+# Otherwise, these methods are identical to their {HighLine} counterparts, see that
 # class for detailed explanations.
 #
 module Kernel
@@ -26,6 +27,8 @@ module Kernel
   def_delegators :$terminal, :agree, :ask, :choose, :say
 end
 
+# When requiring 'highline/import' HighLine adds {#or_ask} to Object so
+#   it is globally available.
 class Object
   #
   # Tries this object as a _first_answer_ for a HighLine::Question.  See that
@@ -33,6 +36,10 @@ class Object
   #
   # *Warning*:  This Object will be passed to String() before set.
   #
+  # @param args [Array<#to_s>]
+  # @param details [lambda] block to be called with the question
+  #   instance as argument.
+  # @return [String] answer
   def or_ask( *args, &details )
     ask(*args) do |question|
       question.first_answer = String(self)

data/lib/highline/list.rb

@@ -1,18 +1,76 @@
 # coding: utf-8
 
 class HighLine
+
+  # List class with some convenience methods like {#col_down}.
   class List
-    attr_reader :items, :cols
-    attr_reader :transpose_mode, :col_down_mode
+
+    # Original given *items* argument.
+    # It's frozen at initialization time and
+    # all later transformations will happen on {#list}.
+    # @return [Array]
+    attr_reader :items
+
+    # Number of columns for each list row.
+    # @return [Integer]
+    attr_reader :cols
+
+    # Columns turn into rows in transpose mode.
+    # @return [Boolean]
+    #
+    # @example A two columns array like this:
+    #   [ [ "a", "b" ],
+    #     [ "c", "d" ],
+    #     [ "e", "f" ],
+    #     [ "g", "h" ],
+    #     [ "i", "j" ] ]
+    #
+    # @example When in transpose mode will be like this:
+    #   [ [ "a", "c", "e", "g", "i" ],
+    #     [ "b", "d", "f", "h", "j" ] ]
+    #
+    # @see #col_down_mode
+
+    attr_reader :transpose_mode
+
+
+    # Content are distributed first by column in col down mode.
+    # @return [Boolean]
+    #
+    # @example A two columns array like this:
+    #   [ [ "a", "b" ],
+    #     [ "c", "d" ],
+    #     [ "e", "f" ],
+    #     [ "g", "h" ],
+    #     [ "i", "j" ] ]
+    #
+    # @example In col down mode will be like this:
+    #   [ [ "a", "f"],
+    #     [ "b", "g"],
+    #     [ "c", "h"],
+    #     [ "d", "i"],
+    #     [ "e", "j"] ]
+    #
+    # @see #transpose_mode
+
+    attr_reader :col_down_mode
+
+    # @param items [#to_a] an array of items to compose the list.
+    # @param options [Hash] a hash of options to tailor the list.
+    # @option options [Boolean] :transpose (false) set {#transpose_mode}.
+    # @option options [Boolean] :col_down (false) set {#col_down_mode}.
+    # @option options [Integer] :cols (1) set {#cols}.
 
     def initialize(items, options = {})
-      @items          = items
+      @items          = items.to_a.dup.freeze
       @transpose_mode = options.fetch(:transpose) { false }
       @col_down_mode  = options.fetch(:col_down)  { false }
       @cols           = options.fetch(:cols)      { 1 }
       build
     end
 
+    # Transpose the (already sliced by rows) list, turning its rows into columns.
+    # @return [self]
     def transpose
       first_row = @list[0]
       other_rows = @list[1..-1]
@@ -20,47 +78,77 @@ class HighLine
       self
     end
 
+    # Slice the list by rows and transpose it.
+    # @return [self]
     def col_down
       slice_by_rows
       transpose
       self
     end
 
+    # Slice the list by rows. The row count is calculated
+    # indirectly based on the {#cols} param and the items count.
+    # @return [self]
     def slice_by_rows
       @list = items_sliced_by_rows
       self
     end
 
+    # Slice the list by cols based on the {#cols} param.
+    # @return [self]
     def slice_by_cols
       @list = items_sliced_by_cols
       self
     end
 
+    # Set the cols number.
+    # @return [self]
     def cols=(cols)
       @cols = cols
       build
     end
 
-    def to_a
-      list
-    end
-
+    # Returns an Array representation of the list
+    # in its current state.
+    # @return [Array] @list.dup
     def list
       @list.dup
     end
 
+    # (see #list)
+    def to_a
+      list
+    end
+
+    # Stringfies the list in its current state.
+    # It joins each individual _cell_ with the current
+    # {#row_join_string} between them.
+    # It joins each individual row with a
+    # newline character. So the returned String is
+    # suitable to be directly outputed
+    # to the screen, preserving row/columns divisions.
+    # @return [String]
     def to_s
       list.map { |row| stringfy(row) }.join
     end
 
+    # The String that will be used to join each
+    # cell of the list and stringfying it.
+    # @return [String] defaults to " " (space)
     def row_join_string
       @row_join_string ||= "  "
     end
 
+    # Set the {#row_join_string}.
+    # @see #row_join_string
     def row_join_string=(string)
       @row_join_string = string
     end
 
+    # Returns the row join string size.
+    # Useful for calculating the actual size of
+    # rendered list.
+    # @return [Integer]
     def row_join_str_size
       row_join_string.size
     end

data/lib/highline/list_renderer.rb

@@ -4,24 +4,34 @@ require 'highline/template_renderer'
 require 'highline/wrapper'
 require 'highline/list'
 
+#
+# This class is a utility for quickly and easily laying out lists
+# to be used by HighLine.
+#
 class HighLine::ListRenderer
-  attr_reader :items, :mode, :option, :highline
-
-  def initialize(items, mode = :rows, option = nil, highline)
-    @highline = highline
-    @mode     = mode
-    @option   = option
-    @items    = render_list_items(items)
-  end
-
-  #
-  # This method is a utility for quickly and easily laying out lists.  It can
-  # be accessed within ERb replacements of any text that will be sent to the
-  # user.
+  # Items list
+  # @return [Array]
+  attr_reader :items
+
+  # @return [Symbol] the current mode the List is being rendered
+  # @see #initialize for more details see mode parameter of #initialize
+  attr_reader :mode
+
+  # Changes the behaviour of some modes. Example, in :inline mode
+  # the option is treated as the 'end separator' (defaults to " or ")
+  # @return option parameter that changes the behaviour of some modes.
+  attr_reader :option
+
+  # @return [HighLine] context
+  attr_reader :highline
+
+  # The only required parameters are _items_ and _highline_.
+  # @param items [Array] the Array of items to list
+  # @param mode [Symbol] controls how that list is formed
+  # @param option has different effects, depending on the _mode_.
+  # @param highline [HighLine] a HighLine instance to direct the output to.
   #
-  # The only required parameter is _items_, which should be the Array of items
-  # to list.  A specified _mode_ controls how that list is formed and _option_
-  # has different effects, depending on the _mode_.  Recognized modes are:
+  # Recognized modes are:
   #
   # <tt>:columns_across</tt>::         _items_ will be placed in columns,
   #                                    flowing from left to right.  If given,
@@ -46,7 +56,16 @@ class HighLine::ListRenderer
   # 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
   # final field width.
-  #
+
+  def initialize(items, mode = :rows, option = nil, highline)
+    @highline = highline
+    @mode     = mode
+    @option   = option
+    @items    = render_list_items(items)
+  end
+
+  # Render the list using the appropriate mode and options.
+  # @return [String] rendered list as String
   def render
     return "" if items.empty?