CleanCode Perl Libraries

Perl

Java

JavaScript

Certified
Class

Testable
Class

Standalone
Mode

Diagnostic
Enabled

NAME
SYNOPSIS
REQUIRES
DESCRIPTION
CONSTRUCTOR
METHODS
BUGS
AUTHOR
VERSION
SINCE
SEE ALSO
POD ERRORS

NAME

CGI::PageValidator::LibraryMgr - Manages validation library.

SYNOPSIS

  use CGI::PageValidator::LibraryMgr;
  $libMgr = CGI::PageValidator::LibraryMgr->new($settings);
  if ($libMgr->success()) {
          CGI::PageValidator::CheckItem->reset();
          CGI::PageValidator::CheckItem->setLibMgr($libMgr);
      . . .
      while (. . .) {
          $libItem = $libMgr->getItem($itemName);
          if (defined ($libItem)) {
              $libItem->doValidate(. . .);
          . . .
      }
      $errList = CGI::PageValidator::CheckItem->getErrList();
  }

REQUIRES

Perl5.005, Data::Handy, Data::Diagnostic, Data::InputOptions, CGI::PageValidator::CheckItem, Convert::SimpleJs2Perl

DESCRIPTION

This module reads the system library (SysLib) followed by the user library (UserLib) files, and creates a dynamic structure of CheckItem objects. See UserLib for details of field definitions which may be used in the library. Once the library is created, some consistency checks are performed, which will catch some developer-introduced errors:

verify dependency links to other library elements;
verify min value constraint is not greater than max value constraint;
verify min length constraint is not greater than max length constraint;
report probable typographic mistakes as identified by two or more elements differing in case only.

Library Conversion

This validation library is available for both front-end use (in a client browser) and back-end use (such as this program). In order to have only a single library used by both either client or server, the validation library is written in JavaScript so it may be directly attached to a web page like any other code file. For back-end use, the library is converted on-the-fly to Perl, and then used.

Thus, in this module, the first step is to translate any required Javascript files. (Note that you don't have to maintain the javascript files if you're not using the javascript half of the system.) There are two standard libraries: SysLib and UserLib.

SysLib is intended for system administrator use only, and is geared to contain universal elements, in a sense. UserLib, on the other hand, is intended to be customized to a particular use. These two standard libraries are mapped into a single Perl package, specified in the list of properties passed to the constructor ($settings).

  LIB_PKG specifies the package for standard libraries SysLib and UserLib
  (Default="CGI::PageValidator::MainLib")

There may also be additional library files needed by various plugins. By naming these in the config file, they will also be converted as needed.

  PLUGIN_DATA_LIBS specifies a list of data libraries for plugins
  (Default=none)

This list should be simple names, not full file paths. So, for example, the .../Plugin/CCLib.pm library for credit card validation is listed as just "CCLib". All plugin data libraries are mapped into a single Perl package.

  PLUGIN_PKG specifies the package for plugin libraries
  (Default="CGI::PageValidator::PluginLib")

Both standard libraries and plugin libraries must be located on both the javascript side and the Perl side for the conversion to proceed.

  PMPATH specifies a path to the Perl root.
  (Default=".")
  JSPATH specifies a path to the javascript root.
  (Default="../js")

So, for example, let JSPATH="../js", PMPATH=".", and LIB_PKG="Val::Lib"; then the SysLib library module will be retrieved from ../js/Val/Lib/SysLib.js and the converted module will be stored at ./Val/Lib/SysLib.pm.

Library Construction

Once the library is available in Perl, the dynamic library structure is then built from the translated files, and stored in the LibraryMgr object as a series of CheckItem objects.

Each library definition may be self-contained or it may extend another definition. This allows leveraging existing definitions for more complex ones. An example might be a basic definition for "state", which can then be extended for a US state, Australian state, or others. For each definition which does extend another, it is expanded into a separate, complete copy when the library is loaded. That way any changes that need to be definition-specific will not have unintended side effects.

Library Usage

Once the object initialization is complete, retrieve a CheckItem object from the library by name, then invoke the doValidate method of each CheckItem object. This populates a list of validation violations which may then be accessed via the static getErrList method of the CheckItem class. See the Synopsis above for a typical sequence.

CONSTRUCTOR

new

PACKAGE->new(settings)

Creates a LibraryMgr object. Converts SysLib and (UserLib from JavaScript to Perl, then builds a dynamic library of CheckItem objects.

Parameters:: settings - InputOptions object; allows configuration via these properties: PLUGIN_DATA_LIBS, LIB_PKG, PLUGIN_PKG, PMPATH, and JSPATH.
Returns:: a newly created object

METHODS

success

OBJ->success()

Indicates whether the library was constructed without error.

Returns:: boolean indicating whether library construction was successful.

getItem

OBJ->getItem(itemName)

Retrieve the CheckItem object for the specified item.

Parameters:: itemName - string; name of item to retrieve.
Returns:: a CheckItem object for the specified name, or undef if not defined.

getPluginPkg

OBJ->getPluginPkg()

This method should be considered package-level access, not public access. Retrieves the name of the package where plugins are stored.

Returns:: Package where plugins are stored.

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 267:: =back doesn't take any parameters, but you said =back -- end of CONSTRUCTOR section
Around line 391:: =back doesn't take any parameters, but you said =back -- end of METHODS section

CleanCode Perl Libraries