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

data/lib/highline/question/answer_converter.rb

@@ -4,6 +4,7 @@ require 'forwardable'
 
 class HighLine
   class Question
+    # It provides all answer conversion flow.
     class AnswerConverter
       extend Forwardable
 
@@ -11,10 +12,19 @@ class HighLine
                      :answer, :answer=, :check_range,
                      :directory, :answer_type, :choices_complete
 
+      # It should be initialized with a Question object.
+      # The class will get the answer from {Question#answer}
+      # and then convert it to the proper {Question#answer_type}.
+      # It is mainly used by {Question#convert}
+      #
+      # @param question [Question]
       def initialize(question)
         @question = question
       end
 
+      # Based on the given Question object's settings,
+      # it makes the conversion and returns the answer.
+      # @return [Object] the converted answer.
       def convert
         return unless answer_type
 
@@ -23,6 +33,7 @@ class HighLine
         answer
       end
 
+      # @return [HighLine::String] answer converted to a HighLine::String
       def to_string
         HighLine::String(answer)
       end
@@ -33,37 +44,45 @@ class HighLine
         HighLine::String(answer)
       end
 
+      # @return [Integer] answer converted to an Integer
       def to_integer
         Kernel.send(:Integer, answer)
       end
 
+      # @return [Float] answer converted to a Float
       def to_float
         Kernel.send(:Float, answer)
       end
 
+      # @return [Symbol] answer converted to an Symbol
       def to_symbol
         answer.to_sym
       end
 
+      # @return [Regexp] answer converted to a Regexp
       def to_regexp
         Regexp.new(answer)
       end
 
+      # @return [File] answer converted to a File
       def to_file
         self.answer = choices_complete(answer)
         File.open(File.join(directory.to_s, answer.last))
       end
 
+      # @return [Pathname] answer converted to an Pathname
       def to_pathname
         self.answer = choices_complete(answer)
         Pathname.new(File.join(directory.to_s, answer.last))
       end
 
+      # @return [Array] answer converted to an Array
       def to_array
         self.answer = choices_complete(answer)
         answer.last
       end
 
+      # @return [Proc] answer converted to an Proc
       def to_proc
         answer_type.call(answer)
       end

data/lib/highline/question_asker.rb

@@ -1,9 +1,17 @@
 class HighLine
+  # Deals with the task of "asking" a question
   class QuestionAsker
+    # @return [Question] question to be asked
     attr_reader :question
 
     include CustomErrors
 
+    # To do its work QuestionAsker needs a Question
+    # to be asked and a HighLine context where to
+    # direct output.
+    #
+    # @param question [Question] question to be asked
+    # @param highline [HighLine] context
     def initialize(question, highline)
       @question = question
       @highline = highline
@@ -12,6 +20,7 @@ class HighLine
     #
     # Gets just one answer, as opposed to #gather_answers
     #
+    # @return [String] answer
     def ask_once
       question.show_question(@highline)
 
@@ -25,19 +34,8 @@ class HighLine
           raise NoConfirmationQuestionError unless @highline.send(:confirm, question)
         end
 
-      rescue NoConfirmationQuestionError
-        explain_error(nil)
-        retry
-
-      rescue NotInRangeQuestionError
-        explain_error(:not_in_range)
-        retry
-
-      rescue NotValidQuestionError
-        explain_error(:not_valid)
-        retry
-
-      rescue QuestionError
+      rescue ExplainableError => e
+        explain_error(e.explanation_key)
         retry
 
       rescue ArgumentError => error
@@ -54,11 +52,8 @@ class HighLine
         else
           raise
         end
-
-      rescue NoAutoCompleteMatch
-        explain_error(:no_completion)
-        retry
       end
+
       question.answer
     end
 
@@ -68,6 +63,7 @@ class HighLine
     # Collects an Array/Hash full of answers as described in
     # HighLine::Question.gather().
     #
+    # @return [Array, Hash] answers
     def gather_answers
       original_question_template = question.template
       verify_match = question.verify_match
