This is the README file ($Revision: 1.2 $) for Term::Query.pm.
Term::Query.pm is a Perl 5 module, which performs generalized queries on
various kinds of values. Validation and normalization of input, based
on the type, is automated, as is error reporting and re-solicitation of
input.
Input of '?', unless configured otherwise, provides useful, helpful
information, based on the expected input type, even in the absence of a
programmer-supplied help string.
There is one primary subroutine, called "query", which is passed a
prompt and some "flags", optionally followed by addtional arguments,
depending upon the particular flags.
The flags are single characters which indicate:
* input type: integer, real, string, yes-no, keyword, or
non-keyword;
* default input, in the absence of user input;
* help string, to be reported for errors or input of '?';
* input validation, such as regexp matching, maximum length, and
"check" subroutine calls;
* input handling, such as blank squeezing, and "before" subroutine
calls.
* name of the variable to be set with the validated input.
An accompanying subroutine, query_table, can be passed an array of of
arguments which will be interatively passed to query, allowing for easy
generation of table-driven query-response input routines.
The subroutine query_table_set_defaults can be used on a query table
array to cause any mentioned variables to be initialized with any
mentioned default values. This is handy for having a single table
defining variables, their default values, and the validation criteria
for setting new values.
The subroutine query_table_process can be used on a query table array to
process the array in a complete general fashion.
Complete details are provided within the module, in the Perl 5 "pod"
format. Traditional man pages are available with the command:
pod2man Query.pm | nroff -man -
The code was developed and requires Perl5.001m (eg: it uses references),
Carp.pm (it diagnoses some misuse of itself) and the PrintArray.pm
module (by the same author).
There is a Makefile with several useful targets for installing at one or
more common locations; there is a "test" target which will perform
regression tests against previous "good" output (see the "t" directory).
WARNING: The "make test" is currently under development, and does not work.
The Query.pm module does work as advertised (except for unreported bugs :^)
The Query.pm archive is available under the GNU General License,
Version 2, and is located at:
http://reality.sgi.com:80/aks/depot/perl/term/Term-Query-2.0.tar.gz
as well as your favorite CPAN site (see "http://www.perl.com/CPAN").
Suggestions or improvements are welcome.
Copyright (C) 1995-1997 Alan K. Stebbens
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.
___________________________________________________________
Alan Stebbens http://reality.sgi.com/aks