highline 1.7.10 → 2.0.3

data/lib/highline/menu.rb

@@ -1,3 +1,6 @@
+# coding: utf-8
+
+#--
 # menu.rb
 #
 #  Created by Gregory Thomas Brown on 2005-05-10.
@@ -6,30 +9,55 @@
 #  This is Free Software.  See LICENSE and COPYING for details.
 
 require "highline/question"
+require "highline/menu/item"
 
 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
+    # Pass +false+ to _color_ to turn off HighLine::Menu's
+    # index coloring.
+    # Pass a color and the Menu's indices will be colored.
+    class << self
+      attr_writer :index_color
+    end
+
+    # Initialize it
+    self.index_color = false
+
+    # Returns color used for coloring Menu's indices
+    class << self
+      attr_reader :index_color
+    end
+
     #
     # 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.
-    #
-    def initialize(  )
+    # 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
       # adjust ours as needed.
       #
-      super("Ignored", [ ], &nil)    # avoiding passing the block along
+      super("Ignored", [], &nil) # avoiding passing the block along
 
-      @items           = [ ]
-      @hidden_items    = [ ]
+      @items           = []
+      @hidden_items    = []
       @help            = Hash.new("There's no help for that topic.")
 
       @index           = :number
@@ -43,14 +71,18 @@ class HighLine
       @shell           = false
       @nil_on_handled  = false
 
+      # Used for coloring Menu indices.
+      # Set it to default. But you may override it.
+      @index_color     = self.class.index_color
+
       # Override Questions responses, we'll set our own.
-      @responses       = { }
+      @responses       = {}
       # Context for action code.
       @highline        = nil
 
       yield self if block_given?
 
-      init_help if @shell and not @help.empty?
+      init_help if @shell && !@help.empty?
     end
 
     #
@@ -119,6 +151,11 @@ class HighLine
     # Defaults to +false+.
     #
     attr_accessor :nil_on_handled
+    #
+    # The color of the index when displaying the menu. See Style class for
+    # available colors.
+    #
+    attr_accessor :index_color
 
     #
     # Adds _name_ to the list of available menu items.  Menu items will be
@@ -133,28 +170,85 @@ class HighLine
     # the current HighLine context before the action code is called and can
     # thus be used for adding output and the like.
     #
-    def choice( name, help = nil, &action )
-      @items << [name, action]
+    # @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, text: 'Load a file',
+    #                 help: "Load a file using your favourite editor.")
+    #     menu.choice(:save, help: "Save data in file.")
+    #     menu.choice(:quit, help: "Exit program.")
+    #
+    #     menu.help("rules", "The rules of this system are as follows...")
+    #   end
+
+    def choice(name, help = nil, text = nil, &action)
+      item = Menu::Item.new(name, text: text, help: help, action: action)
+      @items << item
+      @help.merge!(item.item_help)
+      update_responses # rebuild responses based on our settings
+    end
+
+    #
+    # This method helps reduce the namespaces in the original call,
+    # which would look like this: HighLine::Menu::Item.new(...)
+    # With #build_item, it looks like this: menu.build_item(...)
+    # @param *args splat args, the same args you would pass to an
+    #   initialization of HighLine::Menu::Item
+    # @return [HighLine::Menu::Item] the menu item
+
+    def build_item(*args)
+      Menu::Item.new(*args)
+    end
+
+    #
+    # Adds an item directly to the menu. If you want more configuration
+    # or options, use this method
+    #
+    # @param item [Menu::Item] item containing choice fields and more
+    # @return [void]
 
-      @help[name.to_s.downcase] = help unless help.nil?
-      update_responses  # rebuild responses based on our settings
+    def add_item(item)
+      @items << item
+      @help.merge!(item.item_help)
+      update_responses
     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)
+    #
+    # choice has more options available to you, like longer text or help (and
+    # of course, individual actions)
     #
-    def choices( *names, &action )
+    def choices(*names, &action)
       names.each { |n| choice(n, &action) }
     end
 
-    # Identical to choice(), but the item will not be listed for the user.
-    def hidden( name, help = nil, &action )
-      @hidden_items << [name, action]
+    # 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)
 
