CleanCode Perl Libraries

Perl

Java

JavaScript

Certified
Class

Testable
Class

Standalone
Mode

Diagnostic
Enabled

NAME
SYNOPSIS
REQUIRES
DESCRIPTION
- Note on Plugins
CONSTRUCTOR
METHODS
BUGS
AUTHOR
VERSION
SINCE
SEE ALSO
POD ERRORS

NAME

CGI::PageValidator::CheckItem - Check validity of a single input item.

SYNOPSIS

  use CGI::PageValidator::CheckItem;
  
  # prep
  CGI::PageValidator::CheckItem->reset();
  CGI::PageValidator::CheckItem->setLibMgr($libMgr);
  . . .
  # build library
  $checkItem = CGI::PageValidator::CheckItem->new($elem, $replaced);
  . . .
  # validate with library
  $checkItem->doValidate($val, $depValue);
  . . .
  # report results
  $errList = CGI::PageValidator::CheckItem->getErrList();

REQUIRES

Perl5.005, Data::Handy, Data::Diagnostic, CGI::PageValidator::Plugin

DESCRIPTION

This module examines a single input value against the appropriate library entry, performing a series of standard tests plus an optional customized test (via a plugin). The standard tests (tested in this order) are:

Is the field empty/not empty when required to be?
Is the input contained in an explicit enumeration of allowed values?
Is the length of the input within set bounds?
Is the numerical value of the input within set bounds?
Does the input match a regular expression for the field?

If you use a plugin, it may alter the requirements for the other tests, or it may perform a test of its own.

Any validation violations are added to the class error list which may be retrieved via the getErrList method. These violations may be reported either as a message describing the violation (the default), or just the field name which had the violation. This style is controlled via the setNamesOnly method.

The public interface to this class is detailed below. However, if you are using the basic CGI::PageValidator system, you do not need to invoke those; they are invoked from within the CGI::PageValidator::LibraryMgr class.

Note on Plugins

The whole point of plugins is that they are not called directly, but rather dynamically according to your configuration. This is done by specifying the particular plugin name as the value of the plugin property to a CheckItem object. The CheckItem object, then, will assign this to a variable named $plugin, load the plugin class, create a plugin object, and invoke the examine method defined in this class. Both the class loading and the object creation are performed safely, i.e. any exceptions will be caught rather than cause an abnormal termination. The code fragment below shows how these steps are done in this class.

        $loadError = loadClass($plugin);
        eval { $pluginObj = $plugin->new(
                $this, $this->{dependsOn}, $fieldValue, $depValue, $pluginPkg); };
        $pluginObj->examine();
        $errMsg = $pluginObj->getResult();

CONSTRUCTOR

new

PACKAGE->new(hashRef, replaced)

Creates a CheckItem object, a definition for a validating a single entity based on a collection of facets in the hashRef.

Parameters:

hashRef - reference to has containing validation facets

replaced - boolean; indicates this definition replaces a previous one for the same named entity. This is used only for diagnostic purposes in reporting about the library.

Returns:

a newly created object

METHODS

reset

PACKAGE->reset()

Resets collected list of errors to empty.

getErrList

PACKAGE->getErrList()

Returns collected list of errors.

Returns:: Array reference to list of collected errors.

setNamesOnly

PACKAGE->setNamesOnly(boolValue)

Sets error collection style when a violation is detected. Errors may be reported either as the field name only (true) or as a message describing the violation (the default).

Parameters:: boolValue - boolean; indicates to use names only or not.

setLibMgr

PACKAGE->setLibMgr(libraryManager)

Specifies the "parent" library manager which is manipulating a series of CheckItem objects (needed for dependency processing). This is needed only for two specialized purposes:

(1) To be able to lookup dependent objects to determine whether they are secure or not, and then mask these secure values (e.g. credit card numbers). If this method is not used, dependent values will be displayed unmasked without regard to security.

(2) To specify a non-default package for plugin libraries, which is determined by calling the getPluginPkg of the library manager.

Parameters:: libraryManager - LibraryMgr parent object

copy

OBJ->copy()

Create a shallow copy of the CheckItem object invoking this method. That is, only the first level of items is replicated; any references below that are references to the original.

Returns:: CheckItem object that is a shallow copy of the original.

getNameAndValue

OBJ->getNameAndValue(value)

Returns the object's display name with the normalized value specified. The format is "name (value)". If the object does not have a display name, the field name itself is used. If the object is defined as a secure entity (e.g. for credit card numbers, etc.) the value is masked. This method provides a convenience for uniform name/value appearance, so its use is encouraged in any plugins, etc.

Parameters:: value - string; value to possibly mask and display.
Returns:: Display string with name and value.

getGroupNameAndValue

OBJ->getGroupNameAndValue(value)

Returns the object's display group name with the normalized value specified. The format is "name (value)". If the object does not have a display group name, the display name for the object itself is examined. If the object does not have a display name, the field name is used. If the object is defined as a secure entity (e.g. for credit card numbers, etc.) the value is masked.

A display group name is a collective name for several fields, e.g. area code and phone number, two separate fields, together could be labelled as "telephone" when displaying the information. Similarly, city, state, and zip might be labelled as "post office".

Parameters:: value - string; value to possibly mask and display.
Returns:: Display string with group name and value.

getSecureValue

OBJ->getSecureValue(value)

Normalizes the specified value in the sense of masking it if the object is defined as a secure entity. Otherwise the value is returned unchanged.

Parameters:: value - string; value to mask, if appropriate.
Returns:: Secure (i.e. masked) value if object is defined as a secure entity; plain value otherwise.

doValidate

OBJ->doValidate(fieldValue, depValue)

Validate the specified value using the facets of this CheckItem object. When the value fails a criterium, an error message (or just the field name) is added to the class-common error list. The first failure stops further checking, so no more than one error per field will appear on the error list.

The set of tests is listed, in order, in the introduction section of this page. The only item not listed there is the special case of plugin validation. Using a plugin allows you to connect this CheckItem object with other CheckItem objects semantically. So, for example, you could create a plugin to check a credit card expiration date where the month value and the year value are in separate fields. See the Plugin class for details on how to hookup and use plugins.

Parameters:

fieldValue - string; value to validate.

depValue - string or array reference of strings, which must match the defined dependencies for this entity (dependsOn property). That is, if the entity depends on exactly one other entity, then depValue must be a single string. If the entity depends on multiple other entites, depValue must be an array reference.

BUGS

None

AUTHOR

Michael Sorens

VERSION

$Revision: 8 $ $Date: 2006-12-19 21:13:43 -0800 (Tue, 19 Dec 2006) $

SINCE

CleanCode 0.9

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 212:: =back doesn't take any parameters, but you said =back -- end of CONSTRUCTOR section
Around line 562:: =back doesn't take any parameters, but you said =back -- end of METHODS section

Home