NAME

Term::Interact - Get Data Interactively From User

SYNOPSIS

use Term::Interact;

my $ti = Term::Interact->new( @args );

# interactive
$validated_value = $ti->get( @args );

# non interactive
$validated_value = $ti->sql_check( $value, @args );

$validated_value = $ti->list_check( $value, @args );

$validated_value = $ti->regex_check( $value, @args );

$validated_value = $ti->compare_check( $value, @args );

DESCRIPTION

Term::Interact provides a way to interactively get values from the user. It allows date, text and number processing through a simple API.

The new() method constructs an object using default values and passed in parameters. The get() method prompts the user for values and may use one or more check methods to validate the values provided by the user. These check methods are also available for stand alone usage. Check methods include:

sql_check

for checking input against the return value of SQL statements

regex_check

for checking input against reqular expressions

list_check

for checking input against a list of acceptable values

compare_check

for checking that input satisfies one or more comparison expressions

Finally, while this module steers clear of offering explicit checks like 'phone_number_check' or 'email_check', you may certainly add them by subclassing this module and simply providing the desired check as a subroutine. Just follow the pattern of the built in checks in the source code for Term::Interact.

EXAMPLES

# set up object
my $ti = Term::Interact->new(
    date_format => '%d-%b-%Y',
    date_format_return => '%d-%b-%Y'
);

my $num1 = $ti->get(
    msg         => 'Enter a single digit number.',
    prompt      => 'Go ahead, make my day: ',
    re_prompt   => 'Try Again Here: ',
    regex_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,
    compare_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
#    > 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',
    sql_check => [
                   $dbh,
                   [
                     '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',
    compare_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  => ',',
    list_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 if parms are passed as a list or aref.
# In the example below, the sql_check will be applied
#  before the regex_check.
my $foo = $ti->get (
  [
    name        => $name,
    delimiter   => $delim,
    sql_check   => $aref_sql,
    regex_check => $aref_regex,
  ]
);

# If multiple checks are specified, the ordering
#  is *not* preserved if parms are passed as an href
my $foo = $ti->get (
  {
    name        => $name,
    delimiter   => $delim,
    sql_check   => $aref_sql,
    regex_check => $aref_regex,
  }
);

# multiple requests in one call to get method
my ($foo, $bar) = $ti->get (
    [
      [
        name          => 'foo',
        compare_check => [ @check_arefs ],
      ],
      {
        name       => 'bar',
        delimiter  => ',',
        list_check => \@valid_values,
      },
    ]
);

PARAMETERS

These parameters are available for use with new(), where they will be stored within the constructed object. They are also available for use with get() and the check methods, where they will override any values stored in the object, but only for the duration of that method call. The parameter values stored in the object during construction will not be changed by any parameter values subsequently supplied to other methods.

name

str: Used in auto-assembling a message for the user if no msg parameter was specified.

type

str: Currently, the only meaningful value for this parameter is 'date'. If set to date, all input from the user and all check values supplied by the programmer will be parsed as dates by Date::Manip.

allow_null

bool: Defaults to 0. Set to 1 to allow user to enter 'NULL', regardless of any other checking. This is useful for database related prompting.

timeout

num: Defaults to 600 seconds. Set to 0 to turn off the timeout functionality. Timeout results in a fatal error which you may catch as you like. (This option not available under MS Windows.)

maxtries

num: Defaults to 20. Set to 0 turn off the maxtries functionality. Exceeding the maxtries results in a fatal error which you must catch.

msg

str: Message that will print prior to user input prompt. No msg will be printed if defined as 0. If left undefined, a message will be auto-generated.

prompt

str: Defaults to '> '. User will be prompted for input with this string.

reprompt

str: User will be re-prompted for input (as necessary) with this string.

case

str: The case of user input will be adjusted. uc, lc, and ucfirst are available.

confirm

bool: The user will be prompted to confirm the input if set to 1. Defaults to 0.

delimiter

str: Set this parameter to allow the user to enter multiple values via delimitation. Note this is a string value, not a pattern.

delimiter_spacing

str: Defaults to 'auto', whereby one space will be added after each delimiter when prompting the user, and whitespace before and after any delimiters will be discarded when reading user input. Set it to any value other than 'auto' to disable this behavior,

min_elem

num: Set this parameter to require the user to enter a minimum number of values. Note this is a meaningful parameter only when used in conjunction with delimiter.

max_elem

num: Set this parameter to restrict the user to a maximum number of values they can enter. Note this is a meaningful parameter only when used in conjunction with delimiter.

unique_elem

bool: Set this parameter to require all elements of the user-entered delimited value list to be unique. Note this is a meaningful parameter only when used in conjunction with delimiter.

default

str or aref: If the user is permitted to input multiple values (i.e., you have specified a delimiter), you may specify multiple default values by passing them in an aref. Or you may pass in one default value as a string.

date_format

str: This string is used to format dates for diplay. See Date::Manip's UnixDate function for details. Defaults to '%c' if type is set to 'date'.

date_format_return

str: This string is used to format dates returned by Term::Interact methods. See Date::Manip's UnixDate function for details. If no date_format_return is specified, dates will be returned in epoch second format.

FH_OUT

FH: Defaults to STDOUT. This filehandle will be used to print any messages to the user.

FH_IN

FH: Defaults to STDIN. This filehandle will be used to read any input from the user.

term_width

num: Defaults to 72. If the term_width of FH_OUT is less than the default or a value that you provide, the FH_OUT term_width will be used instead.

ReadMode

num: Sets a ReadMode for user prompting. Useful for turning terminal echo off for getting passwords. See Term::ReadKey for details. If set, ReadMode will be reset to 0 after each user input and in END processing.

sql_check

aref: The first element of this aref must be a valid database handle (See DBI for details). Following that may be either SQL statements (one string each) or arefs consisting of one SQL statement and one error message each. User-entered values must be found in the results of every SQL statement provided to be acceptable. Examples:

[ $dbh, 'SELECT zing FROM zap', 'SELECT boo FROM dap' ]

[
  $dbh,
  ['SELECT zing FROM zap', '%s is not a zing!'],
  [
    'SELECT boo FROM dap',
    '%s is not a boo!  Valid boos are %s'
  ]
]

regex_check

qr// or aref: This parameter can be set to a single compiled regex, an aref with one compiled regex and one error message, or an aref with multiple compiled regexes or regex/error arefs. User-entered values must match every regex provided to be acceptable. Examples:

qr/^\d+$/

[ qr/^\d+$/, 'That contained non-digits!' ]

[
  [qr/^\d+/, "%s doesn't start with digits!"],
  qr/foo/
]

list_check

aref: This aref contains legitimate values against which user input will be checked.

compare_check

aref: This aref contains one comparison test, a comparison test and error message, or arefs of comparison tests and error messages. Operators will be split from the front of the comparison tests. All perl operators except <=> and cmp (reasonably) are available. Examples:

[ '>6' ]

[ 'eq boo far', 'You did not say \'boo far\'!' ]

[ '> 6', ' < 11' ] # whitespace around operator is ignored

[
  ['>=6', '%s is not %s!'],
  ['<11', 'That was not less than eleven!'
]

[ ['> 12/31/2015', '%s is not %s!'], '<11' ]

AUTHOR

Term::Interact by Phil R Lawrence.

COPYRIGHT

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.

NOTE

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. :-)

SEE ALSO

Text::Autoformat, Term::ReadKey, Date::Manip