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' ( 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.


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.

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.


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.

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 prompt to display.


The options to prompt for.


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.

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.

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.


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


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.


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.


Option keys are treated case insensitively.

Defuaults to true.


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


Yuval Kogman <>


        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.