highline 1.7.10 → 2.0.3

data/lib/highline/question/answer_converter.rb

@@ -0,0 +1,103 @@
+# coding: utf-8
+
+require "forwardable"
+
+class HighLine
+  class Question
+    # It provides all answer conversion flow.
+    class AnswerConverter
+      extend Forwardable
+
+      def_delegators :@question,
+                     :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
+
+        self.answer = convert_by_answer_type
+        check_range
+        answer
+      end
+
+      # @return [HighLine::String] answer converted to a HighLine::String
+      def to_string
+        HighLine::String(answer)
+      end
+
+      # That's a weird name for a method!
+      # But it's working ;-)
+      define_method "to_highline::string" do
+        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
+
+      private
+
+      def convert_by_answer_type
+        if answer_type.respond_to? :parse
+          answer_type.parse(answer)
+        elsif answer_type.is_a? Class
+          send("to_#{answer_type.name.downcase}")
+        else
+          send("to_#{answer_type.class.name.downcase}")
+        end
+      end
+    end
+  end
+end

data/lib/highline/question.rb

@@ -1,3 +1,6 @@
+# coding: utf-8
+
+#--
 # question.rb
 #
 #  Created by James Edward Gray II on 2005-04-26.
@@ -5,9 +8,11 @@
 #
 #  This is Free Software.  See LICENSE and COPYING for details.
 
+require "English"
 require "optparse"
 require "date"
 require "pathname"
+require "highline/question/answer_converter"
 
 class HighLine
   #
@@ -17,43 +22,49 @@ class HighLine
   # process is handled according to the users wishes.
   #
   class Question
-    # An internal HighLine error.  User code does not need to trap this.
-    class NoAutoCompleteMatch < StandardError
-      # do nothing, just creating a unique error type
+    include CustomErrors
+
+    #
+    # If _template_or_question_ is already a Question object just return it.
+    # If not, build it.
+    #
+    # @param template_or_question [String, Question] what to ask
+    # @param answer_type [Class] to what class to convert the answer
+    # @param details to be passed to Question.new
+    # @return [Question]
+    def self.build(template_or_question, answer_type = nil, &details)
+      if template_or_question.is_a? Question
+        template_or_question
+      else
+        Question.new(template_or_question, answer_type, &details)
+      end
     end
 
     #
-    # Create an instance of HighLine::Question.  Expects a _question_ to ask
+    # Create an instance of HighLine::Question.  Expects a _template_ to ask
     # (can be <tt>""</tt>) and an _answer_type_ to convert the answer to.
     # The _answer_type_ parameter must be a type recognized by
     # Question.convert(). If given, a block is yielded the new Question
     # object to allow custom initialization.
     #
-    def initialize( question, answer_type )
+    # @param template [String] any String
+    # @param answer_type [Class] the type the answer will be converted to it.
+    def initialize(template, answer_type)
       # initialize instance data
-      @question    = String(question).dup
+      @template    = String(template).dup
       @answer_type = answer_type
-      @completion = @answer_type
+      @completion  = @answer_type
 
-      @character    = nil
-      @limit        = nil
       @echo         = true
-      @readline     = false
       @whitespace   = :strip
       @case         = nil
-      @default      = nil
-      @validate     = nil
-      @above        = nil
-      @below        = nil
       @in           = nil
-      @confirm      = nil
-      @gather       = false
-      @verify_match = false
       @first_answer = nil
-      @directory    = Pathname.new(File.expand_path(File.dirname($0)))
       @glob         = "*"
-      @responses    = Hash.new
       @overwrite    = false
+      @user_responses = {}
+      @internal_responses = default_responses_hash
+      @directory = Pathname.new(File.expand_path(File.dirname($PROGRAM_NAME)))
 
       # allow block to override settings
       yield self if block_given?
@@ -63,7 +74,11 @@ class HighLine
     end
 
     # The ERb template of the question to be asked.
