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

data/lib/highline/menu.rb

@@ -12,18 +12,26 @@ require "highline/question"
 
 class HighLine
   #
-  # Menu objects encapsulate all the details of a call to HighLine.choose().
-  # Using the accessors and Menu.choice() and Menu.choices(), the block passed
-  # to HighLine.choose() can detail all aspects of menu display and control.
+  # Menu objects encapsulate all the details of a call to {HighLine#choose HighLine#choose}.
+  # Using the accessors and {Menu#choice} and {Menu#choices}, the block passed
+  # to {HighLine#choose} can detail all aspects of menu display and control.
   #
   class Menu < Question
     #
     # Create an instance of HighLine::Menu.  All customization is done
-    # through the passed block, which should call accessors and choice() and
-    # choices() as needed to define the Menu.  Note that Menus are also
-    # Questions, so all that functionality is available to the block as
-    # well.
-    #
+    # through the passed block, which should call accessors, {#choice} and
+    # {#choices} as needed to define the Menu.  Note that Menus are also
+    # {HighLine::Question Questions}, so all that functionality is available
+    # to the block as well.
+    #
+    # @example Implicit menu creation through HighLine#choose
+    #   cli = HighLine.new
+    #   answer = cli.choose do |menu|
+    #     menu.prompt = "Please choose your favorite programming language?  "
+    #     menu.choice(:ruby) { say("Good choice!") }
+    #     menu.choices(:python, :perl) { say("Not from around here, are you?") }
+    #   end
+
     def initialize(  )
       #
       # Initialize Question objects with ignored values, we'll
@@ -136,6 +144,23 @@ class HighLine
     # the current HighLine context before the action code is called and can
     # thus be used for adding output and the like.
     #
+    # @param name [#to_s] menu item title/header/name to be displayed.
+    # @param action [Proc] callback action to be run when the item is selected.
+    # @param help [String] help/hint string to be displayed.
+    # @return [void]
+    # @example (see HighLine::Menu#initialize)
+    # @example Use of help string on menu items
+    #   cli = HighLine.new
+    #   cli.choose do |menu|
+    #     menu.shell = true
+    #
+    #     menu.choice(:load, "Load a file.")
+    #     menu.choice(:save, "Save data in file.")
+    #     menu.choice(:quit, "Exit program.")
+    #
+    #     menu.help("rules", "The rules of this system are as follows...")
+    #   end
+
     def choice( name, help = nil, &action )
       @items << [name, action]
 
@@ -144,16 +169,25 @@ class HighLine
     end
 
     #
-    # A shortcut for multiple calls to the sister method choice().  <b>Be
+    # A shortcut for multiple calls to the sister method {#choice}.  <b>Be
     # warned:</b>  An _action_ set here will apply to *all* provided
     # _names_.  This is considered to be a feature, so you can easily
     # hand-off interface processing to a different chunk of code.
-    #
+    # @param names [Array<#to_s>] menu item titles/headers/names to be displayed.
+    # @param action (see #choice)
+    # @return [void]
+    # @example (see HighLine::Menu#initialize)
     def choices( *names, &action )
       names.each { |n| choice(n, &action) }
     end
 
-    # Identical to choice(), but the item will not be listed for the user.
+    # Identical to {#choice}, but the item will not be listed for the user.
+    # @see #choice
+    # @param name (see #choice)
+    # @param help (see #choice)
+    # @param action (see #choice)
+    # @return (see #choice)
+
     def hidden( name, help = nil, &action )
       @hidden_items << [name, action]
 
@@ -212,8 +246,12 @@ class HighLine
 
     #
     # Used to set help for arbitrary topics.  Use the topic <tt>"help"</tt>
-    # to override the default message.
+    # to override the default message. Mainly for internal use.
     #
+    # @param topic [String] the menu item header/title/name to be associated with
+    #   a help message.
+    # @param help [String] the help message to be associated with the menu
+    #   item/title/name.
     def help( topic, help )
       @help[topic] = help
     end
@@ -290,19 +328,22 @@ class HighLine
     #
     # This method processes the auto-completed user selection, based on the
     # rules for this Menu object.  If an action was provided for the
-    # selection, it will be executed as described in Menu.choice().
+    # selection, it will be executed as described in {#choice}.
     #
+    # @param highline_context [HighLine] a HighLine instance to be used as context.
+    # @param selection [String, Integer] index or title of the selected menu item.
+    # @param details additional parameter to be passed when in shell mode.
+    # @return [nil, Object] if @nil_on_handled is set it returns +nil+,
+    #   else it returns the action return value.
     def select( highline_context, selection, details = nil )
       # add in any hidden menu commands
       @items.concat(@hidden_items)
 
       # Find the selected action.
-      name, action = if selection =~ /^\d+$/
-        @items[selection.to_i - 1]
+      name, action = if selection =~ /^\d+$/ # is a number?
+        get_item_by_number(selection)
       else
-        l_index = "`"
-        index = @items.map { "#{l_index.succ!}" }.index(selection)
-        @items.find { |c| c.first == selection } or @items[index]
+        get_item_by_letter(selection)
       end
 
       # Run or return it.
@@ -322,6 +363,20 @@ class HighLine
       @items.slice!(@items.size - @hidden_items.size, @hidden_items.size)
     end
 
+    # Returns the menu item referenced by its index
+    # @param selection [Integer] menu item's index.
+    def get_item_by_number(selection)
+      @items[selection.to_i - 1]
+    end
+
+    # Returns the menu item referenced by its title/header/name.
+    # @param selection [String] menu's title/header/name
+    def get_item_by_letter(selection)
+      l_index = "`" # character before the letter "a"
+      index = @items.map { "#{l_index.succ!}" }.index(selection)
+      @items.find { |c| c.first == selection } or @items[index]
+    end
+
     #
     # Allows Menu objects to pass as Arrays, for use with HighLine.list().
     # This method returns all menu items to be displayed, complete with

