highline 1.7.10 → 2.0.3

data/lib/highline/color_scheme.rb

@@ -1,3 +1,6 @@
+# coding: utf-8
+
+#--
 # color_scheme.rb
 #
 # Created by Jeremy Hinegardner on 2007-01-24
@@ -8,16 +11,15 @@
 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 ]
@@ -46,63 +48,78 @@ class HighLine
     # converted to <tt>:symbols</tt> and values are converted to HighLine
     # constants.
     #
-    def initialize( h = nil )
-      @scheme = Hash.new
-      load_from_hash(h) unless h.nil?
+    # @param h [Hash]
+    def initialize(h = nil)
+      @scheme = {}
+      load_from_hash(h) if h
       yield self if block_given?
     end
 
     # Load multiple colors from key/value pairs.
-    def load_from_hash( h )
+    # @param h [Hash]
+    def load_from_hash(h)
       h.each_pair do |color_tag, constants|
         self[color_tag] = constants
       end
     end
 
     # Does this color scheme include the given tag name?
-    def include?( color_tag )
+    # @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.
-    def []( color_tag )
+    # @param color_tag [#to_sym]
+    # @return [Style]
+    def [](color_tag)
       @scheme[to_symbol(color_tag)]
     end
 
     # Retrieve the original form of the scheme
-    def definition( color_tag )
+    # @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.
-    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)
+    # @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 }
+      @scheme.each_with_object({}) do |pair, hsh|
+        key, value = pair
+        hsh[key] = value.list
+      end
     end
 
-
     private
 
     # Return a normalized representation of a color name.
-    def to_symbol( t )
+    def to_symbol(t)
       t.to_s.downcase
     end
 
     # Return a normalized representation of a color setting.
-    def to_constant( v )
+    def to_constant(v)
       v = v.to_s if v.is_a?(Symbol)
-      if v.is_a?(::String) then
+      if v.is_a?(::String)
         HighLine.const_get(v.upcase)
       else
         v
@@ -112,23 +129,23 @@ class HighLine
 
   # A sample ColorScheme.
   class SampleColorScheme < ColorScheme
+    SAMPLE_SCHEME = {
+      critical: [:yellow, :on_red],
+      error: [:bold, :red],
+      warning: [:bold, :yellow],
+      notice: [:bold, :magenta],
+      info: [:bold, :cyan],
+      debug: [:bold, :green],
+      row_even: [:cyan],
+      row_odd: [:magenta]
+    }.freeze
     #
     # Builds the sample scheme with settings for <tt>:critical</tt>,
     # <tt>:error</tt>, <tt>:warning</tt>, <tt>:notice</tt>, <tt>:info</tt>,
     # <tt>:debug</tt>, <tt>:row_even</tt>, and <tt>:row_odd</tt> colors.
     #
-    def initialize( h = nil )
-      scheme = {
-        :critical => [ :yellow, :on_red  ],
-        :error    => [ :bold,   :red     ],
-        :warning  => [ :bold,   :yellow  ],
-        :notice   => [ :bold,   :magenta ],
-        :info     => [ :bold,   :cyan    ],
-        :debug    => [ :bold,   :green   ],
-        :row_even => [ :cyan    ],
-        :row_odd  => [ :magenta ]
-      }
-      super(scheme)
+    def initialize(_h = nil)
+      super(SAMPLE_SCHEME)
     end
   end
 end

data/lib/highline/compatibility.rb

@@ -1,16 +1,23 @@
+# coding: utf-8
+
 unless STDIN.respond_to? :getbyte
+  # HighLine adds #getbyte alias to #getc when #getbyte is not available.
   class IO
-    alias_method :getbyte, :getc
+    # alias to #getc when #getbyte is not available
+    alias getbyte getc
   end
 
+  # HighLine adds #getbyte alias to #getc when #getbyte is not available.
   class StringIO
