Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Query(3)	      User Contributed Perl Documentation	      Query(3)

NAME
       Term::Query - Table-driven query	routine.

SYNOPSIS
       "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;"

DESCRIPTION
   query
       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.

   query_table
       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.

   query_table_set_defaults
       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.

   query_table_process
       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.

   Query Table
       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.

   Flag	Characters
       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.

   Flag	Characters Without Arguments
       i    The	input must be an integer.

       n    The	input must be a	number,	real or	integer.

       Y    The	input is a "yes" or "no", with a default answer	of "yes".

       N    The	input is a "yes" or "no", with a default answer	of "no".

       r    Some input is required; an empty response will be refused.	This
	    option is only meaningful when there is no default input (see the
	    d flag character below).

       s    Strip and squeeze the input.  Leading and trailing blanks are
	    eliminated,	and embedded whitespace	is "squeezed" to single	blank
	    characters.	 This flag is implied by the k and K flags.

       H    Do not treat input of ? as a request for help.  This disables
	    automatic help, unless implemented with the	after (a flag)
	    subroutine.

   Flag	Characters With	Arguments
       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.

       a \_after
	    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;

       b \_before
	    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.

       d $default
	    The	next argument is the default input.  This string is used
	    instead of an empty	response from the user.	 The default value can
	    be a scalar	value, a reference to a	scalar value, or a reference
	    to a subroutine, which will	be invoked for its result only if a
	    default value is needed (no	input is given).

       h $help_string
	    The	next argument is the help string, which	is printed in response
	    to an input	of "?".	 In order to enter a ? as actual text, it must
	    be prefixed	with a backslash: "\".

       k \@array
	    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.

       K \@array
	    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).

       l $maxlen
	    The	next argument specifies	the maximum length of the input.

       m $regular_expression
	    The	next argument specifies	a regular expression pattern against
	    which the input will be matched.

       I $reference
	    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.

       J $reference
	    The	next argument is the input reference, as with the I flag,
	    except that	if the input fails any of the constraints, additional
	    input is solicited from the	input.	In other words,	the J flag
	    sets a one-time only input reference.  Think of it as jumping into
	    the	query loop with	an initial input.

       V variable_name_or_ref
	    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".

   Details
       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.

       o    If the b flag was given, the "before" subroutine is	invoked	as a
	    "pre-input"	test.  If the sub returns a 0, empty string, or	undef,
	    the	query is abandoned.  Otherwise,	processing continues.

       o    If the I or	J flags	were given, then input is obtained, without
	    prompting, from the	associated reference.  If the reference	type
	    is "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.

       o    In the absence either the I	or J flags, "query" will issue the
	    given prompt and obtain input from STDIN.  If an EOF occurs, an
	    "undef" value will result.

       o    The	input is examined for "null" input (that is, the empty
	    string), and processing quits in this case.	 Since most input is
	    obtained from STDIN, a null	input indicates	an end-of-file (EOF).
	    If the input is not	null, a	terminating newline is removed,	and
	    the	input testing continues.  At this point, an empty input	string
	    does not indicate an EOF.

       o    If the s, k, or K flags were given,	the input is trimmed of
	    leading and	trailing blanks, and all whitespace is "squeezed" to
	    single blanks.

       o    If the input is an empty response, and there is a default input (d
	    flag), use it instead.

       o    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.

       o    If input is	required (indicated by the r flag), and	if the input
	    is empty, produce an error message,	and query again.

       o    If there was a a flag, the corresponding after subroutine is
	    invoked with the input reference as	its argument.  If the
	    subroutine returns a non-null, non-zero value, the input succeeds,
	    otherwise it fails.	 It is up to the after subroutine to display
	    any	appropriate error messages.

       o    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";

       o    If an integer response is required (i flagged), check for integer
	    input.  If not, print an error, and	query again.  A	successful
	    integer input is returned.

       o    If a numeric response is required (n flagged), check for proper
	    numeric input (either integer or real format).  Errors produce a
	    warning, and another query.

       o    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.

       o    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.

       o    If the query was m flagged with a Perl regular expression pattern,
	    then the input is matched against the pattern.  Failures are noted
	    with an error message, and the query reattempted.

       o    If the query was l flagged with a maximum input length, the	length
	    of the input is checked against the	maximum.  A length violation
	    is noted with an error message and the user	is queried again.

       o    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.

       o    Finally, having passed whatever conditions were flagged, the input
	    is returned	to the user.

EXAMPLE
       The following are typical usage samples:

       o    To perform a simple	"yes" or "no" query, with "no" as the default
	    answer:

	     $ans = &query("Do you wish	to quit? (yn)",'N');

       o    An equivalent alternative is:

		query "Do you wish to quit? (yn)", 'NV', \$ans;

       o    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

       o    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

       o    To solicit one of several keywords:

	     @keys = split(' ','SGI DEC	IBM Sun	HP Apple');
	     $vendor = &query('Please enter a vendor:','rkd',\@keys,'SGI');

       o    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+$');

ENVIRONMENT
       COLUMNS
	    This variable is used to control the width of output when listing
	    the	keyword	arrays.	 If not	defined, 80 is used by default.

DEPENDENCIES
       Carp.pm
	    Used to produce usage error	messages.

       Array::PrintCols::print_cols
	    Used to produce displays of	the keyword arrays.

FILES
       None.

AUTHOR
       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.

DIAGNOSTICS
	Input is required.
	    Issued when	an empty response is given, and	there is no default
	    input.

	Please answer with 'yes' or 'no', or enter '?' for help.
	    Issued for Y or N flagged queries, and the input is	not
	    reconizeable.

	Please enter an	integer	number.
	    Printed when non-integer input is given for	i flagged queries.

	Please enter a number, real or integer.
	    Printed when non-numeric input is given for	n flagged queries.

	The input '$input' is ambiguous; it matches the	following:
	    Issued in response to k flagged queries with input which matches
	    more than one of the allowed keywords.

	The input '$input' fails to match any of the allowed keywords:
	    Printed when input to a k flagged query does not match any of the
	    keywords.

	The input '%s' matches a disallowed keyword '%s'.
	    Printed when the input matches one of the unacceptable keywords
	    given on a K flagged query.

	'%s' fails to match '%s'
	    This results from input failing to match the regular expression
	    given on a m flagged query.

	Input is %d characters too long; cannot	exceed %d characters.
	    The	length of the input exceeded the maximum length	given with the
	    l flag argument.

	Please try again, or enter '?' for help.
	query: The k flag needs	an array reference.
	    The	next argument in the argument list to query wasn't an array
	    reference.

	query: The K flag needs	an array reference.
	    The	next argument in the argumentlist to query wasn't an array
	    reference.

BUGS
POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 1353:
	   You forgot a	'=back'	before '=head1'

perl v5.24.1			  1996-10-22			      Query(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | ENVIRONMENT | DEPENDENCIES | FILES | AUTHOR | DIAGNOSTICS | BUGS | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Term::Query&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help