Class: HighLine::Menu
Overview
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.
Instance Attribute Summary collapse
-
#flow ⇒ Object
This attribute is passed directly on as the mode to HighLine.list() by all the preset layouts.
-
#header ⇒ Object
Used by all the preset layouts to display title and/or introductory information, when set.
-
#index ⇒ Object
An index to append to each menu item in display.
-
#index_suffix ⇒ Object
The String placed between an index and a menu item.
-
#layout ⇒ Object
An ERb layout to use when displaying this Menu object.
-
#list_option ⇒ Object
This setting is passed on as the third parameter to HighLine.list() by all the preset layouts.
-
#nil_on_handled ⇒ Object
When
true
, any selected item handled by provided action code, will returnnil
, instead of the results to the action code. -
#prompt ⇒ Object
Used by all the preset layouts to ask the actual question to fetch a menu selection from the user.
-
#select_by ⇒ Object
The select_by attribute controls how the user is allowed to pick a menu item.
-
#shell ⇒ Object
When set to
true
, responses are allowed to be an entire line of input, including details beyond the command itself.
Attributes inherited from Question
#above, #answer_type, #below, #case, #character, #confirm, #default, #directory, #echo, #first_answer, #gather, #glob, #in, #limit, #overwrite, #question, #readline, #responses, #validate, #whitespace
Instance Method Summary collapse
-
#choice(name, help = nil, &action) ⇒ Object
Adds name to the list of available menu items.
-
#choices(*names, &action) ⇒ Object
A shortcut for multiple calls to the sister method choice().
-
#help(topic, help) ⇒ Object
Used to set help for arbitrary topics.
-
#hidden(name, help = nil, &action) ⇒ Object
Identical to choice(), but the item will not be listed for the user.
-
#init_help ⇒ Object
Initializes the help system by adding a
:help
choice, some action code, and the default help listing. -
#initialize {|_self| ... } ⇒ Menu
constructor
Create an instance of HighLine::Menu.
-
#options ⇒ Object
This method returns all possible options for auto-completion, based on the settings of index and select_by.
-
#select(highline_context, selection, details = nil) ⇒ Object
This method processes the auto-completed user selection, based on the rules for this Menu object.
-
#to_ary ⇒ Object
Allows Menu objects to pass as Arrays, for use with HighLine.list().
-
#to_str ⇒ Object
Allows Menu to behave as a String, just like Question.
-
#update_responses ⇒ Object
This method will update the intelligent responses to account for Menu specific differences.
Methods inherited from Question
#answer_or_default, #build_responses, #change_case, #convert, #expected_range, #first_answer?, #in_range?, #remove_whitespace, #selection, #valid_answer?
Constructor Details
#initialize {|_self| ... } ⇒ Menu
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.
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 |
# File 'lib/highline/menu.rb', line 26 def initialize( ) # # Initialize Question objects with ignored values, we'll # adjust ours as needed. # super("Ignored", [ ], &nil) # avoiding passing the block along @items = [ ] @hidden_items = [ ] @help = Hash.new("There's no help for that topic.") @index = :number @index_suffix = ". " @select_by = :index_or_name @flow = :rows @list_option = nil @header = nil @prompt = "? " @layout = :list @shell = false @nil_on_handled = false # Override Questions responses, we'll set our own. @responses = { } # Context for action code. @highline = nil yield self if block_given? init_help if @shell and not @help.empty? update_responses # rebuild responses based on our settings end |
Instance Attribute Details
#flow ⇒ Object
This attribute is passed directly on as the mode to HighLine.list() by all the preset layouts. See that method for appropriate settings.
87 88 89 |
# File 'lib/highline/menu.rb', line 87 def flow @flow end |
#header ⇒ Object
Used by all the preset layouts to display title and/or introductory information, when set. Defaults to nil
.
98 99 100 |
# File 'lib/highline/menu.rb', line 98 def header @header end |
#index ⇒ Object
An index to append to each menu item in display. See Menu.index=() for details.
63 64 65 |
# File 'lib/highline/menu.rb', line 63 def index @index end |
#index_suffix ⇒ Object
The String placed between an index and a menu item. Defaults to “. ”. Switches to “ ”, when index is set to a String (like “-”).
68 69 70 |
# File 'lib/highline/menu.rb', line 68 def index_suffix @index_suffix end |
#layout ⇒ Object
An ERb layout to use when displaying this Menu object. See Menu.layout=() for details.
108 109 110 |
# File 'lib/highline/menu.rb', line 108 def layout @layout end |
#list_option ⇒ Object
This setting is passed on as the third parameter to HighLine.list() by all the preset layouts. See that method for details of its effects. Defaults to nil
.
93 94 95 |
# File 'lib/highline/menu.rb', line 93 def list_option @list_option end |
#nil_on_handled ⇒ Object
When true
, any selected item handled by provided action code, will return nil
, instead of the results to the action code. This may prove handy when dealing with mixed menus where only the names of items without any code (and nil
, of course) will be returned. Defaults to false
.
124 125 126 |
# File 'lib/highline/menu.rb', line 124 def nil_on_handled @nil_on_handled end |
#prompt ⇒ Object
Used by all the preset layouts to ask the actual question to fetch a menu selection from the user. Defaults to “? ”.
103 104 105 |
# File 'lib/highline/menu.rb', line 103 def prompt @prompt end |
#select_by ⇒ Object
The select_by attribute controls how the user is allowed to pick a menu item. The available choices are:
:index
-
The user is allowed to type the numerical or alphetical index for their selection.
:index_or_name
-
Allows both methods from the
:index
option and the:name
option. :name
-
Menu items are selected by typing a portion of the item name that will be auto-completed.
82 83 84 |
# File 'lib/highline/menu.rb', line 82 def select_by @select_by end |
#shell ⇒ Object
When set to true
, responses are allowed to be an entire line of input, including details beyond the command itself. Only the first “word” of input will be matched against the menu choices, but both the command selected and the rest of the line will be passed to provided action blocks. Defaults to false
.
116 117 118 |
# File 'lib/highline/menu.rb', line 116 def shell @shell end |
Instance Method Details
#choice(name, help = nil, &action) ⇒ Object
Adds name to the list of available menu items. Menu items will be displayed in the order they are added.
An optional action can be associated with this name and if provided, it will be called if the item is selected. The result of the method will be returned, unless nil_on_handled is set (when you would get nil
instead). In shell mode, a provided block will be passed the command chosen and any details that followed the command. Otherwise, just the command is passed. The @highline
variable is set to the current HighLine context before the action code is called and can thus be used for adding output and the like.
139 140 141 142 143 |
# File 'lib/highline/menu.rb', line 139 def choice( name, help = nil, &action ) @items << [name, action] @help[name.to_s.downcase] = help unless help.nil? end |
#choices(*names, &action) ⇒ Object
A shortcut for multiple calls to the sister method choice(). Be warned: 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.
151 152 153 |
# File 'lib/highline/menu.rb', line 151 def choices( *names, &action ) names.each { |n| choice(n, &action) } end |
#help(topic, help) ⇒ Object
Used to set help for arbitrary topics. Use the topic "help"
to override the default message.
216 217 218 |
# File 'lib/highline/menu.rb', line 216 def help( topic, help ) @help[topic] = help end |
#hidden(name, help = nil, &action) ⇒ Object
Identical to choice(), but the item will not be listed for the user.
156 157 158 159 160 |
# File 'lib/highline/menu.rb', line 156 def hidden( name, help = nil, &action ) @hidden_items << [name, action] @help[name.to_s.downcase] = help unless help.nil? end |
#init_help ⇒ Object
Initializes the help system by adding a :help
choice, some action code, and the default help listing.
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 |
# File 'lib/highline/menu.rb', line 191 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| topic.strip! topic.downcase! if topic.empty? @highline.say(@help["help"]) else @highline.say("= #{topic}\n\n#{@help[topic]}") end end end |
#options ⇒ Object
This method returns all possible options for auto-completion, based on the settings of index and select_by.
265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 |
# File 'lib/highline/menu.rb', line 265 def ( ) # add in any hidden menu commands @items.concat(@hidden_items) by_index = if @index == :letter l_index = "`" @items.map { "#{l_index.succ!}" } else (1 .. @items.size).collect { |s| String(s) } end by_name = @items.collect { |c| c.first } case @select_by when :index then by_index when :name by_name else by_index + by_name end ensure # make sure the hidden items are removed, before we return @items.slice!(@items.size - @hidden_items.size, @hidden_items.size) end |
#select(highline_context, selection, details = nil) ⇒ Object
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().
295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 |
# File 'lib/highline/menu.rb', line 295 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] else l_index = "`" index = @items.map { "#{l_index.succ!}" }.index(selection) @items.find { |c| c.first == selection } or @items[index] end # Run or return it. if not @nil_on_handled and not action.nil? @highline = highline_context if @shell action.call(name, details) else action.call(name) end elsif action.nil? name else nil end ensure # make sure the hidden items are removed, before we return @items.slice!(@items.size - @hidden_items.size, @hidden_items.size) end |
#to_ary ⇒ Object
Allows Menu objects to pass as Arrays, for use with HighLine.list(). This method returns all menu items to be displayed, complete with indexes.
331 332 333 334 335 336 337 338 339 340 341 342 343 |
# File 'lib/highline/menu.rb', line 331 def to_ary( ) 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}" } when :none @items.map { |c| "#{c.first}" } else @items.map { |c| "#{index}#{@index_suffix}#{c.first}" } end end |
#to_str ⇒ Object
Allows Menu to behave as a String, just like Question. Returns the layout to be rendered, which is used by HighLine.say().
349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 |
# File 'lib/highline/menu.rb', line 349 def to_str( ) case @layout when :list '<%= if @header.nil? then '' else "#{@header}:\n" end %>' + "<%= list( @menu, #{@flow.inspect}, #{@list_option.inspect} ) %>" + "<%= @prompt %>" when :one_line '<%= if @header.nil? then '' else "#{@header}: " end %>' + "<%= @prompt %>" + "(<%= list( @menu, #{@flow.inspect}, #{@list_option.inspect} ) %>)" + "<%= @prompt[/\s*$/] %>" when :menu_only "<%= list( @menu, #{@flow.inspect}, #{@list_option.inspect} ) %><%= @prompt %>" else @layout end end |
#update_responses ⇒ Object
This method will update the intelligent responses to account for Menu specific differences. This overrides the work done by Question.build_responses().
375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 |
# File 'lib/highline/menu.rb', line 375 def update_responses( ) append_default unless default.nil? @responses = { :ambiguous_completion => "Ambiguous choice. " + "Please choose one of #{.inspect}.", :ask_on_error => "? ", :invalid_type => "You must enter a valid #{}.", :no_completion => "You must choose one of " + "#{.inspect}.", :not_in_range => "Your answer isn't within the expected range " + "(#{expected_range}).", :not_valid => "Your answer isn't valid (must match " + "#{@validate.inspect})." }.merge(@responses) end |