String::Checker - An extensible string validation module (allowing commonly used checks on strings to be called more concisely and consistently).
use String::Checker; String::Checker::register_check($checkname, \&sub); $return = String::Checker::checkstring($string, [ expectation, ... ]);
This is a very simple library for checking a string against a given set of expectations. It contains a number of pre-defined expectations which can be used, and can also be extended to perform any arbitrary match or modification on 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 input parameters) against a set of expectations, this comes in pretty handy. As a matter of fact, the CGI::ArgChecker module is a simple, CGI.pm aware wrapper for this library.
The checkstring function takes a string scalar and a reference to a list of 'expectations' as arguments, and outputs a reference to a list, containing the names of the expectations which failed.
Each expectation, in turn, can either be a string scalar (the name of the expectation) or a two-element array reference (the first element being the name of the expectation, and second element being the argument to that expectation.) 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.
The module predefines a number of checks. They are:
Never fails - will convert an undef scalar to an empty string, though.
Fails if the input string is either undef or empty.
Fails if the length of the input string is less than the numeric value of it's single argument.
Fails if the length of the input string is more than the numeric value of it's single argument.
Fails if the input string does not solely consist of numeric characters.
Fails if the argument does not solely consist of numeric characters, plus an optional single '.'.
Fails if the input string contains characters other than those in its argument.
Fails if the input string contains any of the characters in its argument.
Never fails - converts the string to upper case.
Never fails - converts the string to lower case.
Never fails - strips leading and trailing whitespace from the string.
Fails if the input string does not precisely match at least one of the elements of the array reference it takes as an argument.
Fails if the input string does not match the regular expression it takes as an argument.
Fails if the input string does not match the regular expression: ^\S+\@@[\w-]+\.[\w\.-]+$
Fails if the input string does not match the regular expression ^[0-9+.()-]*$
Interprets the input string as a date, if possible. This will fail if it can't figure out a date from the input. In addition, it is possible to use this to standardize date input. Pass a formatting string (see the strftime(3) man page) as an argument to this check, and the string will be formatted appropriately if possible. This is based on the Date::Manip(1) module, so that documentation might prove valuable if you're using this check.
Use register_check to register a new expectation checking routine. This function 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 be a reference to the input string (the function is free to modify the value of the string). The second argument, if any, is the second element of a two-part expectation, whatever that might be.
The function should return undef unless there's a problem, in which case it should return 1. It's also best (if possible) to return undef if the string is undef, so that the user can decide whether to allow_empty or disallow_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; };
Hopefully none.
J. David Lowe, dlowe@webjuice.com
perl(1), CGI::ArgChecker(1)
To install String::Checker, copy and paste the appropriate command in to your terminal.
cpanm
cpanm String::Checker
CPAN shell
perl -MCPAN -e shell install String::Checker
For more information on module installation, please visit the detailed CPAN module installation guide.