NAME

Base - Base Object the Business::Payroll derives from.

SYNOPSIS

package Business::Payroll::Test;
use Business::Payroll::Base;
use strict;
use vars qw($AUTOLOAD $VERSION @ISA @EXPORT);

require Exporter;

@ISA = qw(Business::Payroll::Base Exporter AutoLoader);
@EXPORT = qw();

$VERSION = '0.01';

sub new
{
  my $class = shift;
  my $self = $class->SUPER::new(@_);
  my %args = ( something => 'Hello World!', @_ );

  if ($self->didErrorOccur)
  {
    $self->prefixError();
    return $self;
  }

  # instantiate anything unique to this module
  $self->{something} = $args{something};

  # do validation
  # The $self->Business::Payroll::Test::isValid makes sure we access our
  # isValid method and not any classes isValid method that has
  # derived from us.
  if (!$self->Business::Payroll::Test::isValid)
  {
    # the error is set in the isValid() method.
    return $self;
  }

  # do anything else you might need to do.
  return $self;
}

sub isValid
{
  my $self = shift;

  # make sure our Parent class is valid.
  if (!$self->SUPER::isValid())
  {
    $self->prefixError();
    return 0;
  }

  # validate our parameters.
  if ($self->{something} !~ /^(.+)$/)
  {
    $self->invalid("something", $self->something);
  }

  if ($self->numInvalid() > 0 || $self->numMissing() > 0)
  {
    $self->postfixError($self->genErrorString("all"));
    return 0;
  }
  return 1;
}

DESCRIPTION

Base is the base Business::Payroll class.

Exported FUNCTIONS

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

scalar new()

Creates a new instance of the Business::Payroll::Base object.

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     - "() - Error!<br>\n"
missingArgument - "%s is missing"
invalidArgument - "%s = '%s' is invalid"

bool isValid(void)

Returns 1 or 0 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("personObj");
would signal that personObj was not found.

$self->missing("personObj", "this is a test.");
would signal that personObj 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 formEncodeString(string)

HTTP Form encodes the string to protect against xss
(cross site scripting) or for embedding in an HTML Form.

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->setError($self->genErrorString("missing"));

bool isEntryMissing(name)

Returns 1 if name is found in the missing hash, else 0.

bool isEntryInvalid(name)

Returns 1 if name is found in the invalid hash, else 0.

bool isEntryValid(name)

Returns 1 if name is found in the valid hash, else 0.

bool isEntryUnknown(name)

Returns 1 if name is found in the unknown hash, else 0.

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.

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("error, errorString");

Would return a hash containing the error and errorString
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;

AUTHOR

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

SEE ALSO

perl(1), Business::Payroll(3)