@@ -87,12 +83,17 @@ class HighLine
       question.verify_match ? @highline.send(:last_answer, answers) : answers
     end
 
+    # Gather multiple integer values based on {Question#gather} count
+    # @return [Array] answers
     def gather_integer
       gather_with_array do |answers|
         (question.gather-1).times { answers << ask_once }
       end
     end
 
+    # Gather multiple values until any of them matches the
+    # {Question#gather} Regexp.
+    # @return [Array] answers
     def gather_regexp
       gather_with_array do |answers|
         answers << ask_once until answer_matches_regex(answers.last)
@@ -100,6 +101,9 @@ class HighLine
       end
     end
 
+    # Gather multiple values and store them on a Hash
+    # with keys provided by the Hash on {Question#gather}
+    # @return [Hash]
     def gather_hash
       answers = {}
 

data/lib/highline/simulate.rb

@@ -10,12 +10,15 @@
 #
 # adapted from https://gist.github.com/194554
 
+
 class HighLine
 
   # Simulates Highline input for use in tests.
   class Simulate
 
     # Creates a simulator with an array of Strings as a script
+    # @param strings [Array<String>] preloaded string to be used
+    #   as input buffer when simulating.
     def initialize(strings)
       @strings = strings
     end
@@ -40,7 +43,13 @@ class HighLine
       false
     end
 
-    # A wrapper method that temporarily replaces the Highline instance in $terminal with an instance of this object for the duration of the block
+    # A wrapper method that temporarily replaces the Highline
+    # instance in $terminal with an instance of this object
+    # for the duration of the block
+    #
+    # @param strings [String] preloaded string buffer that
+    #   will feed the input operations when simulating.
+
     def self.with(*strings)
       @input = $terminal.instance_variable_get :@input
       $terminal.instance_variable_set :@input, new(strings)

data/lib/highline/statement.rb

@@ -4,55 +4,79 @@ require 'highline/wrapper'
 require 'highline/paginator'
 require 'highline/template_renderer'
 
-class HighLine::Statement
-  attr_reader :source, :highline
-  attr_reader :template_string
-
-  def initialize(source, highline)
-    @highline = highline
-    @source   = source
-    @template_string = stringfy(source)
-  end
+class HighLine
+  # This class handles proper formatting based
+  # on a HighLine context, applying wrapping,
+  # pagination, indentation and color rendering
+  # when necessary. It's used by {HighLine#render_statement}
+  # @see HighLine#render_statement
+  class Statement
+    # The source object to be stringfied and formatted.
+    attr_reader :source
 
-  def statement
-    @statement ||= format_statement
-  end
+    # The HighLine context
+    # @return [HighLine]
+    attr_reader :highline
 
-  def to_s
-    statement
-  end
+    # The stringfied source object
+    # @return [String]
+    attr_reader :template_string
 
-  private
+    # It needs the input String and the HighLine context
+    # @param source [#to_s]
+    # @param highline [HighLine] context
+    def initialize(source, highline)
+      @highline = highline
+      @source   = source
+      @template_string = stringfy(source)
+    end
 
-  def stringfy(template_string)
-    String(template_string || "").dup
-  end
+    # Returns the formated statement.
+    # Applies wrapping, pagination, indentation and color rendering
+    # based on HighLine instance settings.
+    # @return [String] formated statement
+    def statement
+      @statement ||= format_statement
+    end
 
-  def format_statement
-    return template_string unless template_string.length > 0
+    # (see #statement)
+    # Delegates to {#statement}
+    def to_s
+      statement
+    end
 
-    statement = render_template
+    private
 
-    statement = HighLine::Wrapper.wrap(statement, highline.wrap_at)
-    statement = HighLine::Paginator.new(highline).page_print(statement)
+    def stringfy(template_string)
+      String(template_string || "").dup
+    end
 
-    statement = statement.gsub(/\n(?!$)/,"\n#{highline.indentation}") if highline.multi_indent
-    statement
-  end
+    def format_statement
+      return template_string unless template_string.length > 0
 
