Term::Interact - Interactively Get Validated Data
use Term::Interact;
my $ti = Term::Interact->new( @args );
# get validated data interactively $validated_data = $ti->get( @args );
# check existing data non-interactively die "Invalid!" unless $ti->validate( $data, @args );
Term::Interact enables you to interactively get validated data from a user. This is accomplished via a simple API, wherein you specify various parameters for prompting the user, as well as "checks" with which gotten data will be validated.
# set up object with some optional parameters my $ti = Term::Interact->new(
# set desired date formatting behavior # (See perldoc Date::Manip for syntax) date_format_display => '%d-%b-%Y', date_format_return => '%s',
# database handle (see perldoc DBI) to # allow sql_checks. dbh => $dbh, );
my $num1 = $ti->get(
msg => 'Enter a single digit number.',
prompt => 'Go ahead, make my day: ',
re_prompt => 'Try Again Here: ',
check => [
qr/^\d$/,
'%s is not a single digit number!'
],
);
#
# Resulting Interaction looks like:
#
# Enter a single digit number.
# Go ahead, make my day: w
# 'w' is not a single digit number!
# Try Again Here: 23
# '23' is not a single digit number!
# Try Again Here: 2
my $date = $ti->get (
type => 'date',
name => 'Date from 2001',
confirm => 1,
check => [
['<= 12-31-2001', '%s is not %s.'],
['>= 01/01/2001', '%s is not %s.'],
]
);
#
# Resulting Interaction looks like:
#
# Date from 2001: Enter a value.
# > 2002-03-12
# You entered: '12-Mar-2002'. Is this correct? (Y|n)
# '12-Mar-2002' is not <= 31-Dec-2001.
# > foo
# 'foo' is not a valid date
# > 2000-12-31
# You entered: '31-Dec-2000'. Is this correct? (Y|n)
# '31-Dec-2000' is not >= 01/01/2001.
# > 2001-02-13
# You entered: '13-Feb-2001'. Is this correct? (Y|n)
my $states_aref = $ti->get (
msg => 'Please enter a comma delimited list of states.',
prompt => 'State: ',
re_prompt => 'Try Again: ',
delimiter => ',',
case => 'uc',
dbh => $dbh,
check => [
'SELECT state FROM states ORDER BY state',
'%s is not a valid state code. Valid codes are: %s'
],
);
#
# Resulting Interaction looks like:
#
# Please enter a comma delimited list of states.
# State: FOO
# 'FOO' is not a valid state code. Valid codes are: AA, AB, AE, AK,
# AL, AP, AQ, AR, AS, AZ, BC, CA, CO, CT, CZ, DC, DE, FL, FM, GA, GU,
# HI, IA, ID, IL, IN, KS, KY, LA, LB, MA, MB, MD, ME, MH, MI, MN, MO,
# MP, MS, MT, NB, NC, ND, NE, NF, NH, NJ, NM, NS, NT, NV, NY, OH, OK,
# ON, OR, PA, PE, PQ, PR, PW, RI, RM, SC, SD, SK, TN, TT, TX, UT, VA,
# VI, VT, WA, WI, WV, WY, YT
# Try Again: az, pa
my $num2 = $ti->get (
name => 'Number Less Than 10 and More than 3',
check => [
[' < 10', '%s is not less than 10.'],
['>3', '%s is not %s.'],
]
);
#
# Resulting Interaction looks like:
#
# Number Less Than 10 and More than 3: Enter a value.
# > f
# 'f' is not numeric.
# > 1
# '1' is not > 3.
# > -1
# '-1' is not > 3.
# > 14
# '14' is not less than 10.
# > 5
my $grades = $ti->get ( name => 'Letter grade', delimiter => ',', check => [ 'A', 'B', 'C', 'D', 'F' ], ); # # Resulting Interaction looks like: # # Letter grade: Enter a value or list of values delimited with commas. # > 1 # > s # > X # > a, b # > A, B, C
# If multiple checks are specified, the ordering # is preserved. In the example below, the sql_check # will be applied before the regex_check. my $foo = $ti->get ( name => $name, delimiter => $delim, check => [ 'SELECT foo FROM bar', qr/aaa|bbb|ccc/ ], );
# multiple requests in one call to get method
my ($foo, $bar) = $ti->get (
[
[
name => 'foo',
check => [qw/ A B C /],
],
# you can use an href if you prefer
{
name => 'bar',
delimiter => ',',
check => qr/kermit|der|frosch/,
},
]
);
new
The new method constructs a Term::Interact object using default values and passed in key=>value parameters (see PARAMETERS section below). The parameter values stored in the object are subsequently accessible for reading and setting via methods named the same as the parameters. For example:
# get the value of the date_format_return parameter
my $fmt = $ti->date_format_return;
# set the value of the date_format_return parameter
# to DD-Mon-YYYY
$ti->date_format_return( '%d-%b-%Y' );
get
get method prompts the user for data and, if a check parameter (see check in the PARAMETERS section below) has been passed in, invokes the validate method to validate the user-provided data.
validate
validate method accepts the data to be validated as its first parameter, and then the same key=>value parameters that new and get accept. One of these parameters needs to be the check parameter so that validation can be performed.
new_check
new_check method uses a check parameter value to construct one or more check objects (which are returned in an aref). You'll not usually invoke this method, because the validate method transparently invokes it to transform its check parameter value into a collection of check objects. (These check objects are what the internal check methods actually use to validate data.) Nonetheless, you may invoke this method if you like. By doing so you could initially set the check parameter to an aref of check objects when invoking get or validate.
parameters
The parameters method returns information about available parameters. If called with no args, it will return a list of available parameter names in list context, or an href of all parameter information in scalar context:
{
interact => {type => 'bool', default => 1 },
name => {type => 'str', } ,
...
check => {type => ['str','aref','qr//','coderef'], }
}
If called with a specific type, ala $ti->parameter(type => 'bool'), a list of parameters matching that type will be returned in list context, or an aref of parameter_name => type pairs will be returnes in scalar context. Also note that not-types are available, ala $ti->parameter(type => '!bool').
If called with the key value pair (default => 1), the method will return a list of parameters that have default values. If called this way in scalar context, the method will return an aref of parameter_name => default_value key value pairs.
All of the parameters are listed below in the PARAMETER section, and are all accessible via self-named mutator/accessor mehods.
These parameters are available for use with new, where they will be stored within the constructed object. They are also available for use with the get and validate methods, where they will override any values stored in the object, but only for the duration of that method call. In other words, the parameter values stored in the object during construction will be temporarilly overriden, but not changed by, any variant parameter values subsequently supplied to get or validate. The parameter values stored in the object may be changed, however, by invoking the self-named method accessor/mutators, ala $ti->timeout( 30 ).
interact
name
type
allow_null
timeout
maxtries
shared_autoformat_args
term_width ]}. The autoformat method from Text::Autoformat is used to format everything printed to FH_OUT. This href will be passed to autoformat every time it is invoked.
menu
msg
succinct
msg_indent
msg_newline
prompt
reprompt
prompt will be used instead.
prompt_indent
case
confirm
echo
echo_quote
delimiter
delimiter_spacing
min_elem
delimiter.
max_elem
delimiter.
unique_elem
delimiter.
default
check_default
date_format_display
type is set to date.
date_format_return
get and validate methods. See Date::Manip's UnixDate function for details. Note this is a meaningful parameter only when used in conjunction if type is set to date.
FH_OUT
FH_IN
term_width
ReadMode
dbh
translate
aref: Translates validated user input into something else. Useful, for example, when you require the user to enter only one character for the sake of convenience, but you really want something more verbose returned. The aref may contain one or more translation rules, each of which is comprised of a check (see below) and a translation string. For example, when calling get with the following, a validated user input of 'p' would be translated into the string 'portrait' before being returned to you:
translate => [
[ 'eq p' => 'portrait' ],
[ 'eq l' => 'landscape' ],
]
check
str, aref, qr//, coderef: This parameter accepts one string, one aref, one compiled regular expression (qr//), or one coderef. With these options you will be able to indicate one or more of the following kinds of checks to be used in validating data, as well as any error message you would like for each of the checks.
CHECK VARIETIES
Term::Interact comes with support for six varieties of check expressions:
SYNTAX
Possible values when specifying a single check:
[ $check_aref, $err_str ]
-or-
[ $check_aref ]
-or-
$check_aref
-or-
[ $check_regex, $err_str ]
-or-
[ $check_regex ]
-or-
$check_regex
-or-
[ $check_str, $err_str ]
-or-
[ $check_str ]
-or-
$check_str
Possible values when specifying multiple checks:
[
[ $check_aref, $err_str ],
[ $check_aref ],
$check_aref,
[ $check_regex, $err_str ],
[ $check_regex ],
$check_regex,
[ $check_str, $err_str ],
[ $check_str ],
$check_str,
]
NOTE
This module steers clear of offering explicit checks like 'phone_number_check' or 'email_address_check'. In the author's opinion one may generally obtain all the convenience and code readability one needs via the built in varieties of checks. However, if you have regular need for an additional check you'll likely want to steer clear of the built in custom_check option (see above). You can more permanently add your own custom checks by subclassing Term::Interact and providing the desired checks as subroutines (all the check subs follow a simple API, just follow the pattern). Additionally you will need to modify the private _classify_check_type function.
Term::Interact by Phil R Lawrence.
Support is available by emailing the author directly: prl ~AT~ cpan ~DOT~ org
The Term::Interact module is Copyright (c) 2002 Phil R Lawrence. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This module was developed while I was in the employ of Lehigh University. They kindly allowed me to have ownership of the work with the understanding that I would release it to open source. :-)
Text::Autoformat, Term::ReadKey, Date::Manip