MAN page from Old RedHat 7.X perl-String-Checker-0.03-8.i386.rpm

Checker

Section: User Contributed Perl Documentation (3)
Updated: perl v5.6.0
Index

NAME

String::Checker - An extensible string validation module (allowingcommonly used checks on strings to be called more concisely andconsistently).

SYNOPSIS

 use String::Checker;

 String::Checker::register_check($checkname, \&sub); $return = String::Checker::checkstring($string, [ expectation, ... ]);

DESCRIPTION

This is a very simple library for checking a string against a given set ofexpectations. It contains a number of pre-defined expectations which can beused, and can also be extended to perform any arbitrary match or modificationon a string.

Why is this useful? If you're only checking one string, it probably isn't.However, if you're checking a bunch of strings (say, for example, CGI inputparameters) against a set of expectations, this comes in pretty handy. Asa matter of fact, the CGI::ArgChecker module is a simple, CGI.pm aware wrapperfor this library.

Checking a string

The checkstring function takes a string scalar and a reference to a list of'expectations' as arguments, and outputs a reference to a list, containingthe names of the expectations which failed.

Each expectation, in turn, can either be a string scalar (the name of theexpectation) or a two-element array reference (the first element being thename of the expectation, and second element being the argument to thatexpectation.) For example:

   $string = "foo";   String::Checker::checkstring($string, [ 'allow_empty',                                           [ 'max' => 20 ] ] );

Note that the expectations are run in order. In the above case, for example,the 'allow_empty' expectation would be checked first, followed by the 'max'expectation with an argument of 20.

Defined checks

The module predefines a number of checks. They are:

allow_empty: Never fails - will convert an undef scalar to an empty string, though.
disallow_empty: Fails if the input string is either undef or empty.
min: Fails if the length of the input string is less than the numeric value ofit's single argument.
max: Fails if the length of the input string is more than the numeric value ofit's single argument.
want_int: Fails if the input string does not solely consist of numeric characters.
want_float: Fails if the argument does not solely consist of numeric characters, plusan optional single '.'.
allow_chars: Fails if the input string contains characters other than those in itsargument.
disallow_chars: Fails if the input string contains any of the characters in its argument.
upcase: Never fails - converts the string to upper case.
downcase: Never fails - converts the string to lower case.
stripxws: Never fails - strips leading and trailing whitespace from the string.
enum: Fails if the input string does not precisely match at least one of theelements of the array reference it takes as an argument.
match: Fails if the input string does not match the regular expression it takesas an argument.
want_email: Fails if the input string does not match the regular expression: ^\S+\@@[\w-]+\.[\w\.-]+$
want_phone: Fails if the input string does not match the regular expression ^[0-9+.()-]*$
want_date: Interprets the input string as a date, if possible. This will fail if it can'tfigure out a date from the input. In addition, it is possible to use this tostandardize date input. Pass a formatting string (see the strftime(3) man page)as an argument to this check, and the string will be formatted appropriatelyif possible. This is based on the Date::Manip(1) module, so that documentationmight prove valuable if you're using this check.

Extension checks

Use register_check to register a new expectation checking routine. Thisfunction should be passed a new expectation name and a code reference.

This code reference will be called every time the expectation name is seen,with either one or two arguments. The first argument will always bea reference to the input string (the function is free to modify the valueof the string). The second argument, if any, is the second element of atwo-part expectation, whatever that might be.

The function should return undef unless there's a problem, in which caseit should return 1. It's also best (if possible) to return undef if thestring is undef, so that the user can decide whether to allow_empty ordisallow_empty independent of your check.

For example, registering a check to verify that the input word is ``poot''would look like:

   String::Checker::register_check("ispoot", sub {       my($s) = shift;       if ((defined($$s)) && ($$s ne 'poot')) {           return 1;       }       return undef;   };

BUGS

Hopefully none.

AUTHOR

J. David Lowe, dloweAATTwebjuice.com

This document was created byman2html,using the manual pages.