NAME

CPANPLUS::Tools::Term - Term::ReadLine UI made easy

SYNOPSIS

    use CPANPLUS::Tools::Term;
    use Term::ReadLine;

    my $term = Term::ReadLine->new('brand');

    my $reply = $term->get_reply(
                    prompt => 'What is your favourite colour?',
                    choices => [qw|blue red green|],
                    default => blue,
    );

    my $bool = $term->ask_yn(
                        prompt => 'Do you like cookies?',
                        default => 'y',
                );

    my $string = q[some_command -option --no-foo --quux='this thing'];

    my ($options,$munged_input) = $term->parse_options($string);

    ### don't have CPANPLUS::Tools::Term issue warnings -- default is '1'
    $CPANPLUS::Tools::Term::VERBOSE = 0;

    ### always pick the default (good for non-interactive terms)
    ### -- default is '0'
    $CPANPLUS::Tools::Term::AUTOREPLY = 1;

DESCRIPTION

CPANPLUS::Tools::Term is a transparent way of eliminating the overhead of having to format a question and then validate the reply, informing the user if the answer was not proper and re-issuing the question.

Simply give it the question you want to ask, optionally with choices the user can pick from and a default and CPANPLUS::Tools::Term will DWYM.

For asking a yes or no question, there's even a shortcut.

How it works

CPANPLUS::Tools::Term places itself at the back of the Term::ReadLine @ISA array, so you can call it's functions through your term object.

Methods

get_reply

get_reply takes the following arguments:

prompt: A string containing the question you want to ask,
choices: An array reference with all the choices you want to let the user pick from. This parameter is optional.
default: The default answer -- This is the answer picked if the user just hits enter or if $AUTOREPLY is set to true. This parameter is optional.
allow: A handler you can specify to check the reply against. This can be any of the types that the CPANPLUS::Tools::Check check function allows, so please refer to that manpage for details. This parameter is optional.

ask_yn

ask_yn takes the following arguments:

prompt: A string containing the question you want to ask,
default: The default answer -- This is the answer picked if the user just hits enter or if $AUTOREPLY is set to true. This paramter is optional.

The choices that are presented are either yes or no and will return 0 if no was answered and 1 if yes was answered.

parse_options

parse_options will convert all options given from an input string to a hash reference. If called in list context it will also return the part of the input string that it found no options in.

Consider this example:

    my $str =   q[command --no-foo --baz --bar=0 --quux=bleh ] .
                q[--option="some'thing" -one-dash -single=blah' arg];

    my ($options,$munged) =  $term->parse_options($str);

    ### $options would contain: ###
    $options = {
                'foo'       => 0,
                'bar'       => 0,
                'one-dash'  => 1,
                'baz'       => 1,
                'quux'      => 'bleh',
                'single'    => 'blah\'',
                'option'    => 'some\'thing'
    };

    ### and this is the munged version of the input string,
    ### ie what's left of the input minus the options
    $munged = 'command arg';

As you can see, you can either use a single or a double - to indicate an option. If you prefix an option with no- and do not give it a value, it will be set to 0. If it has no prefix and no value, it will be set to 1. Otherwise, it will be set to it's value. Note also that it can deal fine with single/double quoting issues.

Global Variables

The behaviour of CPANPLUS::Tools::Term can be altered by changing the following global variables:

AUTHOR

This module by Jos Boumans <kane@cpan.org>.

COPYRIGHT

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.

CPANPLUS::Tools::Term - Term::ReadLine UI made easy