- NAME
- SYNOPSIS
- DESCRIPTION
- SEE ALSO
- POD ERRORS

# NAME

ActiveState::Menu - Present a menu

# SYNOPSIS

     use ActiveState::Menu qw(menu prompt yes);

     my $sel = menu([qw(Foo Bar Baz)]);

     menu(intro  => "M E N U",
          menu   => [["&Foo", \&do_foo],
                     ["S&ub", {
                         intro      => "S U B  M E N U",
                         menu       => [qw(Apples Oranges Exit)],
                         loop_until => 2,
                     }],
                     ["Ba&r", \&do_bar],
                     "-----",
                     ["&h", \&do_help],
                     ["(Ba&z)", \&do_baz]],
          prompt => "What (type 'h' for help)?",
          force  => 1,
         );

      my $ans = (prompt("What is your favourite colour?", "blue"));

      if (yes("Do you really want to quit?")) {
          print "Bye\n";
          exit;
      }

# DESCRIPTION

This module provide the following functions:

menu( %opts )

  This function will present a menu on the terminal. The return value is the index of menu item selected (or `undef` if no item was selected).

  The following options are recognised:

         menu:    something to select from (array ref)
         intro:   heading text
         prompt:  prompt text
         force:   force something to be selected (bool)
         disabled_selectable: allow disabled items to be selected
         loop_until: show menu in a loop until a particular item is selected

  The items of the `menu` array can either be plain text strings or an array reference containing a string and a function reference.

  If a function is provided, it will be invoked if the item is selected. The value of $_ is set to the menu text before the function is called, so the same function can serve multiple entries and change it behaviour based on what it finds in $_.

  If the menu text contains the letter "&" then the next letter is taken as a selector. The menu item can be selected by typing this selector. The "&" character itself is not rendered.

  If the menu text is enclosed in parenthesis, then that selection is shown as disabled. Any action associated with the item is not triggered if it is selected.

  If the menu text only consist of the letter "&" followed by a selector char, then the given menu item is invisible, but the associated action could still be triggered. This can be used for hidden commands or help behaviour as demonstrated in the synopsis above.

  If the menu text consist of a line of at least 3 dashes, then it is taken as a separator. An action is associated with a separator line is always ignored.

  If only a single argument is given to the menu() function, it is taken to be the same as the `menu` option.

  The `intro` text is presented as a heading above the menu. Simple markup like *bold*and _underline_ can be used for visual effect. If not provided, no heading is used.

  The `prompt` option replace the default "Please select an item?" text.

  If the `force` option has a TRUE value then it prevents the menu() function from returning undef (if the user did not select any item). It also prevents the index of any disabled items from being returned. The option `disabled_selectable` can be used to counter that behaviour.

  The loop_until option, if specified, makes the menu run in a loop until one of the indices specified by the option is selected. The value of the option should be either a single index, or a reference to an array of indices.

prompt( $question, $default )

  This function will ask a question on the terminal and return the answer given. If the program is not running on a terminal then the $default is returned.

  This function comes from the `ActiveState::Prompt` module. Refer to the documentation of that module for the complete story.

yes( $question, $default )

  Will use the prompt function to ask a question and then return a TRUE value if the answer was "yes". If no $default is given it defaults to "no".

  This function also comes from the `ActiveState::Prompt` module.

# SEE ALSO

ActiveState::Prompt.

# POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 243:

  You forgot a '=back' before '=head1'