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)