-    attr_accessor :question
+    attr_accessor :template
+
+    # The answer, set by HighLine#ask
+    attr_accessor :answer
+
     # The type that will be used to convert this answer.
     attr_accessor :answer_type
     # For Auto-completion
@@ -133,11 +148,15 @@ class HighLine
     attr_accessor :in
     #
     # Asks a yes or no confirmation question, to ensure a user knows what
-    # they have just agreed to.  If set to +true+ the question will be,
-    # "Are you sure?  "  Any other true value for this attribute is assumed
-    # to be the question to ask.  When +false+ or +nil+ (the default),
-    # answers are not confirmed.
-    #
+    # they have just agreed to.  The confirm attribute can be set to :
+    # +true+  :     In this case the question will be, "Are you sure?".
+    # Proc    :     The Proc is yielded the answer given. The Proc must
+    #               output a string which is then used as the confirm
+    #               question.
+    # String  :     The String must use ERB syntax. The String is
+    #               evaluated with access to question and answer and
+    #               is then used as the confirm question.
+    # When set to +false+ or +nil+ (the default), answers are not confirmed.
     attr_accessor :confirm
     #
     # When set, the user will be prompted for multiple answers which will
@@ -201,7 +220,9 @@ class HighLine
     # <tt>:not_valid</tt>::             The error message shown when
     #                                   validation checks fail.
     #
-    attr_reader :responses
+    def responses
+      @user_responses
+    end
     #
     # When set to +true+ the question is asked, but output does not progress to
     # the next line.  The Cursor is moved back to the beginning of the question
@@ -214,12 +235,11 @@ class HighLine
     # Returns the provided _answer_string_ or the default answer for this
     # Question if a default was set and the answer is empty.
     #
-    def answer_or_default( answer_string )
-      if answer_string.length == 0 and not @default.nil?
-        @default
-      else
-        answer_string
-      end
+    # @param answer_string [String]
+    # @return [String] the answer itself or a default message.
+    def answer_or_default(answer_string)
+      return default if answer_string.empty? && default
+      answer_string
     end
 
     #
@@ -227,36 +247,55 @@ class HighLine
     # responses based on the details of this Question object.
     # Also used by Menu#update_responses.
     #
-    def build_responses(message_source = answer_type, new_hash_wins = false)
+    # @return [Hash] responses Hash winner (new and old merge).
+    # @param message_source [Class] Array or String for example.
+    #   Same as {#answer_type}.
+
+    def build_responses(message_source = answer_type)
       append_default if [::String, Symbol].include? default.class
 
-      choice_error_str_func = lambda do
-        message_source.is_a?(Array) \
-            ? '[' +  message_source.map { |s| "#{s}" }.join(', ') + ']' \
-            : message_source.inspect
-      end
+      new_hash = build_responses_new_hash(message_source)
+      # Update our internal responses with the new hash
+      # generated from the message source
+      @internal_responses = @internal_responses.merge(new_hash)
+    end
+
+    def default_responses_hash
+      {
+        ask_on_error: "?  ",
+        mismatch: "Your entries didn't match."
+      }
+    end
+
+    # When updating the responses hash, it generates the new one.
+    # @param message_source (see #build_responses)
+    # @return [Hash] responses hash
+    def build_responses_new_hash(message_source)
+      { ambiguous_completion: "Ambiguous choice.  Please choose one of " +
+        choice_error_str(message_source) + ".",
+        invalid_type: "You must enter a valid #{message_source}.",
+        no_completion: "You must choose one of " +
+          choice_error_str(message_source) + ".",
+        not_in_range: "Your answer isn't within the expected range " \
+          "(#{expected_range}).",
+        not_valid: "Your answer isn't valid (must match " \
+          "#{validate.inspect})." }
+    end
 
