Class: HighLine::Menu

Inherits:
Question show all
Defined in:
lib/highline/menu.rb,
lib/highline/menu/item.rb

Overview

Menu objects encapsulate all the details of a call to HighLine#choose. Using the accessors and #choice and #choices, the block passed to #choose can detail all aspects of menu display and control.

Defined Under Namespace

Classes: Item

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes inherited from Question

#above, #answer, #answer_type, #below, #case, #character, #completion, #confirm, #default, #default_hint_show, #directory, #echo, #first_answer, #gather, #glob, #in, #limit, #overwrite, #readline, #template, #validate, #verify_match, #whitespace

Instance Method Summary collapse

Methods inherited from Question

#answer_or_default, #ask_on_error_msg, build, #build_responses, #build_responses_new_hash, #change_case, #check_range, #choices_complete, #confirm_question, #convert, #default_responses_hash, #expected_range, #final_response, #final_responses, #first_answer?, #format_answer, #get_echo_for_response, #get_response, #get_response_or_default, #in_range?, #remove_whitespace, #responses, #selection, #show_question, #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, #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.

Examples:

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

Yields:

  • (_self)

Yield Parameters:



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/highline/menu.rb', line 52

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

  # 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       = {}
  # Context for action code.
  @highline        = nil

  yield self if block_given?

  init_help if @shell && !@help.empty?
end

Class Attribute Details

.index_color ⇒ Object

Returns the value of attribute index_color.



34
35
36
 
# File 'lib/highline/menu.rb', line 34

def index_color
  @index_color
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.



116
117
118
 
# File 'lib/highline/menu.rb', line 116

def flow
  @flow
end

#header ⇒ Object

Used by all the preset layouts to display title and/or introductory information, when set. Defaults to nil.



127
128
129
 
# File 'lib/highline/menu.rb', line 127

def header
  @header
end

#index ⇒ Object

An index to append to each menu item in display. See Menu.index=() for details.



92
93
94
 
# File 'lib/highline/menu.rb', line 92

def index
  @index
end

#index_color ⇒ Object

The color of the index when displaying the menu. See Style class for available colors.



158
159
160
 
# File 'lib/highline/menu.rb', line 158

def index_color
  @index_color
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 “-”).



97
98
99
 
# File 'lib/highline/menu.rb', line 97

def index_suffix
  @index_suffix
end

#layout ⇒ Object

An ERb layout to use when displaying this Menu object. See Menu.layout=() for details.



137
138
139
 
# File 'lib/highline/menu.rb', line 137

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.



122
123
124
 
# File 'lib/highline/menu.rb', line 122

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.



153
154
155
 
# File 'lib/highline/menu.rb', line 153

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 “? ”.



132
133
134
 
# File 'lib/highline/menu.rb', line 132

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 alphabetical 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.



111
112
113
 
# File 'lib/highline/menu.rb', line 111

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.



145
146
147
 
# File 'lib/highline/menu.rb', line 145

def shell
  @shell
end

Instance Method Details

#add_item(item) ⇒ void

This method returns an undefined value.

Adds an item directly to the menu. If you want more configuration or options, use this method

Parameters:

  • item (Menu::Item) —

    item containing choice fields and more



217
218
219
220
221
 
# File 'lib/highline/menu.rb', line 217

def add_item(item)
  @items << item
  @help.merge!(item.item_help)
  update_responses
end

#all_items ⇒ Object 



390
391
392
 
# File 'lib/highline/menu.rb', line 390

def all_items
  @items + @hidden_items
end

#build_item(*args) ⇒ HighLine::Menu::Item

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(…)

Parameters:

  • *args —

    splat args, the same args you would pass to an initialization of HighLine::Menu::Item

Returns:



206
207
208
 
# File 'lib/highline/menu.rb', line 206

def build_item(*args)
  Menu::Item.new(*args)
end

#choice(name, help = nil, text = nil, &action) ⇒ void

This method returns an undefined value.

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.

Examples:

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

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