-  def render_template
-    # Assigning to a local var so it may be
-    # used inside instance eval block
+      statement = render_template
 
-    template_renderer = TemplateRenderer.new(template, source, highline)
-    template_renderer.render
-  end
+      statement = HighLine::Wrapper.wrap(statement, highline.wrap_at)
+      statement = HighLine::Paginator.new(highline).page_print(statement)
 
-  def template
-    @template ||= ERB.new(template_string, nil, "%")
-  end
+      statement = statement.gsub(/\n(?!$)/,"\n#{highline.indentation}") if highline.multi_indent
+      statement
+    end
+
+    def render_template
+      # Assigning to a local var so it may be
+      # used inside instance eval block
+
+      template_renderer = TemplateRenderer.new(template, source, highline)
+      template_renderer.render
+    end
+
+    def template
+      @template ||= ERB.new(template_string, nil, "%")
+    end
 
-  def self.const_missing(constant)
-    HighLine.const_get(constant)
+    def self.const_missing(constant)
+      HighLine.const_get(constant)
+    end
   end
 end

data/lib/highline/string.rb

@@ -2,32 +2,33 @@
 
 require "highline/string_extensions"
 
-#
-# HighLine::String is a subclass of String with convenience methods added for colorization.
-#
-# Available convenience methods include:
-#   * 'color' method         e.g.  highline_string.color(:bright_blue, :underline)
-#   * colors                 e.g.  highline_string.magenta
-#   * RGB colors             e.g.  highline_string.rgb_ff6000
-#                             or   highline_string.rgb(255,96,0)
-#   * background colors      e.g.  highline_string.on_magenta
-#   * RGB background colors  e.g.  highline_string.on_rgb_ff6000
-#                             or   highline_string.on_rgb(255,96,0)
-#   * styles                 e.g.  highline_string.underline
-#
-# Additionally, convenience methods can be chained, for instance the following are equivalent:
-#   highline_string.bright_blue.blink.underline
-#   highline_string.color(:bright_blue, :blink, :underline)
-#   HighLine.color(highline_string, :bright_blue, :blink, :underline)
-#
-# For those less squeamish about possible conflicts, the same convenience methods can be
-# added to the built-in String class, as follows:
-#
-#  require 'highline'
-#  Highline.colorize_strings
-#
-
 class HighLine
+
+  #
+  # HighLine::String is a subclass of String with convenience methods added for colorization.
+  #
+  # Available convenience methods include:
+  #   * 'color' method         e.g.  highline_string.color(:bright_blue, :underline)
+  #   * colors                 e.g.  highline_string.magenta
+  #   * RGB colors             e.g.  highline_string.rgb_ff6000
+  #                             or   highline_string.rgb(255,96,0)
+  #   * background colors      e.g.  highline_string.on_magenta
+  #   * RGB background colors  e.g.  highline_string.on_rgb_ff6000
+  #                             or   highline_string.on_rgb(255,96,0)
+  #   * styles                 e.g.  highline_string.underline
+  #
+  # Additionally, convenience methods can be chained, for instance the following are equivalent:
+  #   highline_string.bright_blue.blink.underline
+  #   highline_string.color(:bright_blue, :blink, :underline)
+  #   HighLine.color(highline_string, :bright_blue, :blink, :underline)
+  #
+  # For those less squeamish about possible conflicts, the same convenience methods can be
+  # added to the built-in String class, as follows:
+  #
+  #  require 'highline'
+  #  Highline.colorize_strings
+  #
+
   class String < ::String
     include StringExtensions
   end

data/lib/highline/string_extensions.rb

@@ -1,40 +1,30 @@
 # coding: utf-8
 
 class HighLine
+  # Returns a HighLine::String from any given String.
+  # @param s [String]
+  # @return [HighLine::String] from the given string.
   def self.String(s)
     HighLine::String.new(s)
   end
 
