Prompt::ReadKey - Darcs style single readkey option prompt.
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) }, ], );
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.
Display a prompt, with additinal formatting and processing of additional and/or default options, an automated help option, etc.
Low level prompt, without processing of options and prompt reformatting.
Affected by repeat_until_valid.
repeat_until_valid
Don't prompt repeatedly on invalid answers.
Just delegates to print using the prompt argument.
print
prompt
Returns a list of options, based on the arguments, defaults, various flags, etc.
Delegates to process_option for a list of options.
process_option
Low level option processor, checks for validity mostly.
Merges the explicit default options, additional options, and optional help option.
Returns a list of keys that trigger the help command. Defaults to ? and h.
?
h
If auto_help is true then it returns help_keys.
auto_help
help_keys
Creates an option from the get_help_keys key list.
get_help_keys
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.
help_footer
help_header
option_to_help_text
tabulate_help_text
Uses Text::Table to pretty print the help.
Affected by the help_headings option.
help_headings
Makes a hashref of text values from an option, to be formatted by tabulate_help_text.
Sort the options. This is a stub for subclassing, the current implementation leaves the options in the order they were gathered.
Check the set of options for validity (duplicate names and keys, etc).
Affected by the allow_duplicate_names option.
allow_duplicate_names
Returns the prompt string (from default or args).
Format the option keys for the prompt. Appeneded to the actual prompt by format_prompt.
format_prompt
Concatenates the key skipping options for which is_help is true in the spec.
is_help
If the case_insensitive option is true then the default command's key will be uppercased, and the rest lowercased.
case_insensitive
Append the output of format_options in brackets to the actual prompt, and adds a space.
format_options
Wrapper for read_key that returns the option selected.
read_key
Called when an invalid key was entered. Uses print internally.
Process the option into it's return value, triggerring callbacks or mapping to the option name as requested.
calls ReadMode and ReadKey to get a single character from Term::ReadKey.
ReadMode
ReadKey
Affected by echo_key, auto_newline, readkey_mode, readmode.
echo_key
auto_newline
readkey_mode
readmode
Under case_insensitive mode will lowercase the character specified.
Called for every character read and every character in the option spec by read_option.
read_option
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.
These attributes control default values for options.
The attribute name is prefixed with default for clarity.
default
Additional options to append to the default or explicitly specified options.
Defaults to nothing.
Whether or not to automatically create a help command.
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.
name
heading
Defaults to Key, Name, Description.
Text to prepend to the help message.
Defaults to a simple description of the help screen.
Text to append to the help message.
No default value.
The keys that create_help_option will assign to the help option.
create_help_option
Defaults to ? and h.
Whether or not duplicate option names are allowed. Defaults to
The argument to pass to ReadKey. Default to 0. See Term::ReadKey.
0
The value to give to ReadMode. Defaults to 3. See Term::ReadKey.
3
Whether or not to echo back the key entered.
Whether or not to add a newline after reading a key (if the key is not newline itself).
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.
option_to_return_value
Defaults to true.
Option keys are treated case insensitively.
Defuaults to true.
When invalid input is entered, reprompt until a valid choice is made.
This module is maintained using Darcs. You can get the latest version from http://nothingmuch.woobling.org/code, and use darcs send to commit changes.
darcs send
Yuval Kogman <nothingmuch@woobling.org>
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.
To install Prompt::ReadKey, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prompt::ReadKey
CPAN shell
perl -MCPAN -e shell install Prompt::ReadKey
For more information on module installation, please visit the detailed CPAN module installation guide.