Term::Query - Table-driven query routine.
use Term::Query
qw( query query_table query_table_set_defaults query_table_process );
$result = query $prompt, $flags, [ $optional_args ];
$ok = query_table \@array;
query_table_set_defaults \@array;
$ok = query_table_process \@array, \&flagsub, \&querysub;
The query subroutine fulfills the need for a generalized question-response subroutine, with programmatic defaulting, validation, condition and error checking.
Given $prompt and $flags, and possibly additional arguments, depending upon the characters in $flags, query issues a prompt to STDOUT and solicits input from STDIN. The input is validated against a set of test criteria as configured by the characters in $flags; if any of the tests fail, an error message is noted, and the query is reattempted.
When STDIN is not a tty (not interactive), prompts are not issued, and
errors cause a return rather than attempting to obtain more input.
This non-interactive behaviour can be disabled by setting the variable
$Foce_Interactive as below:
$Term::Query::Force_Interactive = 1;
When $Force_Interactive is a non-null, non-zero value, query
will issue prompts, error messages, and ask for additional input
even when the input is not interactive.
The query_table subroutine performs multiple queries, by invoking query, setting associated variables with the results of each query. Prompts, flags, and other arguments for each query are given in an array, called a query table, which is passed to the query_table subroutine by reference.
The query_table_set_defaults subroutine causes any variables named in the given query table array to be assigned their corresponding default values, if any. This is a non-interactive subroutine.
A general interface to processing a query table is available with the query_table_process subroutine. It accepts a query table array, and two subroutine references, a &flagsub and a &querysub. The &flagsub is invoked on each each flag character given in the $flags argument of the query table (see below). The &querysub is invoked for each query in the query table.
The query_table and query_table_set_defaults subroutines both use query_table_process to perform their functions.
The format of the query table array passed to query_table, query_table_set_defaults, and query_table_process subroutines is:
@array = ( $prompt1, $flags1, [ $arglist1, ... ],
$prompt2, $flags2, [ $arglist2, ... ],
...
$promptN, $flagsN, [ $arglistN, ... ] );
In English, there are three items per query: a prompt string, a
flags string, and an array of arguments. Note that the syntax used
above uses [ ... ] to denote a Perl 5 anonymous array, not an
optional set of arguments. Of course, if there are no arguments for a
particular query, the corresponding anonymous array can be the null
string or zero.
The query table design is such that a query table can be created with a set of variables, their defaults, value constraints, and help strings, and it can be used to both initialize the variables' values and to interactively set their new values. The query_table_set_defaults subroutine performs the former, while query_table does the latter.
With typical usage, given $prompt and $flags, query prints $prompt and then waits for input from the user. The handling of the response depends upon the flag characters given in the $flags string.
The flag characters indicate the type of input, how to process it, acceptable values, etc. Some flags simply indicate the type or processing of the input, and do not require additional arguments. Other flags require that subsequent arguments to the query subroutine be given. The arguments must be given in the same order as their corresponding flag characters.
The ordering of the flags in the $flags argument is important -- it
determines the ordering of the tests. For example, if both the a and
m flags are given as "am", then this indicates that an after
subroutine call should be performed first, followed by a regular
expression match test.
All tests are applied in the order given in the $flags until a particular test fails. When a test fails, an error message is generated and the input is reattempted, except in the case of the I flag.
"yes" or "no", with a default answer of "yes".
"yes" or "no", with a default answer of "no".
The following flag characters indicate the presence of an argument to
query. The arguments must occur in the same order as their
corresponding flag characters. For example, if both the V and h
flags are given as "Vh", then the first argument must be the
variable name, and the next the help string, in that order.
The next argument is the after subroutine, to be invoked after the input has been solicited. This feature provides for an "open ended" input validation, completely at the control of the user of the Query module. The after subroutine is invoked in this manner:
&$after( \$input );
If the after sub returns an undef, then query processing stops
with an immediate undef return value.
If the after sub returns a null or zero value, then the input is rejected and resolicted. No error messages are displayed except the "Please try again." message.
Since the after sub has the reference to the $input variable, it is free to change the value of input indirectly; ie:
$$input = $some_new_value;
The next argument is the before subroutine, to be invoked before any input is attempted. If the before sub returns a non-null, non-zero value, the current query will be attempted. If a null or zero value is returned, the current query will be abandoned, with a null return.
This feature, used in a query table, allows for selective queries to be programmed by using before subs on the optional queries. For example, using the following anonymous sub as the b flag argument:
sub { $> == 0; }
will cause the corresponding query to only be issued for the root
user.
The ordering of the b flag in the $flags argument is unimportant, since, by definition, this test is always performed before attempting any input.
The next argument is a reference to an array of allowable keywords. The input is matched against the array elements in a case-insensitive manner, with unambiguous abbreviations allowed. This flag implies the s flag.
The matching can be made case-sensitive by setting the following variable prior to the invocation of query:
$Query::Case_sensitive = 1;
By default, this variable is null.
The next argument is a reference to an array of disallowed keywords In this case, for the input to be unacceptable, it must match exactly, case-insensitive, one of the array elements. This flag implies the s flag.
The k option is useful for soliciting new, unique keywords to a growing list. Adding new fields to a database, for example.
The matching can be made case-sensitive by setting the
$Query::Case_sensitive variable (see above).
The next argument is the input: either a simple scalar value, or a
reference to a value, such as a SCALAR variable reference (eg:
\$somevar), or a CODE reference (eg: sub {..}). In any case,
the resulting value is used as input instead of reading from STDIN.
If the input returned by the reference does not match other constraints,
additional input is not attempted. An error message is noted, and an
undef return is taken.
This option is handy for applications which have already acquired the
input, and wish to use the validation features of query.
It is also useful to embed a query definition in a query table which does not actually perform a query, but instead does a variable assignment dynamically, using the I reference value.
The next argument is the variable name or reference to receive the validated input as its value. This option, and its corresponding variable name, would normally be present on all entries used with query_table in order to retain to the values resulting from each query.
The value can either be a string representing the variable name, or
a reference to a variable, eg: \$some_var.
The query processing proceeds basically in the same order as defined by the flags argument, with some exceptions. For example, the before subroutine is always performed prior to input.
There are implicit precedences in the ordering of some of the flag
tests. Generally, flags have their corresponding tests performed in
the same order as the given flags. Some flag tests, however, require
that other flags' tests be performed beforehand in order to be
effective. For example, when given the k flag and an s flag,
stripping the input would only be effective if the strip were done on
the input before testing the input against the keyword table. In other
words, the s flag has precedence over the k flag. If the user
supplies the flags string as "ks", the effective ordering would
still be "sk".
The table below indicates the precedences of the flag tests:
Given Flag Flags With Higher Precedence ========== ================================ i (int) s (strip), d (default), h (help) k (key) s (strip), d (default), h (help) K (nonkey) s (strip), d (default), h (help) l (maxlen) d (default), h (help) m (match) d (default), h (help) n (numeric) s (strip), d (default), h (help) N (no) s (strip), d (default), h (help) r (required) d (default), h (help) s (strip) d (default), h (help) Y (yes) s (strip), d (default), h (help)
Except for the implied precedence indicated in the table above, the ordering of the flag tests proceeds in the same order as given in the flags argument.
Excepting the precedences above, query processing proceeds generally as described below.
CODE, then it is invoked and the resulting return value is used as
the input. Otherwise the reference is evaluated in a scalar context and
used as the input. The J flag test is only done once, on the first
entry into the input loop.
query will issue the
given prompt and obtain input from STDIN. If an EOF occurs, an undef
value will result.
Unless the H flag is given, if the input is the character "?" with nothing else, then print some helpful information. If the user had supplied a help string, it is printed, otherwise the message:
You are being asked "$prompt"
is displayed. Also, some information about the expected response, according to any given flag characters, is displayed. Finally, the user is returned to the prompt, and given another opportunity to enter a response.
If the query was flagged Y or N, match the input against the pattern:
/^(y(es?)?|no?)$/i
If the match fails, print an error message, and query again. When the
match succeeds, replace the input with the complete word "yes" or
"no";
If the query was given a keyword table (flagged with k), the input is matched against the allowable keyword list. If an exact match is found, the keyword is returned as the input. Failing an exact match, an abbreviation search is performed against the keywords. If a single match is found, it is returned as the input. If no match is found, an error message is produced, and the user is returned to the query to try again. Otherwise, the input was ambiguous, an error noted showing the matches, and the user is queried again.
The matching is case-insensitive or not, according to the value of the
variable $Query::Case_sensitive, which is nil, by default. The
variable may be set by the user to change the matching from
case-insensitive to case-sensitive.
If the query was given an unacceptable keyword list (flagged with K), the input is compared against the unacceptable keywords. If it matches any keywords exactly, an error is noted, and the query is performed again.
The matching is case-insensitive by default. Set the variable
$Query::Case_sensitive to a non-null, non-zero value to make the
keyword matching case-sensitive.
If the query has a variable defined with the V flag, the variable is assigned the input string. This is always done last, after and only if all tests are successful.
If the variable is a string name and not qualified with a package name
(ie: $foo::variable), then the variable is qualified at the level
outside of the Query.pm module.
The following are typical usage samples:
To perform a simple "yes" or "no" query, with "no" as the default answer:
$ans = &query("Do you wish to quit? (yn)",'N');
An equivalent alternative is:
query "Do you wish to quit? (yn)", 'NV', \$ans;
To perform the same query, with some supplied helpful information:
$ans = &query("Do you wish to quit? (yn)",'Nh',<<'EOF');
You are being asked if you wish to quit. If you answer "yes",
then all changes will be lost. An answer of "no", will allow
you to return to continue making changes.
EOF
To solicit an integer input:
$mode = &query("Please enter the file mode:",'idh','644',<<'EOF');
Please enter the 3 digit numeric file mode; if you are unsure
of how the file mode is used, please see the man page for "chmod".
EOF
To solicit one of several keywords:
@keys = split(' ','SGI DEC IBM Sun HP Apple');
$vendor = &query('Please enter a vendor:','rkd',\@keys,'SGI');
To solicit a new, unique keyword to be used as a database field name, with a regexp pattern to check it against:
@fields = split(' ','Index Vendor Title'); # existing fields
$newfield = &query('New field name:','rKm',\@fields,'^\w+$');
None.
Copyright (C) 1995 Alan K. Stebbens <aks@hub.ucsb.edu>
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
The next argument in the argumentlist to query wasn't an array reference.