-    alias_method :getbyte, :getc
+    # alias to #getc when #getbyte is not available
+    alias 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_method :each_line, :each
+    # alias to #each when each_line is not available.
+    alias each_line each
   end
 end

data/lib/highline/custom_errors.rb

@@ -0,0 +1,57 @@
+# encoding: utf-8
+
+class HighLine
+  # Internal HighLine errors.
+  module CustomErrors
+    # 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
+
+    # Invalid Question error
+    class NotValidQuestionError < ExplainableError
+      # (see ExplainableError#explanation_key)
+      def explanation_key
+        :not_valid
+      end
+    end
+
+    # Out of Range Question error
+    class NotInRangeQuestionError < ExplainableError
+      # (see ExplainableError#explanation_key)
+      def explanation_key
+        :not_in_range
+      end
+    end
+
+    # Unconfirmed Question error
+    class NoConfirmationQuestionError < ExplainableError
+      # (see ExplainableError#explanation_key)
+      def explanation_key
+        nil
+      end
+    end
+
+    # 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

@@ -1,3 +1,5 @@
+# coding: utf-8
+
 # import.rb
 #
 #  Created by James Edward Gray II on 2005-04-26.
@@ -8,22 +10,23 @@
 require "highline"
 require "forwardable"
 
-$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
-# quick and dirty input and output.  These methods use the HighLine object in
-# the global variable <tt>$terminal</tt>, which is initialized to used
-# <tt>$stdin</tt> and <tt>$stdout</tt> (you are free to change this).
-# Otherwise, these methods are identical to their HighLine counterparts, see that
-# class for detailed explanations.
+# {HighLine#agree}, {HighLine#ask}, {HighLine#choose} and {HighLine#say}
+# globally available.  This is handy for
+# quick and dirty input and output.  These methods use HighLine.default_instance
+# 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 class for detailed explanations.
 #
 module Kernel
   extend Forwardable
-  def_delegators :$terminal, :agree, :ask, :choose, :say
+  def_instance_delegators :HighLine, :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
@@ -31,11 +34,15 @@ class Object
   #
   # *Warning*:  This Object will be passed to String() before set.
   #
-  def or_ask( *args, &details )
+  # @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) unless nil?
+      question.first_answer = String(self)
 
-      details.call(question) unless details.nil?
+      yield(question) if details
     end
   end
 end

data/lib/highline/io_console_compatible.rb

@@ -0,0 +1,37 @@
+# coding: utf-8
+
+require "stringio"
+require "tempfile"
+
+#
+# On tests, we try to simulate input output with
+# StringIO, Tempfile and File objects.
+#
+# For this to be accomplished, we have to do some
+# tweaking so that they respond adequately to the
+# called methods during tests.
+#
+
+module IOConsoleCompatible
+  def getch
+    getc
+  end
+
+  attr_accessor :echo
+
+  def winsize
+    [24, 80]
+  end
+end
+
+class Tempfile
+  include IOConsoleCompatible
+end
+
+class File
+  include IOConsoleCompatible
+end
+
+class StringIO
+  include IOConsoleCompatible
+end

data/lib/highline/list.rb

@@ -0,0 +1,177 @@
+# coding: utf-8
+
+class HighLine
+  # List class with some convenience methods like {#col_down}.
+  class List
+    # 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.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]
+      @list = first_row.zip(*other_rows)
+      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
+
+    # 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
+    attr_writer :row_join_string
+
+    # 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
+
+    private
+
+    def build
+      slice_by_cols
+      transpose if transpose_mode
+      col_down  if col_down_mode
+      self
+    end
+
+    def items_sliced_by_cols
+      items.each_slice(cols).to_a
+    end
+
+    def items_sliced_by_rows
+      items.each_slice(row_count).to_a
+    end
+
+    def row_count
+      (items.count / cols.to_f).ceil
+    end
+
+    def stringfy(row)
+      row.compact.join(row_join_string) + "\n"
+    end
+  end
+end