GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  STRING::CHECKER (3)

.ds Aq ’

NAME

String::Checker - An extensible string validation module (allowing commonly used checks on strings to be called more concisely and consistently).

CONTENTS

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

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

    Defined checks

The module predefines a number of checks. They are:
<B>allow_emptyB> Never fails - will convert an undef scalar to an empty string, though.
<B>disallow_emptyB> Fails if the input string is either undef or empty.
<B>minB> Fails if the length of the input string is less than the numeric value of it’s single argument.
<B>maxB> Fails if the length of the input string is more than the numeric value of it’s single argument.
<B>want_intB> Fails if the input string does not solely consist of numeric characters.
<B>want_floatB> Fails if the argument does not solely consist of numeric characters, plus an optional single ’.’.
<B>allow_charsB> Fails if the input string contains characters other than those in its argument.
<B>disallow_charsB> Fails if the input string contains any of the characters in its argument.
<B>upcaseB> Never fails - converts the string to upper case.
<B>downcaseB> Never fails - converts the string to lower case.
<B>stripxwsB> Never fails - strips leading and trailing whitespace from the string.
<B>enumB> Fails if the input string does not precisely match at least one of the elements of the array reference it takes as an argument.
<B>matchB> Fails if the input string does not match the regular expression it takes as an argument.
<B>want_emailB> Fails if the input string does not match the regular expression: ^\S+\@@[\w-]+\.[\w\.-]+$
<B>want_phoneB> Fails if the input string does not match the regular expression ^[0-9+.()-]*$
<B>want_dateB> 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.

    Extension checks

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;
   };



BUGS

Hopefully none.

AUTHOR

J. David Lowe, dlowe@webjuice.com

SEE ALSO

perl(1), CGI::ArgChecker(1)
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CHECKER (3) 1999-11-25

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.