view release on metacpan or  search on metacpan

inc/bundle/Term/UI.pm  view on Meta::CPAN

use strict;
use warnings;

use Carp;
use Params::Check qw[check allow];
use Term::ReadLine;
use Locale::Maketext::Simple Style => 'gettext';
use Term::UI::History;

our $AUTOREPLY;
our $INVALID = loc( 'Invalid selection, please try again: ' );
our $VERBOSE = 1;

push @Term::ReadLine::Stub::ISA, __PACKAGE__
        unless grep { $_ eq __PACKAGE__ } @Term::ReadLine::Stub::ISA;


=pod

=head1 NAME

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

=head1 SYNOPSIS

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

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

    ### Retrieve the entire session as a printable string:
    $hist = Term::UI::History->history_as_string;
    $hist = $term->history_as_string;

=head1 DESCRIPTION

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

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

=head1 HOW IT WORKS

C<Term::UI> places itself at the back of the C<Term::ReadLine>
C<@ISA> array, so you can call its functions through your term object.

C<Term::UI> uses C<Term::UI::History> to record all interactions
with the commandline. You can retrieve this history, or alter
the filehandle the interaction is printed to. See the
C<Term::UI::History> manpage or the C<SYNOPSIS> for details.

=head1 METHODS

=head2 $reply = $term->get_reply( prompt => 'question?', [choices => \@list, default => $list[0], preput => "text to put as default user input", multi => BOOL, print_me => "extra text to print & record", allow => $ref] );

C<get_reply> asks a user a question, and then returns the reply to the
caller. If the answer is invalid (more on that below), the question will
be reposed, until a satisfactory answer has been entered.

You have the option of providing a list of choices the user can pick from
using the C<choices> argument. If the answer is not in the list of choices
presented, the question will be reposed.

If you provide a C<default>  answer, this will be returned when either
C<$AUTOREPLY> is set to true, (see the C<GLOBAL VARIABLES> section further
below), or when the user just hits C<enter>.

The C<preput> argument allows to specify a text that will be inserted to
the prompt line as the initial input which may be edited, deleted or
accepted by the user. If you supply the empty string as the C<preput>
argument then the C<default> value will be preputted. It will only work if
the underlying readline module provide support for it (now it is supported
only by the C<Term::Readline::Gnu>).

You can indicate that the user is allowed to enter multiple answers by
toggling the C<multi> flag. Note that a list of answers will then be
returned to you, rather than a simple string.

By specifying an C<allow> handler, you can yourself validate the answer
a user gives. This can be any of the types that the Params::Check C<allow>
function allows, so please refer to that manpage for details.

Finally, you have the option of adding a C<print_me> argument, which is
simply printed before the prompt. It's printed to the same file handle
as the rest of the questions, so you can use this to keep track of a
full session of Q&A with the user, and retrieve it later using the
C<< Term::UI->history_as_string >> function.

See the C<EXAMPLES> section for samples of how to use this function.

=cut

sub get_reply {