-      @help[name.to_s.downcase] = help unless help.nil?
+    def hidden(name, help = nil, &action)
+      item = Menu::Item.new(name, text: name, help: help, action: action)
+      @hidden_items << item
+      @help.merge!(item.item_help)
     end
 
     #
@@ -172,31 +266,36 @@ class HighLine
     # _index_suffix_ to a single space and _select_by_ to <tt>:name</tt>.
     # Because of this, you should make a habit of setting the _index_ first.
     #
-    def index=( style )
+    def index=(style)
       @index = style
 
+      return unless @index == :none || @index.is_a?(::String)
+
       # Default settings.
-      if @index == :none or @index.is_a?(::String)
-        @index_suffix = " "
-        @select_by    = :name
-      end
+      @index_suffix = " "
+      @select_by    = :name
     end
 
     #
     # Initializes the help system by adding a <tt>:help</tt> choice, some
     # action code, and the default help listing.
     #
-    def init_help(  )
+    def init_help
       return if @items.include?(:help)
 
       topics    = @help.keys.sort
-      help_help = @help.include?("help") ? @help["help"] :
-                  "This command will display helpful messages about " +
-                  "functionality, like this one.  To see the help for " +
-                  "a specific topic enter:\n\thelp [TOPIC]\nTry asking " +
-                  "for help on any of the following:\n\n" +
-                  "<%= list(#{topics.inspect}, :columns_across) %>"
-      choice(:help, help_help) do |command, topic|
+      help_help =
+        if @help.include?("help")
+          @help["help"]
+        else
+          "This command will display helpful messages about " \
+            "functionality, like this one.  To see the help for " \
+            "a specific topic enter:\n\thelp [TOPIC]\nTry asking " \
+            "for help on any of the following:\n\n" \
+            "<%= list(#{topics.inspect}, :columns_across) %>"
+        end
+
+      choice(:help, help_help) do |_command, topic|
         topic.strip!
         topic.downcase!
         if topic.empty?
@@ -209,9 +308,13 @@ 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.
     #
-    def help( topic, help )
+    # @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
 
@@ -235,24 +338,23 @@ class HighLine
     # <tt>:menu_only</tt>::    Just the menu items, followed up by a likely
     #                          short _prompt_.
     # <i>any ERb String</i>::  Will be taken as the literal _layout_.  This
-    #                          String can access <tt>@header</tt>,
-    #                          <tt>@menu</tt> and <tt>@prompt</tt>, but is
-    #                          otherwise evaluated in the typical HighLine
-    #                          context, to provide access to utilities like
-    #                          HighLine.list() primarily.
+    #                          String can access <tt>header</tt>,
+    #                          <tt>menu</tt> and <tt>prompt</tt>, but is
+    #                          otherwise evaluated in the TemplateRenderer
+    #                          context so each method is properly delegated.
     #
     # If set to either <tt>:one_line</tt>, or <tt>:menu_only</tt>, _index_
     # will default to <tt>:none</tt> and _flow_ will default to
     # <tt>:inline</tt>.
     #
-    def layout=( new_layout )
+    def layout=(new_layout)
       @layout = new_layout
 
       # Default settings.
       case @layout
       when :one_line, :menu_only
         self.index = :none
-        @flow  = :inline
+        @flow = :inline
       end
     end
 
@@ -260,66 +362,142 @@ class HighLine
     # This method returns all possible options for auto-completion, based
     # on the settings of _index_ and _select_by_.
     #
-    def options(  )
-      # add in any hidden menu commands
-      @items.concat(@hidden_items)
-
-      by_index = if @index == :letter
-        l_index = "`"
-        @items.map { "#{l_index.succ!}" }
+    def options
+      case @select_by
+      when :index
+        map_items_by_index
+      when :name
+        map_items_by_name
       else
-        (1 .. @items.size).collect { |s| String(s) }
+        map_items_by_index + map_items_by_name
       end
-      by_name = @items.collect { |c| c.first }
+    end
 
