NAME

ASCOPE::Term - Aaron's widget for doing things on the command line.


SUMMARY

 my $term = ASCOPE::Term->new();
 if ($term->ask_yesno("Do something")) {
    my $answer = $term->choose_from_list("Choose me",\@options);
 }


DESCRIPTION

This is Aaron's widget for doing things on the command line. While it is true that the world really doesn't need anymore terminal thingies, apparently I do.

It is really just a wrapper/helper module for a variety of Term::* modules with an interface that I like.

For the time being I will probably not send this package to the CPAN. If people want me to, I will reconsider.


PACKAGE METHODS

$pkg = __PACKAGE__->new()

Returns an object. Woot!


OBJECT METHODS

$pkg->ask($question,$default)

Returns user input for $question.

$self->ask_yesno($question)

Returns true is answer begins with a ``y'' or equals ``1'', otherwise returns false.

$pkg->ask_exists($question, $default)

Requires the user to return *something*.

$pkg->ask_defined($question,$default)

Requires the user to return something that's been defined (translation: 0 may not pass a boolean test, but it *is* defined).

$self->ask_match($question,$default,$pattern)

Require the user to return something that matches $pattern.

$pkg->ask_integer($question,$default)

Prompt the user to return an integer.

Return the int if they do or undef otherwise.

$pkg->ask_float($question,$default)

Prompt the user to return an floating point number.

Return the floatif they do or undef otherwise.

$pkg->ask_password($username)

Prompts the user for a password and uses the Term::ReadKey package to hide user input.

Returns the password.

$pkg->ask_date(\@date)

Prompt the use for a valid date.

Returns an array reference containing YYYY,MM,DD

The return value for this method may change in subsequent releases.

$pkg->ask_date_span(\@start,\@end)

Prompt the use for two valid dates. Make sure that dates are chronological

Returns an array reference containing YYYY-MM-DD, YYYY-MM-DD

The return value for this method may change in subsequent releases

$pkg->ask_money_figure($amount,$currency,\@valid_currencies)

Prompt the user for a money amount and a currency.

If no list of valid currencies is provided the user will br prompted to provide one.

Returns an array reference containing the amount followed by the currency.

$pkg->choose_one($label,\@choices)

Prompt the user to choose one item from a set list.

Lists with eleven, or more, items are presented ten at a time along with the following options when applicable:

For example :

 213 ->perl -I./lib ./t/005-choose_many.t
 +------------------------------------+
 | 1 - 10 of 11 possible choices      |
 +------------------------------------+
 | * cow                              |
 | * dog                              |
 | * cat                              |
 | * bird                             |
 | * apple                            |
 | * boo                              |
 | * poo                              |
 | * zoo                              |
 | * hump                             |
 | * bump                             |
 +------------------------------------+
 | >> next // done \\ cancel || show  |
 +------------------------------------+
 [choose]

The method uses the Term::Complete package in an effort to minimize unnecessary typing.

Returns a string.

$pkg->choose_many($label,\@choices)

Prompt the user to choose one or more items from a set list.

See docs for $pkg->choose_one() for details.

Returns an array reference.

$pkg->take_note(\$note)

Prompt the user for a note -- anything that spans multiple lines -- or edit an existing one.

The following characters, followed by a new line, are treated as ``special'' :

When the user passes an existing note, it is split on newlines and each is passed to the user for editing.

Returns a string

$self->ask_getopts(\%opts,@order)

Prompt the user for bunch of stuff using Getopt::Long.

$opts is the associative array.

The key is expected to use the same format that the Getopt::Long::GetOptions manpage uses for keys.

The value for the key is an array reference whose values are :

If @order is not defined, then the user will be prompted for each key in $opts alphabetically.

Example:

 my %opts = (
             "username"  => "bob",
             "email"     => undef,
            );
 $term->ask_getopts({
                     "username=s" => [ \$opts{'username'}],
                     "email=s" => [
                                    \$opts{'email'},
                                    "email address",
                                    sub { return \"$opts{'username'}\@bob.com"; },
                                  ],
                                 "username","email",
                                });
 # would produce:
 asc @ localhost in /home/asc/bin/perl/debug
 122 ->./term-ref
 username?  [bob] asc
 email address? [asc@bob.com] 
 $VAR1 = {
           'email' => 'asc@bob.com',
           'username' => 'asc',
         };

This method still isn't very smart about lists.


VERSION

0.2


DATE

$Date: 2003/06/23 12:51:05 $


AUTHOR

Aaron Straup Cope


REQUIREMENTS

the Term::Prompt manpage

the Term::ANSIColor manpage

the Term::ReadKey manpage

the Term::Complete manpage

the Date::Calc manpage

Memoize


BUGS

This release works much better in an Emacs shell than earlier versions however there are still bugs. It basically doesn't work at all in eshell mode.


LICENSE

Copyright (c) 2001-2003, Aaron Straup Cope. All Rights Reserved.

This is free software, you may use it and distribute it under the same terms as Perl itself.