-  # HighLine extensions for String class
-  # Included by HighLine::String
+  # HighLine extensions for String class.
+  # Included by HighLine::String.
   module StringExtensions
+    # Included hook. Actions to take when being included.
+    # @param base [Class, Module] base class
     def self.included(base)
-      HighLine::COLORS.each do |color|
-        color = color.downcase
-        base.class_eval <<-END
-          undef :#{color} if method_defined? :#{color}
-          def #{color}
-            color(:#{color})
-          end
-        END
-
-        base.class_eval <<-END
-          undef :on_#{color} if method_defined? :on_#{color}
-          def on_#{color}
-            on(:#{color})
-          end
-        END
-        HighLine::STYLES.each do |style|
-          style = style.downcase
-          base.class_eval <<-END
-            undef :#{style} if method_defined? :#{style}
-            def #{style}
-              color(:#{style})
-            end
-          END
-        end
-      end
+      define_builtin_style_methods(base)
+      define_style_support_methods(base)
+    end
 
+    # At include time, it defines all basic style
+    # support method like #color, #on, #uncolor,
+    # #rgb, #on_rgb and the #method_missing callback
+    # @return [void]
+    # @param base [Class, Module] the base class/module
+    #
+    def self.define_style_support_methods(base)
       base.class_eval do
         undef :color if method_defined? :color
         undef :foreground if method_defined? :foreground
@@ -55,19 +45,17 @@ class HighLine
 
         undef :rgb if method_defined? :rgb
         def rgb(*colors)
-          color_code = colors.map{|color| color.is_a?(Numeric) ? '%02x'%color : color.to_s}.join
-          raise "Bad RGB color #{colors.inspect}" unless color_code =~ /^[a-fA-F0-9]{6}/
+          color_code = setup_color_code(*colors)
           color("rgb_#{color_code}".to_sym)
         end
 
         undef :on_rgb if method_defined? :on_rgb
         def on_rgb(*colors)
-          color_code = colors.map{|color| color.is_a?(Numeric) ? '%02x'%color : color.to_s}.join
-          raise "Bad RGB color #{colors.inspect}" unless color_code =~ /^[a-fA-F0-9]{6}/
+          color_code = setup_color_code(*colors)
           color("on_rgb_#{color_code}".to_sym)
         end
 
-        # TODO Chain existing method_missing
+        # @todo Chain existing method_missing?
         undef :method_missing if method_defined? :method_missing
         def method_missing(method, *args, &blk)
           if method.to_s =~ /^(on_)?rgb_([0-9a-fA-F]{6})$/
@@ -76,10 +64,50 @@ class HighLine
             raise NoMethodError, "undefined method `#{method}' for #<#{self.class}:#{'%#x'%self.object_id}>"
           end
         end
+
+        private
+
+        def setup_color_code(*colors)
+          color_code = colors.map{|color| color.is_a?(Numeric) ? '%02x'%color : color.to_s}.join
+          raise "Bad RGB color #{colors.inspect}" unless color_code =~ /^[a-fA-F0-9]{6}/
+          color_code
+        end
+      end
+    end
+
+    # At include time, it defines all basic builtin styles.
+    # @param base [Class, Module] base Class/Module
+    def self.define_builtin_style_methods(base)
+      HighLine::COLORS.each do |color|
+        color = color.downcase
+        base.class_eval <<-END
+          undef :#{color} if method_defined? :#{color}
+          def #{color}
+            color(:#{color})
+          end
+        END
+
+        base.class_eval <<-END
+          undef :on_#{color} if method_defined? :on_#{color}
+          def on_#{color}
+            on(:#{color})
+          end
+        END
+
+        HighLine::STYLES.each do |style|
+          style = style.downcase
+          base.class_eval <<-END
+            undef :#{style} if method_defined? :#{style}
+            def #{style}
+              color(:#{style})
+            end
+          END
+        end
       end
     end
   end
 
+  # Adds color support to the base String class
   def self.colorize_strings
     ::String.send(:include, StringExtensions)
   end