data/lib/highline/paginator.rb

@@ -1,9 +1,17 @@
 # coding: utf-8
 
 class HighLine
+  # Take the task of paginating some piece of text given a HighLine context
   class Paginator
+
+    # @return [HighLine] HighLine context
     attr_reader :highline
 
+    # Returns a HighLine::Paginator instance where you can
+    # call {#page_print} on it.
+    # @param highline [HighLine] context
+    # @example
+    #   HighLine::Paginator.new(highline).page_print(statement)
     def initialize(highline)
       @highline = highline
     end
@@ -16,6 +24,8 @@ class HighLine
     # Note that the final page of _output_ is *not* printed, but returned
     # instead.  This is to support any special handling for the final sequence.
     #
+    # @param text [String] text to be paginated
+    # @return [String] last line if paging is aborted
     def page_print(text)
       return text unless highline.page_at
 

data/lib/highline/question.rb

@@ -27,6 +27,10 @@ class HighLine
     # 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
@@ -42,26 +46,18 @@ class HighLine
     # Question.convert(). If given, a block is yielded the new Question
     # object to allow custom initialization.
     #
+    # @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
-      @template    = template.dup
+      @template    = String(template).dup
       @answer_type = 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         = "*"
@@ -231,8 +227,10 @@ class HighLine
     # Returns the provided _answer_string_ or the default answer for this
     # Question if a default was set and the answer is empty.
     #
+    # @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
+      return default if answer_string.empty? && default
       answer_string
     end
 
@@ -241,16 +239,24 @@ class HighLine
     # responses based on the details of this Question object.
     # Also used by Menu#update_responses.
     #
+    # @return [Hash] responses Hash winner (new and old merge).
+    # @param message_source [Class] Array or String for example.
+    #   Same as {#answer_type}.
+    # @param new_hash_wins [Boolean] merge precedence (new vs. old).
+
     def build_responses(message_source = answer_type, new_hash_wins = false)
       append_default if [::String, Symbol].include? default.class
 
-      old_hash = @responses
+      old_hash = responses
 
       new_hash = build_responses_new_hash(message_source)
 
       @responses = new_hash_wins ? old_hash.merge(new_hash) : new_hash.merge(old_hash)
     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) + '.',
@@ -262,7 +268,7 @@ class HighLine
                                  "(#{expected_range}).",
         :mismatch             => "Your entries didn't match.",
         :not_valid            => "Your answer isn't valid (must match " +
-                                 "#{@validate.inspect})." }
+                                 "#{validate.inspect})." }
     end
 
 
@@ -280,6 +286,9 @@ class HighLine
     #
     # An unrecognized choice (like <tt>:none</tt>) is treated as +nil+.
     #
+    # @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
@@ -325,10 +334,14 @@ class HighLine
       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
@@ -342,8 +355,8 @@ class HighLine
     def expected_range
       expected = [ ]
 
-      expected << "above #{@above}" if @above
-      expected << "below #{@below}" if @below
+      expected << "above #{above}" if above
+      expected << "below #{below}" if below
       expected << "included in #{@in.inspect}" if @in
 
       case expected.size
@@ -373,8 +386,8 @@ class HighLine
     # are not checked.
     #
     def in_range?
-      (!@above or answer > @above) and
-      (!@below or answer < @below) and
+      (!above or answer > above) and
+      (!below or answer < below) and
       (!@in or @in.include?(answer))
     end
 
@@ -397,23 +410,29 @@ class HighLine
     #
     # This process is skipped for single character input.
     #
+    # @param answer_string [String]
+    # @return [String] answer string with whitespaces removed
     def remove_whitespace(answer_string)
-      if !@whitespace
+      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)
@@ -426,10 +445,10 @@ class HighLine
     # 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|
+      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
@@ -439,7 +458,7 @@ class HighLine
 
     # Stringifies the template to be asked.
     def to_s
-      @template
+      template
     end
 
     #
@@ -450,9 +469,9 @@ class HighLine
     # and case handling.
     #
     def valid_answer?
-      !@validate or
-      (@validate.is_a?(Regexp) and answer =~ @validate) or
-      (@validate.is_a?(Proc)   and @validate[answer])
+      !validate or
+      (validate.is_a?(Regexp) and answer =~ validate) or
+      (validate.is_a?(Proc)   and validate[answer])
     end
 
     #
@@ -464,6 +483,9 @@ class HighLine
     #
     # 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?
 
@@ -477,10 +499,21 @@ class HighLine
       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?  "
@@ -493,6 +526,10 @@ class HighLine
       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 responses[:ask_on_error] == :question
         self
@@ -506,8 +543,28 @@ class HighLine
     # 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) unless (@readline && (@echo == true && !@limit))
+      highline.say(self) unless (readline && (echo == true && !limit))
+    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
@@ -518,14 +575,14 @@ class HighLine
     # not affected.
     #
     def append_default
-      if @template =~ /([\t ]+)\Z/
-        @template << "|#{@default}|#{$1}"
-      elsif @template == ""
-        @template << "|#{@default}|  "
-      elsif @template[-1, 1] == "\n"
-        @template[-2, 0] =  "  |#{@default}|"
+      if template =~ /([\t ]+)\Z/
+        template << "|#{default}|#{$1}"
+      elsif template == ""
+        template << "|#{default}|  "
+      elsif template[-1, 1] == "\n"
+        template[-2, 0] =  "  |#{default}|"
       else
-        @template << "  |#{@default}|"
+        template << "  |#{default}|"
       end
     end