-      case @select_by
-      when :index then
-        by_index
-      when :name
-        by_name
+    def map_items_by_index
+      if [:letter, :capital_letter].include?(@index)
+        # @ and ` are the previous ASCII characters to A and a respectively
+        prev_char = (@index == :capital_letter ? '@' : '`')
+        all_items.map { prev_char.succ!.dup }
       else
-        by_index + by_name
+        (1..all_items.size).map(&:to_s)
       end
-    ensure
-      # make sure the hidden items are removed, before we return
-      @items.slice!(@items.size - @hidden_items.size, @hidden_items.size)
+    end
+
+    def map_items_by_name
+      all_items.map(&:name)
+    end
+
+    def all_items
+      @items + @hidden_items
     end
 
     #
     # 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().
-    #
-    def select( highline_context, selection, details = nil )
+    # 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)
+      items = all_items
 
       # Find the selected action.
-      name, action = if selection =~ /^\d+$/
-        @items[selection.to_i - 1]
+      selected_item = find_item_from_selection(items, selection)
+
+      # Run or return it.
+      @highline = highline_context
+      value_for_selected_item(selected_item, details)
+    end
+
+    def find_item_from_selection(items, selection)
+      if selection =~ /^\d+$/ # is a number?
+        get_item_by_number(items, 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(items, selection)
       end
+    end
 
-      # Run or return it.
-      if not action.nil?
-        @highline = highline_context
-        if @shell
-          result = action.call(name, details)
-        else
-          result = action.call(name)
-        end
+    # Returns the menu item referenced by its index
+    # @param selection [Integer] menu item's index.
+    def get_item_by_number(items, 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(items, selection)
+      item = items.find { |i| i.name == selection }
+      return item if item
+
+      # 97 is the "a" letter at ascii table
+      # Ex: For "a" it will return 0, and for "c" it will return 2
+      index = selection.downcase.ord - 97
+      items[index]
+    end
+
+    def value_for_selected_item(item, details)
+      if item.action
+        result = if @shell
+                   item.action.call(item.name, details)
+                 else
+                   item.action.call(item.name)
+                 end
         @nil_on_handled ? nil : result
-      elsif action.nil?
-        name
       else
-        nil
+        item.name
+      end
+    end
+
+    def gather_selected(highline_context, selections, details = nil)
+      @highline = highline_context
+      # add in any hidden menu commands
+      items = all_items
+
+      if selections.is_a?(Array)
+        value_for_array_selections(items, selections, details)
+      elsif selections.is_a?(Hash)
+        value_for_hash_selections(items, selections, details)
+      else
+        raise ArgumentError, "selections must be either Array or Hash"
+      end
+    end
+
+    def value_for_array_selections(items, selections, details)
+      # Find the selected items and return values
+      selected_items = selections.map do |selection|
+        find_item_from_selection(items, selection)
+      end
+      index = 0
+      selected_items.map do |selected_item|
+        value = value_for_selected_item(selected_item, self.shell ? details[index] : nil)
+        index += 1
+        value
+      end
+    end
+
+    def value_for_hash_selections(items, selections, details)
+      # Find the selected items and return in hash form
+      index = 0
+      selections.each_with_object({}) do |(key, selection), memo|
+        selected_item = find_item_from_selection(items, selection)
+        value = value_for_selected_item(selected_item, self.shell ? details[index] : nil)
+        index += 1
+        memo[key] = value
+      end
+    end
+
+    def decorate_index(index)
+      if index_color
+        HighLine.color(index, index_color)
+      else
+        index
       end
-    ensure
-      # make sure the hidden items are removed, before we return
-      @items.slice!(@items.size - @hidden_items.size, @hidden_items.size)
     end
 
     #
@@ -327,17 +505,26 @@ class HighLine
     # This method returns all menu items to be displayed, complete with
     # indexes.
     #
-    def to_ary(  )
+    def to_ary
+      @items.map.with_index { |item, ix| decorate_item(item.text.to_s, ix) }
+    end
+
+    def decorate_item(text, ix)
+      decorated, non_decorated = mark_for_decoration(text, ix)
+      decorate_index(decorated) + non_decorated
+    end
+
+    def mark_for_decoration(text, ix)
       case @index
       when :number
-        @items.map { |c| "#{@items.index(c) + 1}#{@index_suffix}#{c.first}" }
-      when :letter
-        l_index = "`"
-        @items.map { |c| "#{l_index.succ!}#{@index_suffix}#{c.first}" }
+        ["#{ix + 1}#{@index_suffix}", text]
+      when :letter, :capital_letter
+        first_letter = (@index == :capital_letter ? 'A' : 'a')
+        ["#{(first_letter.ord + ix).chr}#{@index_suffix}", text]
       when :none
-        @items.map { |c| "#{c.first}" }
+        [text, ""]
       else
-        @items.map { |c| "#{index}#{@index_suffix}#{c.first}" }
+        ["#{index}#{@index_suffix}", text]
       end
     end
 
@@ -345,37 +532,45 @@ class HighLine
     # Allows Menu to behave as a String, just like Question.  Returns the
     # _layout_ to be rendered, which is used by HighLine.say().
     #
-    def to_s(  )
+    def to_s
       case @layout
       when :list
-        '<%= if @header.nil? then '' else "#{@header}:\n" end %>' +
-        "<%= list( @menu, #{@flow.inspect},
-                          #{@list_option.inspect} ) %>" +
-        "<%= @prompt %>"
+        %(<%= header ? "#{header}:\n" : '' %>) +
+          parse_list +
+          show_default_if_any +
+          "<%= prompt %>"
       when :one_line
-        '<%= if @header.nil? then '' else "#{@header}:  " end %>' +
-        "<%= @prompt %>" +
-        "(<%= list( @menu, #{@flow.inspect},
-                           #{@list_option.inspect} ) %>)" +
-        "<%= @prompt[/\s*$/] %>"
+        %(<%= header ? "#{header}:  " : '' %>) +
+          "<%= prompt %>" \
+          "(" + parse_list + ")" +
+          show_default_if_any +
+          "<%= prompt[/\s*$/] %>"
       when :menu_only
-        "<%= list( @menu, #{@flow.inspect},
-                          #{@list_option.inspect} ) %><%= @prompt %>"
+        parse_list +
+          show_default_if_any +
+          "<%= prompt %>"
       else
         @layout
       end
     end
 
+    def parse_list
+      "<%= list( menu, #{@flow.inspect},
+           #{@list_option.inspect} ) %>"
+    end
+
+    def show_default_if_any
+      default.to_s.empty? ? "" : "(#{default}) "
+    end
+
     #
     # This method will update the intelligent responses to account for
     # Menu specific differences.  Calls the superclass' (Question's)
     # build_responses method, overriding its default arguments to specify
-    # 'options' will be used to populate choice lists, and that
-    # the newly built hash will predominate over the preexisting hash
-    # for any keys that are the same.
+    # 'options' will be used to populate choice lists.
     #
-    def update_responses(  )
-      build_responses(options, true)
+    def update_responses
+      build_responses(options)
     end
   end
 end

data/lib/highline/paginator.rb

@@ -0,0 +1,52 @@
+# 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
+
+    #
+    # Page print a series of at most _page_at_ lines for _output_.  After each
+    # page is printed, HighLine will pause until the user presses enter/return
+    # then display the next page of data.
+    #
+    # 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
+
+      lines = text.lines.to_a
+      while lines.size > highline.page_at
+        highline.puts lines.slice!(0...highline.page_at).join
+        highline.puts
+        # Return last line if user wants to abort paging
+        return "...\n#{lines.last}" unless continue_paging?
+      end
+      lines.join
+    end
+
+    #
+    # Ask user if they wish to continue paging output. Allows them to
+    # type "q" to cancel the paging process.
+    #
+    def continue_paging?
+      command = highline.new_scope.ask(
+        "-- press enter/return to continue or q to stop -- "
+      ) { |q| q.character = true }
+      command !~ /\A[qQ]\Z/ # Only continue paging if Q was not hit.
+    end
+  end
+end