NAME

Prompt::ReadKey - Darcs style single readkey option prompt.

SYNOPSIS

        my $p = Prompt::ReadKey->new;

        my $name = $p->prompt(
                prompt => "blah",
                options => [
                        { name => "foo" },
                        {
                                name => "bar",
                                default => 1,
                                doc => "This is the bar command", # used in help message
                                keys => [qw(b x)],                # defaults to substr($name, 0, 1)
                        },
                ],
        );

DESCRIPTION

This module aims to provide a very subclassible Term::ReadKey based prompter inspired by Darcs' (http://darcs.net) fantastic command line user interface.

Many options exist both as accessors for default values, and are passable as named arguments to the methods of the api.

The api is structured so that the underlying methods are usable as well, you don't need to use the high level api to make use of this module if you don't want to.

METHODS

prompt %args

Display a prompt, with additinal formatting and processing of additional and/or default options, an automated help option, etc.

do_prompt %args

Low level prompt, without processing of options and prompt reformatting.

Affected by repeat_until_valid.

prompt_once %args

Don't prompt repeatedly on invalid answers.

print_prompt %args

Just delegates to print using the prompt argument.

prepare_options %args

Returns a list of options, based on the arguments, defaults, various flags, etc.

process_options %args

Delegates to process_option for a list of options.

process_option %args

Low level option processor, checks for validity mostly.

gather_options

Merges the explicit default options, additional options, and optional help option.

get_help_keys %args

Returns a list of keys that trigger the help command. Defaults to ? and h.

If auto_help is true then it returns help_keys.

create_help_option %args

Creates an option from the get_help_keys key list.

display_help %args

Prints out a help message.

Affected by help_footer and help_header, delegates to option_to_help_text and tabulate_help_text for the actual work, finally sending the output to print.

tabulate_help_text %args

Uses Text::Table to pretty print the help.

Affected by the help_headings option.

option_to_help_text %args

Makes a hashref of text values from an option, to be formatted by tabulate_help_text.

sort_options %args

Sort the options. This is a stub for subclassing, the current implementation leaves the options in the order they were gathered.

filter_options %args

Check the set of options for validity (duplicate names and keys, etc).

Affected by the allow_duplicate_names option.

prompt_string %args

Returns the prompt string (from default or args).

format_options %args

Format the option keys for the prompt. Appeneded to the actual prompt by format_prompt.

Concatenates the key skipping options for which is_help is true in the spec.

If the case_insensitive option is true then the default command's key will be uppercased, and the rest lowercased.

format_prompt %args

Append the output of format_options in brackets to the actual prompt, and adds a space.

read_option %args

Wrapper for read_key that returns the option selected.

invalid_choice %args

Called when an invalid key was entered. Uses print internally.

option_to_return_value %args

Process the option into it's return value, triggerring callbacks or mapping to the option name as requested.

read_key %args

calls ReadMode and ReadKey to get a single character from Term::ReadKey.

Affected by echo_key, auto_newline, readkey_mode, readmode.

process_char %args

Under case_insensitive mode will lowercase the character specified.

Called for every character read and every character in the option spec by read_option.

print @text

The default version will just call the builtin print. It will locally set $| to 1, though that is probably superflous (I think ReadKey will flush anyway).

This is the only function that does not take named arguments.

OPTIONS AND ATTRIBUTES

These attributes control default values for options.

prompt

The prompt to display.

options

The options to prompt for.

additional_options

Additional options to append to the default or explicitly specified options.

Defaults to nothing.

auto_help

Whether or not to automatically create a help command.

help_headings

The headings of the help table.

Takes an array of hash refs, which are expected to have the name and heading keys filled in. The array is used for ordering and displaying the help table.

Defaults to Key, Name, Description.

help_header

Text to prepend to the help message.

Defaults to a simple description of the help screen.

help_footer

Text to append to the help message.

No default value.

help_keys

The keys that create_help_option will assign to the help option.

Defaults to ? and h.

allow_duplicate_names

Whether or not duplicate option names are allowed. Defaults to

readkey_mode

The argument to pass to ReadKey. Default to 0. See Term::ReadKey.

readmode

The value to give to ReadMode. Defaults to 3. See Term::ReadKey.

echo_key

Whether or not to echo back the key entered.

auto_newline

Whether or not to add a newline after reading a key (if the key is not newline itself).

return_option

Overrides return_name and the callback firing mechanism, so that the option spec is always returned.

return_name

When returning a value from option_to_return_value, and there is no callback, will cause the name of the option to be returned instead of the option spec.

Defaults to true.

case_insensitive

Option keys are treated case insensitively.

Defuaults to true.

repeat_until_valid

When invalid input is entered, reprompt until a valid choice is made.

AUTHOR

Yuval Kogman <nothingmuch@woobling.org>

COPYRIGHT

        Copyright (c) 2008 Yuval Kogman. All rights reserved
        This program is free software; you can redistribute
        it and/or modify it under the same terms as Perl itself.