-      old_hash = @responses
-
-      new_hash = { :ambiguous_completion =>
-                       "Ambiguous choice.  Please choose one of " +
-                       choice_error_str_func.call + '.',
-                     :ask_on_error         =>
-                       "?  ",
-                     :invalid_type         =>
-                       "You must enter a valid #{message_source}.",
-                     :no_completion        =>
-                       "You must choose one of " + choice_error_str_func.call + '.',
-                     :not_in_range         =>
-                       "Your answer isn't within the expected range " +
-                       "(#{expected_range}).",
-                     :mismatch             =>
-                       "Your entries didn't match.",
-                     :not_valid            =>
-                       "Your answer isn't valid (must match " +
-                       "#{@validate.inspect})." }
-
-      @responses = new_hash_wins ? old_hash.merge(new_hash) : new_hash.merge(old_hash)
+    # This is the actual responses hash that gets used in determining output
+    # Notice that we give @user_responses precedence over the responses
+    # generated internally via build_response
+    def final_responses
+      @internal_responses.merge(@user_responses)
+    end
+
+    def final_response(error)
+      response = final_responses[error]
+      if response.respond_to?(:call)
+        response.call(answer)
+      else
+        response
+      end
     end
 
     #
@@ -273,7 +312,10 @@ class HighLine
     #
     # An unrecognized choice (like <tt>:none</tt>) is treated as +nil+.
     #
-    def change_case( answer_string )
+    # @param answer_string [String]
+    # @return [String] upcased, downcased, capitalized
+    #   or unchanged answer String.
+    def change_case(answer_string)
       if [:up, :upcase].include?(@case)
         answer_string.upcase
       elsif [:down, :downcase].include?(@case)
@@ -314,46 +356,34 @@ class HighLine
     # This method throws ArgumentError, if the conversion cannot be
     # completed for any reason.
     #
-    def convert( answer_string )
-      if @answer_type.nil?
-        answer_string
-      elsif [::String, HighLine::String].include?(@answer_type)
-        HighLine::String(answer_string)
-      elsif [Float, Integer, String].include?(@answer_type)
-        Kernel.send(@answer_type.to_s.to_sym, answer_string)
-      elsif @answer_type == Symbol
-        answer_string.to_sym
-      elsif @answer_type == Regexp
-        Regexp.new(answer_string)
-      elsif @answer_type.is_a?(Array) or [File, Pathname].include?(@answer_type)
-        # cheating, using OptionParser's Completion module
-        choices = selection
-        choices.extend(OptionParser::Completion)
-        answer = choices.complete(answer_string)
-        if answer.nil?
-          raise NoAutoCompleteMatch
-        end
-        if @answer_type.is_a?(Array)
-          answer.last
-        elsif @answer_type == File
-          File.open(File.join(@directory.to_s, answer.last))
-        else
-          Pathname.new(File.join(@directory.to_s, answer.last))
-        end
-      elsif [Date, DateTime].include?(@answer_type) or @answer_type.is_a?(Class)
-        @answer_type.parse(answer_string)
-      elsif @answer_type.is_a?(Proc)
-        @answer_type[answer_string]
-      end
+    def convert
+      AnswerConverter.new(self).convert
+    end
+
+    # Run {#in_range?} and raise an error if not succesful
+    def check_range
+      raise NotInRangeQuestionError unless in_range?
+    end
+
+    # Try to auto complete answer_string
+    # @param answer_string [String]
+    # @return [String]
+    def choices_complete(answer_string)
+      # cheating, using OptionParser's Completion module
+      choices = selection
+      choices.extend(OptionParser::Completion)
+      answer = choices.complete(answer_string)
+      raise NoAutoCompleteMatch unless answer
+      answer
     end
 
     # Returns an English explanation of the current range settings.
-    def expected_range(  )
-      expected = [ ]
+    def expected_range
+      expected = []
 
-      expected << "above #{@above}" unless @above.nil?
-      expected << "below #{@below}" unless @below.nil?
-      expected << "included in #{@in.inspect}" unless @in.nil?
+      expected << "above #{above}" if above
+      expected << "below #{below}" if below
+      expected << "included in #{@in.inspect}" if @in
 
       case expected.size
       when 0 then ""
@@ -364,15 +394,15 @@ class HighLine
     end
 
     # Returns _first_answer_, which will be unset following this call.
