.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Query 3pm" .TH Query 3pm "2016-01-08" "perl v5.22.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Term::Query \- Table\-driven query routine. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .ie n .IP """use \f(CBTerm::Query\f(CW""" 17 .el .IP "\f(CWuse \f(CBTerm::Query\f(CW\fR" 17 .IX Item "use Term::Query" \&\f(CW\*(C`qw( \f(CBquery\f(CW \f(CBquery_table\f(CW \f(CBquery_table_set_defaults\f(CW \f(CBquery_table_process\f(CW );\*(C'\fR .PP \&\f(CW\*(C`$result = \f(CBquery\f(CW $\f(CIprompt\f(CW, $\f(CIflags\f(CW, [ $\f(CIoptional_args\f(CW ];\*(C'\fR .PP \&\f(CW\*(C`$\f(CIok\f(CW = \f(CBquery_table\f(CW \e@\f(CIarray\f(CW;\*(C'\fR .PP \&\f(CW\*(C`\f(CBquery_table_set_defaults\f(CW \e@\f(CIarray\f(CW;\*(C'\fR .PP \&\f(CW\*(C`$\f(CIok\f(CW = \f(CBquery_table_process\f(CW \e@\f(CIarray\f(CW, \e&flagsub, \e&querysub;\*(C'\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" .SS "\fBquery\fP" .IX Subsection "query" The \fBquery\fR subroutine fulfills the need for a generalized question-response subroutine, with programmatic defaulting, validation, condition and error checking. .PP Given \fI\f(CI$prompt\fI\fR and \fI\f(CI$flags\fI\fR, and possibly additional arguments, depending upon the characters in \fI\f(CI$flags\fI\fR, \fBquery\fR issues a prompt to \&\s-1STDOUT\s0 and solicits input from \s-1STDIN. \s0 The input is validated against a set of test criteria as configured by the characters in \fI\f(CI$flags\fI\fR; if any of the tests fail, an error message is noted, and the query is reattempted. .PP When \s-1STDIN\s0 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 \&\f(CW$Foce_Interactive\fR as below: .PP .Vb 1 \& $Term::Query::Force_Interactive = 1; .Ve .PP When \f(CW$Force_Interactive\fR is a non-null, non-zero value, \fBquery\fR will issue prompts, error messages, and ask for additional input even when the input is not interactive. .SS "\fBquery_table\fP" .IX Subsection "query_table" The \fBquery_table\fR subroutine performs multiple queries, by invoking \&\fBquery\fR, setting associated variables with the results of each query. Prompts, flags, and other arguments for each query are given in an array, called a \fIquery table\fR, which is passed to the \fBquery_table\fR subroutine by reference. .SS "\fBquery_table_set_defaults\fP" .IX Subsection "query_table_set_defaults" The \fBquery_table_set_defaults\fR subroutine causes any variables named in the given \fIquery table\fR array to be assigned their corresponding default values, if any. This is a non-interactive subroutine. .SS "\fBquery_table_process\fP" .IX Subsection "query_table_process" A general interface to processing a \fIquery table\fR is available with the \&\fBquery_table_process\fR subroutine. It accepts a \fIquery table\fR array, and two subroutine references, a \fI&flagsub\fR and a \fI&querysub\fR. The \&\fI&flagsub\fR is invoked on each each \fIflag\fR character given in the \&\fI\f(CI$flags\fI\fR argument of the \fIquery table\fR (see below). The \fI&querysub\fR is invoked for each query in the \fIquery table\fR. .PP The \fBquery_table\fR and \fBquery_table_set_defaults\fR subroutines both use \&\fBquery_table_process\fR to perform their functions. .SS "\fIQuery Table\fP" .IX Subsection "Query Table" The format of the \fIquery table\fR array passed to \fBquery_table\fR, \&\fBquery_table_set_defaults\fR, and \fBquery_table_process\fR subroutines is: .PP .Vb 4 \& @array = ( $prompt1, $flags1, [ $arglist1, ... ], \& $prompt2, $flags2, [ $arglist2, ... ], \& ... \& $promptN, $flagsN, [ $arglistN, ... ] ); .Ve .PP In English, there are three items per query: a \fIprompt\fR string, a \&\fIflags\fR string, and an array of arguments. Note that the syntax used above uses \f(CW\*(C`[ ... ]\*(C'\fR 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. .PP 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 \fBquery_table_set_defaults\fR subroutine performs the former, while \fBquery_table\fR does the latter. .SS "Flag Characters" .IX Subsection "Flag Characters" With typical usage, given \fI\f(CI$prompt\fI\fR and \fI\f(CI$flags\fI\fR, \fBquery\fR prints \&\fI\f(CI$prompt\fI\fR and then waits for input from the user. The handling of the response depends upon the flag characters given in the \fI\f(CI$flags\fI\fR string. .PP 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 \fBquery\fR subroutine be given. The arguments must be given in the same order as their corresponding flag characters. .PP The ordering of the flags in the \fI\f(CI$flags\fI\fR argument is important \*(-- it determines the ordering of the tests. For example, if both the \fBa\fR and \&\fBm\fR flags are given as \f(CW"am"\fR, then this indicates that an \fIafter\fR subroutine call should be performed first, followed by a regular expression \fImatch\fR test. .PP All tests are applied in the order given in the \fI\f(CI$flags\fI\fR 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 \fBI\fR flag. .SS "Flag Characters Without Arguments" .IX Subsection "Flag Characters Without Arguments" .IP "\fBi\fR" 5 .IX Item "i" The input must be an integer. .IP "\fBn\fR" 5 .IX Item "n" The input must be a number, real or integer. .IP "\fBY\fR" 5 .IX Item "Y" The input is a \f(CW"yes"\fR or \f(CW"no"\fR, with a default answer of \f(CW"yes"\fR. .IP "\fBN\fR" 5 .IX Item "N" The input is a \f(CW"yes"\fR or \f(CW"no"\fR, with a default answer of \f(CW"no"\fR. .IP "\fBr\fR" 5 .IX Item "r" Some input is \fIrequired\fR; an empty response will be refused. This option is only meaningful when there is no default input (see the \fBd\fR flag character below). .IP "\fBs\fR" 5 .IX Item "s" Strip and squeeze the input. Leading and trailing blanks are eliminated, and embedded whitespace is \*(L"squeezed\*(R" to single blank characters. This flag is implied by the \fBk\fR and \fBK\fR flags. .IP "\fBH\fR" 5 .IX Item "H" Do not treat input of \fB?\fR as a request for help. This disables automatic help, unless implemented with the \fIafter\fR (\fBa\fR flag) subroutine. .SS "Flag Characters With Arguments" .IX Subsection "Flag Characters With Arguments" The following flag characters indicate the presence of an argument to \&\fBquery\fR. The arguments must occur in the same order as their corresponding flag characters. For example, if both the \fBV\fR and \fBh\fR flags are given as \f(CW"Vh"\fR, then the first argument must be the variable name, and the next the help string, in that order. .IP "\fBa\fR \fI\e&after\fR" 5 .IX Item "a &after" The next argument is the \fIafter\fR subroutine, to be invoked after the input has been solicited. This feature provides for an \*(L"open ended\*(R" input validation, completely at the control of the user of the Query module. The \fIafter\fR subroutine is invoked in this manner: .Sp .Vb 1 \& &$after( \e$input ); .Ve .Sp If the \fIafter\fR sub returns an \f(CW\*(C`undef\*(C'\fR, then query processing stops with an immediate \f(CW\*(C`undef\*(C'\fR return value. .Sp If the \fIafter\fR sub returns a null or zero value, then the input is rejected and resolicted. No error messages are displayed except the \&\*(L"Please try again.\*(R" message. .Sp Since the \fIafter\fR sub has the reference to the \fI\f(CI$input\fI\fR variable, it is free to change the value of input indirectly; ie: .Sp .Vb 1 \& $$input = $some_new_value; .Ve .IP "\fBb\fR \fI\e&before\fR" 5 .IX Item "b &before" The next argument is the \fIbefore\fR subroutine, to be invoked before any input is attempted. If the \fIbefore\fR 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. .Sp This feature, used in a \fIquery table\fR, allows for selective queries to be programmed by using \fIbefore\fR subs on the optional queries. For example, using the following anonymous sub as the \fBb\fR flag argument: .Sp .Vb 1 \& sub { $> == 0; } .Ve .Sp will cause the corresponding query to only be issued for the \f(CW\*(C`root\*(C'\fR user. .Sp The ordering of the \fBb\fR flag in the \fI\f(CI$flags\fI\fR argument is unimportant, since, by definition, this test is always performed before attempting any input. .ie n .IP "\fBd\fR \fI\fI$default\fI\fR" 5 .el .IP "\fBd\fR \fI\f(CI$default\fI\fR" 5 .IX Item "d $default" The next argument is the \fIdefault\fR 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). .ie n .IP "\fBh\fR \fI\fI$help_string\fI\fR" 5 .el .IP "\fBh\fR \fI\f(CI$help_string\fI\fR" 5 .IX Item "h $help_string" The next argument is the \fIhelp string\fR, which is printed in response to an input of "\fB?\fR". In order to enter a \fB?\fR as actual text, it must be prefixed with a backslash: \*(L"\e\*(R". .IP "\fBk\fR \fI\e@array\fR" 5 .IX Item "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 \&\fBs\fR flag. .Sp The matching can be made case-sensitive by setting the following variable prior to the invocation of \fBquery\fR: .Sp .Vb 1 \& $Query::Case_sensitive = 1; .Ve .Sp By default, this variable is null. .IP "\fBK\fR \fI\e@array\fR" 5 .IX Item "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 \fBs\fR flag. .Sp The \fBk\fR option is useful for soliciting new, unique keywords to a growing list. Adding new fields to a database, for example. .Sp The matching can be made case-sensitive by setting the \&\f(CW$Query::Case_sensitive\fR variable (see above). .ie n .IP "\fBl\fR \fI\fI$maxlen\fI\fR" 5 .el .IP "\fBl\fR \fI\f(CI$maxlen\fI\fR" 5 .IX Item "l $maxlen" The next argument specifies the maximum length of the input. .ie n .IP "\fBm\fR \fI\fI$regular_expression\fI\fR" 5 .el .IP "\fBm\fR \fI\f(CI$regular_expression\fI\fR" 5 .IX Item "m $regular_expression" The next argument specifies a regular expression pattern against which the input will be matched. .ie n .IP "\fBI\fR \fI\fI$reference\fI\fR" 5 .el .IP "\fBI\fR \fI\f(CI$reference\fI\fR" 5 .IX Item "I $reference" The next argument is the input: either a simple scalar value, or a \&\fIreference\fR to a value, such as a \f(CW\*(C`SCALAR\*(C'\fR variable reference (eg: \&\f(CW\*(C`\e$somevar\*(C'\fR), or a \f(CW\*(C`CODE\*(C'\fR reference (eg: \f(CW\*(C`sub {..}\*(C'\fR). In any case, the resulting value is used as input instead of reading from \s-1STDIN.\s0 .Sp If the input returned by the reference does not match other constraints, additional input is not attempted. An error message is noted, and an \&\f(CW\*(C`undef\*(C'\fR return is taken. .Sp This option is handy for applications which have already acquired the input, and wish to use the validation features of \f(CW\*(C`query\*(C'\fR. .Sp It is also useful to embed a query definition in a \fIquery table\fR which does not actually perform a query, but instead does a variable assignment dynamically, using the \fBI\fR reference value. .ie n .IP "\fBJ\fR \fI\fI$reference\fI\fR" 5 .el .IP "\fBJ\fR \fI\f(CI$reference\fI\fR" 5 .IX Item "J $reference" The next argument is the input \fIreference\fR, as with the \fBI\fR flag, except that if the input fails any of the constraints, additional input is solicited from the input. In other words, the \fBJ\fR flag sets a \&\fIone-time\fR only input reference. Think of it as \fIjumping\fR into the query loop with an initial input. .IP "\fBV\fR \fIvariable_name_or_ref\fR" 5 .IX Item "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 \&\fBquery_table\fR in order to retain to the values resulting from each query. .Sp The value can either be a string representing the variable name, or a reference to a variable, eg: \f(CW\*(C`\e$some_var\*(C'\fR. .SS "Details" .IX Subsection "Details" The query processing proceeds basically in the same order as defined by the \fIflags\fR argument, with some exceptions. For example, the \fIbefore\fR subroutine is always performed prior to input. .PP There are implicit precedences in the ordering of some of the \fIflag\fR 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 \fBk\fR flag and an \fBs\fR 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 \fBs\fR flag has precedence over the \fBk\fR flag. If the user supplies the \fIflags\fR string as \f(CW"ks"\fR, the effective ordering would still be \f(CW"sk"\fR. .PP The table below indicates the precedences of the flag tests: .PP .Vb 12 \& 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) .Ve .PP 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 \fIflags\fR argument. .PP Excepting the precedences above, query processing proceeds generally as described below. .IP "\(bu" 5 If the \fBb\fR flag was given, the \*(L"before\*(R" subroutine is invoked as a \&\*(L"pre-input\*(R" test. If the sub returns a 0, empty string, or undef, the query is abandoned. Otherwise, processing continues. .IP "\(bu" 5 If the \fBI\fR or \fBJ\fR flags were given, then input is obtained, without prompting, from the associated reference. If the reference type is \&\f(CW\*(C`CODE\*(C'\fR, 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 \fBJ\fR flag test is only done once, on the first entry into the input loop. .IP "\(bu" 5 In the absence either the \fBI\fR or \fBJ\fR flags, \f(CW\*(C`query\*(C'\fR will issue the given prompt and obtain input from \s-1STDIN. \s0 If an \s-1EOF\s0 occurs, an \f(CW\*(C`undef\*(C'\fR value will result. .IP "\(bu" 5 The input is examined for \*(L"null\*(R" input (that is, the empty string), and processing quits in this case. Since most input is obtained from \&\s-1STDIN,\s0 a null input indicates an end-of-file (\s-1EOF\s0). 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 \&\s-1EOF.\s0 .IP "\(bu" 5 If the \fBs\fR, \fBk\fR, or \fBK\fR flags were given, the input is trimmed of leading and trailing blanks, and all whitespace is \*(L"squeezed\*(R" to single blanks. .IP "\(bu" 5 If the input is an empty response, and there is a \fIdefault\fR input (\fBd\fR flag), use it instead. .IP "\(bu" 5 Unless the \fBH\fR flag is given, if the input is the character "\fB?\fR" with nothing else, then print some helpful information. If the user had supplied a \fIhelp string\fR, it is printed, otherwise the message: .Sp You are being asked "\fI\f(CI$prompt\fI\fR" .Sp 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. .IP "\(bu" 5 If input is \fIrequired\fR (indicated by the \fBr\fR flag), and if the input is empty, produce an error message, and query again. .IP "\(bu" 5 If there was a \fBa\fR flag, the corresponding \fIafter\fR 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 \fIafter\fR subroutine to display any appropriate error messages. .IP "\(bu" 5 If the query was flagged \fBY\fR or \fBN\fR, match the input against the pattern: .Sp .Vb 1 \& /^(y(es?)?|no?)$/i .Ve .Sp If the match fails, print an error message, and query again. When the match succeeds, replace the input with the complete word \f(CW"yes"\fR or \&\f(CW"no"\fR; .IP "\(bu" 5 If an integer response is required (\fBi\fR flagged), check for integer input. If not, print an error, and query again. A successful integer input is returned. .IP "\(bu" 5 If a numeric response is required (\fBn\fR flagged), check for proper numeric input (either integer or real format). Errors produce a warning, and another query. .IP "\(bu" 5 If the query was given a \fIkeyword\fR table (flagged with \fBk\fR), 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. .Sp The matching is case-insensitive or not, according to the value of the variable \f(CW$Query::Case_sensitive\fR, which is nil, by default. The variable may be set by the user to change the matching from case-insensitive to case-sensitive. .IP "\(bu" 5 If the query was given an unacceptable keyword list (flagged with \fBK\fR), the input is compared against the unacceptable keywords. If it matches any keywords exactly, an error is noted, and the query is performed again. .Sp The matching is case-insensitive by default. Set the variable \&\f(CW$Query::Case_sensitive\fR to a non-null, non-zero value to make the keyword matching case-sensitive. .IP "\(bu" 5 If the query was \fBm\fR 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. .IP "\(bu" 5 If the query was \fBl\fR 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. .IP "\(bu" 5 If the query has a variable defined with the \fBV\fR flag, the variable is assigned the input string. This is always done last, after and only if all tests are successful. .Sp If the variable is a string name and not qualified with a package name (ie: \f(CW$foo::variable\fR), then the variable is qualified at the level outside of the Query.pm module. .IP "\(bu" 5 Finally, having passed whatever conditions were flagged, the input is returned to the user. .SH "EXAMPLE" .IX Header "EXAMPLE" The following are typical usage samples: .IP "\(bu" 5 To perform a simple \*(L"yes\*(R" or \*(L"no\*(R" query, with \*(L"no\*(R" as the default answer: .Sp .Vb 1 \& $ans = &query("Do you wish to quit? (yn)",\*(AqN\*(Aq); .Ve .IP "\(bu" 5 An equivalent alternative is: .Sp .Vb 1 \& query "Do you wish to quit? (yn)", \*(AqNV\*(Aq, \e$ans; .Ve .IP "\(bu" 5 To perform the same query, with some supplied helpful information: .Sp .Vb 5 \& $ans = &query("Do you wish to quit? (yn)",\*(AqNh\*(Aq,<<\*(AqEOF\*(Aq); \& 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 .Ve .IP "\(bu" 5 To solicit an integer input: .Sp .Vb 4 \& $mode = &query("Please enter the file mode:",\*(Aqidh\*(Aq,\*(Aq644\*(Aq,<<\*(AqEOF\*(Aq); \& 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 .Ve .IP "\(bu" 5 To solicit one of several keywords: .Sp .Vb 2 \& @keys = split(\*(Aq \*(Aq,\*(AqSGI DEC IBM Sun HP Apple\*(Aq); \& $vendor = &query(\*(AqPlease enter a vendor:\*(Aq,\*(Aqrkd\*(Aq,\e@keys,\*(AqSGI\*(Aq); .Ve .IP "\(bu" 5 To solicit a new, unique keyword to be used as a database field name, with a regexp pattern to check it against: .Sp .Vb 2 \& @fields = split(\*(Aq \*(Aq,\*(AqIndex Vendor Title\*(Aq); # existing fields \& $newfield = &query(\*(AqNew field name:\*(Aq,\*(AqrKm\*(Aq,\e@fields,\*(Aq^\ew+$\*(Aq); .Ve .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" .IP "\fB\s-1COLUMNS\s0\fR" 5 .IX Item "COLUMNS" This variable is used to control the width of output when listing the keyword arrays. If not defined, 80 is used by default. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" .IP "\fBCarp.pm\fR" 5 .IX Item "Carp.pm" Used to produce usage error messages. .IP "\fBArray::PrintCols::print_cols\fR" 5 .IX Item "Array::PrintCols::print_cols" Used to produce displays of the keyword arrays. .SH "FILES" .IX Header "FILES" None. .SH "AUTHOR" .IX Header "AUTHOR" Copyright (C) 1995 Alan K. Stebbens .PP This program is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE. \s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA 02139, USA.\s0 .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" .IP " Input is required." 5 .IX Item " Input is required." Issued when an empty response is given, and there is no default input. .IP " Please answer with 'yes' or 'no', or enter '?' for help." 5 .IX Item " Please answer with 'yes' or 'no', or enter '?' for help." Issued for \fBY\fR or \fBN\fR flagged queries, and the input is not reconizeable. .IP " Please enter an integer number." 5 .IX Item " Please enter an integer number." Printed when non-integer input is given for \fBi\fR flagged queries. .IP " Please enter a number, real or integer." 5 .IX Item " Please enter a number, real or integer." Printed when non-numeric input is given for \fBn\fR flagged queries. .ie n .IP " The input '\fI\fI$input\fI\fR' is ambiguous; it matches the following:" 5 .el .IP " The input '\fI\f(CI$input\fI\fR' is ambiguous; it matches the following:" 5 .IX Item " The input '$input' is ambiguous; it matches the following:" Issued in response to \fBk\fR flagged queries with input which matches more than one of the allowed keywords. .ie n .IP " The input '\fI\fI$input\fI\fR' fails to match any of the allowed keywords:" 5 .el .IP " The input '\fI\f(CI$input\fI\fR' fails to match any of the allowed keywords:" 5 .IX Item " The input '$input' fails to match any of the allowed keywords:" Printed when input to a \fBk\fR flagged query does not match any of the keywords. .IP " The input '%s' matches a disallowed keyword '%s'." 5 .IX Item " The input '%s' matches a disallowed keyword '%s'." Printed when the input matches one of the unacceptable keywords given on a \fBK\fR flagged query. .IP " '%s' fails to match '%s'" 5 .IX Item " '%s' fails to match '%s'" This results from input failing to match the regular expression given on a \fBm\fR flagged query. .ie n .IP " Input is %d characters too long; cannot exceed %d characters." 5 .el .IP " Input is \f(CW%d\fR characters too long; cannot exceed \f(CW%d\fR characters." 5 .IX Item " Input is %d characters too long; cannot exceed %d characters." The length of the input exceeded the maximum length given with the \fBl\fR flag argument. .IP " Please try again, or enter '?' for help." 5 .IX Item " Please try again, or enter '?' for help." .PD 0 .IP " query: The k flag needs an array reference." 5 .IX Item " query: The k flag needs an array reference." .PD The next argument in the argument list to \fBquery\fR wasn't an array reference. .IP " query: The K flag needs an array reference." 5 .IX Item " query: The K flag needs an array reference." The next argument in the argumentlist to \fBquery\fR wasn't an array reference. .SH "BUGS" .IX Header "BUGS"