/ 
Tools-0.01
/ Tools::Term

NAME

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

SYNOPSIS

use 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 Tools::Term issue warnings -- default is '1'
$Tools::SQL::VERBOSE = 0;

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

DESCRIPTION

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 Tools::Term will DWYM.

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

How it works

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 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 Tools::Term can be altered by changing the following global variables:

$Tools::Term::VERBOSE

This controls whether Tools::Term will issue warnings and explenations as to why certain things may have failed. If you set it to 0, Tools::Term will not output any warnings. The default is 1;

$Tools::Term::AUTOREPLY

This will make every question be answered by the default, and warn if there was no default provided. This is particularly usefull if your program is run in non-interactive mode. The default is 0;

$Tools::Term::INVALID

This holds the string that will be printed when the user makes an invalid choice. You can override this string from your program if you, for example, wish to do localization. The default is Invalid selection, please try again:

See Also

Tools::Check, Term::ReadLine

AUTHOR

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

COPYRIGHT

This module is copyright (c) 2002 Jos Boumans <kane@cpan.org>. All rights reserved.

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