-    def first_answer( )
+    def first_answer
       @first_answer
     ensure
       @first_answer = nil
     end
 
     # Returns true if _first_answer_ is set.
-    def first_answer?( )
-      not @first_answer.nil?
+    def first_answer?
+      true if @first_answer
     end
 
     #
@@ -381,10 +411,10 @@ class HighLine
     # _in_ attribute.  Otherwise, +false+ is returned.  Any +nil+ attributes
     # are not checked.
     #
-    def in_range?( answer_object )
-      (@above.nil? or answer_object > @above) and
-      (@below.nil? or answer_object < @below) and
-      (@in.nil? or @in.include?(answer_object))
+    def in_range?
+      (!above || answer > above) &&
+        (!below || answer < below) &&
+        (!@in || @in.include?(answer))
     end
 
     #
@@ -406,43 +436,55 @@ class HighLine
     #
     # This process is skipped for single character input.
     #
-    def remove_whitespace( answer_string )
-      if @whitespace.nil?
+    # @param answer_string [String]
+    # @return [String] answer string with whitespaces removed
+    def remove_whitespace(answer_string)
+      if !whitespace
         answer_string
-      elsif [:strip, :chomp].include?(@whitespace)
-        answer_string.send(@whitespace)
-      elsif @whitespace == :collapse
+      elsif [:strip, :chomp].include?(whitespace)
+        answer_string.send(whitespace)
+      elsif whitespace == :collapse
         answer_string.gsub(/\s+/, " ")
-      elsif [:strip_and_collapse, :chomp_and_collapse].include?(@whitespace)
-        result = answer_string.send(@whitespace.to_s[/^[a-z]+/])
+      elsif [:strip_and_collapse, :chomp_and_collapse].include?(whitespace)
+        result = answer_string.send(whitespace.to_s[/^[a-z]+/])
         result.gsub(/\s+/, " ")
-      elsif @whitespace == :remove
+      elsif whitespace == :remove
         answer_string.gsub(/\s+/, "")
       else
         answer_string
       end
     end
 
+    # Convert to String, remove whitespace and change case
+    # when necessary
+    # @param answer_string [String]
+    # @return [String] converted String
+    def format_answer(answer_string)
+      answer_string = String(answer_string)
+      answer_string = remove_whitespace(answer_string)
+      change_case(answer_string)
+    end
+
     #
     # Returns an Array of valid answers to this question.  These answers are
     # only known when _answer_type_ is set to an Array of choices, File, or
     # Pathname.  Any other time, this method will return an empty Array.
     #
-    def selection(  )
-      if @completion.is_a?(Array)
-        @completion
-      elsif [File, Pathname].include?(@completion)
-        Dir[File.join(@directory.to_s, @glob)].map do |file|
+    def selection
+      if completion.is_a?(Array)
+        completion
+      elsif [File, Pathname].include?(completion)
+        Dir[File.join(directory.to_s, glob)].map do |file|
           File.basename(file)
         end
       else
-        [ ]
+        []
       end
     end
 
-    # Stringifies the question to be asked.
+    # Stringifies the template to be asked.
     def to_s
-      @question
+      template
     end
 
     #
@@ -452,10 +494,110 @@ class HighLine
     # It's important to realize that an answer is validated after whitespace
     # and case handling.
     #
