HTMLObject::ErrorBase(3)

NAME
ErrorBase - the HTMLObject::ErrorBase class.

SYNOPSIS
 The HTMLObject::ErrorBase module provides the core error handling
 data structures and methods for the HTMLObject modules.

 Currently only the Form and Widgets modules are using this code.

EXAMPLE
 use HTMLObject::ErrorBase;

 @ISA = qw(HTMLObject::ErrorBase);

 sub new
 {
   my $class = shift;
   my $self = $class->SUPER::new(@_);

   # build up anything specific to your class.

   return $self;
 }

DESCRIPTION
ErrorBase is the HTMLObject::ErrorBase class that provides the core error structures to keep track of valid, invalid, missing, unknown entries and to query wether or not an entry is invalid, etc.

Exported FUNCTIONS
NOTE: bool = 1(true), 0(false)

scalar new()
    Creates a new instance of the HTMLObject::ErrorBase object.

    requires:

    returns: object reference

    Variables:

     error       - bool

     errorString - scalar

     _errors_    - hash contains the following error hashes:
                     missing,
                     invalid,
                     valid,
                     unknown,
                     extraInfo - holds extra info about an entry
                       in the missing or invalid hashes.

     errorPhrase - Contains string
       '() - Error!<br />\n'

     missingArguemnt - Contains string
       '<b>%s</b> is missing!<br />\n'

     invalidArgument - Contains string
       '<b>%s</b> = '%s' is invalid!<br />\n'

bool isValid(void)
     Returns true or false to indicate if the object is valid.
     The error will be available via errorMessage().

bool error(errorString)
     This method will set the error condition if an argument is
     specified.

     The current error state is returned, regardless of if we are
     setting an error or not.

     A \n is appended to the errorString so you don't have to provide it.
     errorString is prefixed with the caller's full method name followed
     by the errorPhrase string.

     You can either specify the errorString value by name:

     $self->error(errorString => "This is an error!");

     or by value:

     $self->error("This is an error!");

     If you specify multiple arguments (in pass by value mode), then
     we check to see if the first argument contains %'s that are not
     \ escaped and are not %%.  If this is the case, then the incoming
     arguments will be passed through sprintf() for formatting, else we
     just join them with a space ' ' and append them to the current
     errorString.

     To see if an error happened:

     if ($self->error) { die "Error: " . $self->errorMessage; }

void setError(errorString)
     DEPRECATED: see error()

     optional: errorString
     returns: nothing
     Sets error = 1 and errorString = string passed in.
     The errorString is prefixed with the caller's full
     method name followed by the errorPhrase string.

     You can either call as
     setError(errorString => $string)
     or setError($string)

     If you do not specify anything, we blow an error
     telling you to specify errorString.

     \n is appended to the contents of the errorString
     passed in.

void prefixError(errorString)
     optional: errorString
     returns: nothing
     Sets error = 1 and prefixes errorString with string passed in.
     The errorString is prefixed with the caller's full
     method name followed by the errorPhrase string.

     You can either specify the errorString value by name:

     $self->prefixError(errorString => "This is an error!");

     or by value:

     $self->prefixError("This is an error!");

     If you specify multiple arguments (in pass by value mode), then
     we check to see if the first argument contains %'s that are not
     \ escaped and are not %%.  If this is the case, then the incoming
     arguments will be passed through sprintf() for formatting, else we
     just join them with a space ' ' and append them to the current
     errorString.

     If you don't specify anything then
       If you have a previous error, we prefix the caller info to
         that error message.

void postfixError(errorString)
     DEPRECATED: see error()

     optional: errorString
     returns: nothing
     Sets error = 1 and postfixes errorString with string passed in.
     The errorString is prefixed with the caller's full
     method name followed by the errorPhrase string.

     You can either call as
     postfixError(errorString => $string)
     or postfixError($string)

     If you don't specify anything then we call setError and
       inform you that you need to specify the errorString value.

scalar didErrorOccur(void)
     DEPRECATED: see error()

     Returns the value of error.

scalar errorMessage(void)
     Returns the value of errorString.

scalar errorStr(void)
     Returns the value of errorString.

     Alternative to errorMessage().

void resetError(void)
     Resets the error condition flag and string.

void missing(name, extraInfo)
     Adds an entry for name to the missing hash.
     If you specify another value, it will be stored
     as extra info about why this is missing.

     Ex:  $self->missing("langObj");
     would signal that langObj was not found.

     $self->missing("langObj", "this is a test.");
     would signal that langObj was not found and that
     you wanted to tell the user that "this is a test.".