Parameters:

  • name (#to_s) —

    menu item title/header/name to be displayed.

  • action (Proc) —

    callback action to be run when the item is selected.

  • help (String) (defaults to: nil) —

    help/hint string to be displayed.



191
192
193
194
195
196
 
# File 'lib/highline/menu.rb', line 191

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

#choices(*names, &action) ⇒ void

This method returns an undefined value.

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. choice has more options available to you, like longer text or help (and of course, individual actions)

Examples:

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

Parameters:

  • names (Array<#to_s>) —

    menu item titles/headers/names to be displayed.

  • action (Proc) —

    callback action to be run when the item is selected.



237
238
239
 
# File 'lib/highline/menu.rb', line 237

def choices(*names, &action)
  names.each { |n| choice(n, &action) }
end

#decorate_index(index) ⇒ Object 



495
496
497
498
499
500
501
 
# File 'lib/highline/menu.rb', line 495

def decorate_index(index)
  if index_color
    HighLine.color(index, index_color)
  else
    index
  end
end

#decorate_item(text, ix) ⇒ Object 



512
513
514
515
 
# File 'lib/highline/menu.rb', line 512

def decorate_item(text, ix)
  decorated, non_decorated = mark_for_decoration(text, ix)
  decorate_index(decorated) + non_decorated
end

#find_item_from_selection(items, selection) ⇒ Object 



418
419
420
421
422
423
424
 
# File 'lib/highline/menu.rb', line 418

def find_item_from_selection(items, selection)
  if selection =~ /^\d+$/ # is a number?
    get_item_by_number(items, selection)
  else
    get_item_by_letter(items, selection)
  end
end

#gather_selected(highline_context, selections, details = nil) ⇒ Object 



457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/highline/menu.rb', line 457

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

#get_item_by_letter(items, selection) ⇒ Object

Returns the menu item referenced by its title/header/name.

Parameters:

  • selection (String) —

    menu’s title/header/name



434
435
436
437
438
439
440
441
442
 
# File 'lib/highline/menu.rb', line 434

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

#get_item_by_number(items, selection) ⇒ Object

Returns the menu item referenced by its index

Parameters:

  • selection (Integer) —

    menu item’s index.



428
429
430
 
# File 'lib/highline/menu.rb', line 428

def get_item_by_number(items, selection)
  items[selection.to_i - 1]
end

#help(topic, help) ⇒ Object

Used to set help for arbitrary topics. Use the topic "help" to override the default message. Mainly for internal use.

Parameters:

  • topic (String) —

    the menu item header/title/name to be associated with a help message.

  • help (String) —

    the help message to be associated with the menu item/title/name.



317
318
319
 
# File 'lib/highline/menu.rb', line 317

def help(topic, help)
  @help[topic] = help
end

#hidden(name, help = nil, &action) ⇒ void

This method returns an undefined value.

Identical to #choice, but the item will not be listed for the user.

Parameters:

  • name (#to_s) —

    menu item title/header/name to be displayed.

  • help (String) (defaults to: nil) —

    help/hint string to be displayed.

  • action (Proc) —

    callback action to be run when the item is selected.

See Also:



248
249
250
251
252
 
# File 'lib/highline/menu.rb', line 248

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

#init_help ⇒ Object

Initializes the help system by adding a :help choice, some action code, and the default help listing.



283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/highline/menu.rb', line 283

def init_help
  return if @items.include?(:help)

  topics    = @help.keys.sort
  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?
      @highline.say(@help["help"])
    else
      @highline.say("= #{topic}\n\n#{@help[topic]}")
    end
  end
end

#map_items_by_index ⇒ Object 



376
377
378
379
380
381
382
383
384
 
# File 'lib/highline/menu.rb', line 376

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
    (1..all_items.size).map(&:to_s)
  end
end

#map_items_by_name ⇒ Object 



386
387
388
 
# File 'lib/highline/menu.rb', line 386

def map_items_by_name
  all_items.map(&:name)
end

#mark_for_decoration(text, ix) ⇒ Object 



517
518
519
520
521
522
523
524
525
526
527
528
529
 
# File 'lib/highline/menu.rb', line 517

def mark_for_decoration(text, ix)
  case @index
  when :number
    ["#{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
    [text, ""]
  else
    ["#{index}#{@index_suffix}", text]
  end
end

#options ⇒ Object

This method returns all possible options for auto-completion, based on the settings of index and select_by.



365
366
367
368
369
370
371
372
373
374
 
# File 'lib/highline/menu.rb', line 365

def options
  case @select_by
  when :index
    map_items_by_index
  when :name
    map_items_by_name
  else
    map_items_by_index + map_items_by_name
  end
end

#parse_list ⇒ Object 



557
558
559
560
 
# File 'lib/highline/menu.rb', line 557

def parse_list
  "<%= list( menu, #{@flow.inspect},
       #{@list_option.inspect} ) %>"
end

#select(highline_context, selection, details = nil) ⇒ 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 #choice.

Parameters:

  • highline_context (HighLine) —

    a HighLine instance to be used as context.

  • selection (String, Integer) —

    index or title of the selected menu item.

  • details (defaults to: nil) —

    additional parameter to be passed when in shell mode.

Returns:

  • (nil, Object) —

    if @nil_on_handled is set it returns nil, else it returns the action return value.



406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/highline/menu.rb', line 406

def select(highline_context, selection, details = nil)
  # add in any hidden menu commands
  items = all_items

  # Find the selected action.
  selected_item = find_item_from_selection(items, selection)

  # Run or return it.
  @highline = highline_context
  value_for_selected_item(selected_item, details)
end

#show_default_if_any ⇒ Object 



562
563
564
 
# File 'lib/highline/menu.rb', line 562

def show_default_if_any
  default.to_s.empty? ? "" : "(#{default}) "
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.



508
509
510
 
# File 'lib/highline/menu.rb', line 508

def to_ary
  @items.map.with_index { |item, ix| decorate_item(item.text.to_s, ix) }
end

#to_s ⇒ Object

Allows Menu to behave as a String, just like Question. Returns the layout to be rendered, which is used by HighLine.say().



535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
 
# File 'lib/highline/menu.rb', line 535

def to_s
  case @layout
  when :list
    %(<%= header ? "#{header}:\n" : '' %>) +
      parse_list +
      show_default_if_any +
      "<%= prompt %>"
  when :one_line
    %(<%= header ? "#{header}:  " : '' %>) +
      "<%= prompt %>" \
      "(" + parse_list + ")" +
      show_default_if_any +
      "<%= prompt[/\s*$/] %>"
  when :menu_only
    parse_list +
      show_default_if_any +
      "<%= prompt %>"
  else
    @layout
  end
end

#update_responses ⇒ Object

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.



572
573
574
 
# File 'lib/highline/menu.rb', line 572

def update_responses
  build_responses(options)
end

#value_for_array_selections(items, selections, details) ⇒ Object 



471
472
473
474
475
476
477
478
479
480
481
482
 
# File 'lib/highline/menu.rb', line 471

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

#value_for_hash_selections(items, selections, details) ⇒ Object 



484
485
486
487
488
489
490
491
492
493
 
# File 'lib/highline/menu.rb', line 484

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

#value_for_selected_item(item, details) ⇒ Object 



444
445
446
447
448
449
450
451
452
453
454
455
 
# File 'lib/highline/menu.rb', line 444

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
  else
    item.name
  end
end