-    def valid_answer?( answer_string )
-      @validate.nil? or
-      (@validate.is_a?(Regexp) and answer_string =~ @validate) or
-      (@validate.is_a?(Proc)   and @validate[answer_string])
+    def valid_answer?
+      !validate ||
+        (validate.is_a?(Regexp) && answer =~ validate) ||
+        (validate.is_a?(Proc)   && validate[answer])
+    end
+
+    #
+    # Return a line or character of input, as requested for this question.
+    # Character input will be returned as a single character String,
+    # not an Integer.
+    #
+    # This question's _first_answer_ will be returned instead of input, if set.
+    #
+    # Raises EOFError if input is exhausted.
+    #
+    # @param highline [HighLine] context
+    # @return [String] a character or line
+
+    def get_response(highline)
+      return first_answer if first_answer?
+
+      case character
+      when :getc
+        highline.get_response_getc_mode(self)
+      when true
+        highline.get_response_character_mode(self)
+      else
+        highline.get_response_line_mode(self)
+      end
+    end
+
+    # Uses {#get_response} but returns a default answer
+    # using {#answer_or_default} in case no answers was
+    # returned.
+    #
+    # @param highline [HighLine] context
+    # @return [String]
+
+    def get_response_or_default(highline)
+      self.answer = answer_or_default(get_response(highline))
+    end
+
+    # Returns the String to be shown when asking for an answer confirmation.
+    # @param highline [HighLine] context
+    # @return [String] default "Are you sure?" if {#confirm} is +true+
+    # @return [String] {#confirm} rendered as a template if it is a String
+    def confirm_question(highline)
+      if confirm == true
+        "Are you sure?  "
+      elsif confirm.is_a?(Proc)
+        confirm.call(answer)
+      else
+        # evaluate ERb under initial scope, so it will have
+        # access to question and answer
+        template = if ERB.instance_method(:initialize).parameters.assoc(:key) # Ruby 2.6+
+          ERB.new(confirm, trim_mode: "%")
+        else
+          ERB.new(confirm, nil, "%")
+        end
+        template_renderer = TemplateRenderer.new(template, self, highline)
+        template_renderer.render
+      end
+    end
+
+    # Provides the String to be asked when at an error situation.
+    # It may be just the question itself (repeat on error).
+    # @return [self] if :ask_on_error on responses Hash is set to :question
+    # @return [String] if :ask_on_error on responses Hash is set to
+    #   something else
+    def ask_on_error_msg
+      if final_responses[:ask_on_error] == :question
+        self
+      elsif final_responses[:ask_on_error]
+        final_responses[:ask_on_error]
+      end
+    end
+
+    # readline() needs to handle its own output, but readline only supports
+    # full line reading.  Therefore if question.echo is anything but true,
+    # the prompt will not be issued. And we have to account for that now.
+    # Also, JRuby-1.7's ConsoleReader.readLine() needs to be passed the prompt
+    # to handle line editing properly.
+    # @param highline [HighLine] context
+    # @return [void]
+    def show_question(highline)
+      highline.say(self)
+    end
+
+    # Returns an echo string that is adequate for this Question settings.
+    # @param response [String]
+    # @return [String] the response itself if {#echo} is +true+.
+    # @return [String] echo character if {#echo} is truethy. Mainly a String.
+    # @return [String] empty string if {#echo} is falsy.
+    def get_echo_for_response(response)
+      # actually true, not only truethy value
+      if echo == true
+        response
+      # any truethy value, probably a String
+      elsif echo
+        echo
+      # any falsy value, false or nil
+      else
+        ""
+      end
     end
 
     private
@@ -465,15 +607,23 @@ class HighLine
     # Trailing whitespace is preserved so the function of HighLine.say() is
     # not affected.
     #
-    def append_default(  )
-      if @question =~ /([\t ]+)\Z/
-        @question << "|#{@default}|#{$1}"
-      elsif @question == ""
-        @question << "|#{@default}|  "
-      elsif @question[-1, 1] == "\n"
-        @question[-2, 0] =  "  |#{@default}|"
+    def append_default
+      if template =~ /([\t ]+)\Z/
+        template << "|#{default}|#{Regexp.last_match(1)}"
+      elsif template == ""
+        template << "|#{default}|  "
+      elsif template[-1, 1] == "\n"
+        template[-2, 0] = "  |#{default}|"
+      else
+        template << "  |#{default}|"
+      end
+    end
+
+    def choice_error_str(message_source)
+      if message_source.is_a? Array
+        "[" + message_source.join(", ") + "]"
       else
-        @question << "  |#{@default}|"
+        message_source.inspect
       end
     end
   end