void valid(name, value)
     Adds an entry for name with it's value to the valid hash.

     Ex: $self->valid("name", "John Doe");
     would signal that name was found and specify the value we got.

void invalid(name, value, extraInfo)
     Adds an entry for name with it's value in the invalid hash so you
     know it was invalid and what the user specified.
     If extraInfo is specified, then it is tacked on after the value
     part is displayed so you can inform the user of extra conditions
     about why this was invalid.

     Ex: $self->invalid("name", "");
     would signal that name was found but it was invalid and the value
     the user sent us.

     $self->invalid("name", "1", "names can not start with digits.");
     would signal that name = '1' was invalid and then let you give the
     user more feedback as to why "names can not start with digits."

void unknown(name, value)
     Adds an entry for name with it's value in the unknown hash so you
     know it was specified but the calling program didn't know how to
     handle it.

     Ex: $self->unknown("123num", "xdy391234ksldfj.askj28095;");

% or @ getMissing(void)
     Returns the hash of name entries that were required but not found
     or the array of name entries if in list context.

% or @ getInvalid(void)
     Returns the hash of name, value pairs that were found to be invalid
     or the array of name entries if in list context.

% or @ getValid(void)
     Returns the hash of name, value pairs that were found to be valid
     or the array of name entries if in list context.

% or @ getUnknown(void)
     Returns the hash of name, value pairs that were found to be unknown
     or the array of name entries if in list context.

scalar getMissingEntry(entry)
     Returns the value from the missing hash associated with entry.

scalar getInvalidEntry(entry)
     Returns the value from the invalid hash associated with entry.

scalar getValidEntry(entry)
     Returns the value from the valid hash associated with entry.

scalar getUnknownEntry(entry)
     Returns the value from the unknown hash associated with entry.

scalar getExtraInfoEntry(entry)
     returns the entry from the extraInfo hash for the specified entry.

scalar genErrorString(type)
     Generates the Error String for the specified type.

     type = missing, invalid, all

     When type = all, then we generate first the missing then the
     invalid error strings.

     type = missing uses the missingArgument language phrase.

     type = invalid uses the invalidArgument language phrase.

     Ex:  $self->error($self->genErrorString("missing"));

bool isEntryMissing(name)
     Returns true if name is found in the missing hash, else false.

bool isEntryInvalid(name)
     Returns true if name is found in the invalid hash, else false.

bool isEntryValid(name)
     Returns true if name is found in the valid hash, else false.

bool isEntryUnknown(name)
     Returns true if name is found in the unknown hash, else false.

void clearErrors(type)
     Empties the specified error hash.

     type can be all, missing, invalid, valid, unknown

     When type = all, then we clear all the hashes, otherwise we just
     clear the specified hash.

     Ex:  $self->clearErrors("missing");
     would clear just the missing entries.

void deleteErrorsEntry(type, entry)
     (this method just shifts the input, so you do not
     have to name your arguments)

     Returns the value of the specified entry from the
     specified errors hash and then deletes the entry.
     Returns undef if the entry does not exist.

     type can be missing, invalid, valid, unknown

     Ex:  $self->deleteErrorsEntry("valid", "fname");
     would return the value fname from the valid data
     structure and then delete it.

     This method is mainly for the Validation code that
     needs to move entries from the valid hash to the
     invalid hash to make the user deal with the entry.

scalar numMissing(void)
     Returns the number of entries that were required but not found.

scalar numInvalid(void)
     Returns the number of entries that were found to be invalid.

scalar numValid(void)
     Returns the number of entries that were found to be valid.

scalar numUnknown(void)
     Returns the number of entries that were found to be unknown.

% extract(args)
     Takes a string of comma seperated arguments that are taken
     from the current object and inserted into a hash.

     Returns the hash of arguments capable of being passed to
     a new method.

     Ex:

     my %args = $self->extract("langObj, applicationObj");

     Would return a hash containing the langObj and applicationObj
     variables from the current object.

NOTE
 All data fields are accessible by specifying the object
 and pointing to the data member to be modified on the
 left-hand side of the assignment.
 Ex.  $obj->variable($newValue); or $value = $obj->variable;

 This module based off of the Portal::Base module.

AUTHOR
James A. Pattie (mailto:james@pcxperience.com)

SEE ALSO
perl(1), HTMLObject::Base(3), HTMLObject::Normal(3), HTMLObject::Template(3), HTMLObject::Form(3)