NAME
CGI::Portable::Errors - Manages error list for operations
DEPENDENCIES
Perl Version
5.004Standard Modules
I<none>Nonstandard Modules
I<none>SYNOPSIS
See CGI::Portable, which is a subclass of this.
DESCRIPTION
This class is designed to be inherited by CGI::Portable and implements some of that module's functionality; however, this class can also be used by itself. The split of functionality between several modules is intended to emphasize the fact that CGI::Portable is doing several tasks in parallel that are related but distinct, so you have more flexability to use what you need and not carry around what you don't use. Each module has the POD for all methods it implements.
This class implements methods that manage an "error list" property, which is designed to accumulate any error strings that should be printed to the program's error log or shown to the user before the program exits. What constitutes an error condition is up to you, but the suggested use is for things that are not the web user's fault, such as problems compiling or calling program modules, or problems using file system files for settings or data. The errors list is not intended to log invalid user input, which would be common activity. Since some errors are non-fatal and other parts of your program would still work, it is possible for several errors to happen in parallel; hence a list. At program start-up this list starts out empty.
An extension to this feature is the concept of "no error" messages (undefined strings) which if used indicate that the last operation *did* work. This gives you the flexability to always record the result of an operation for acting on later. If you use get_error() in a boolean context then it would be true if the last noted operation had an error and false if it didn't. You can also issue an add_no_error() to mask errors that have been dealt with so they don't continue to look unresolved.
SYNTAX
This class does not export any functions or methods, so you need to call them using object notation. This means using Class->function() for functions and $object->method() for methods. If you are inheriting this class for your own modules, then that often means something like $self->method().
CONSTRUCTOR FUNCTIONS AND METHODS AND CONTEXT SWITCHING
These functions and methods are involved in making new CGI::Portable::Errors objects, except the last one which combines two existing ones. All five of them are present in both CGI::Portable and other classes designed to be inherited by it, including this one, because they implement its functionality.
new()
This function creates a new CGI::Portable::Errors (or subclass) object and returns it.
initialize()
This method is used by new() to set the initial properties of objects that it creates.
clone([ CLONE ])
This method initializes a new object to have all of the same properties of the current object and returns it. This new object can be provided in the optional argument CLONE (if CLONE is an object of the same class as the current object); otherwise, a brand new object of the current class is used. Only object properties recognized by CGI::Portable::Errors are set in the clone; other properties are not changed.
make_new_context([ CONTEXT ])
This method initializes a new object of the current class and returns it. This new object has some of the current object's properties, namely the "input" properties, but lacks others, namely the "output" properties; the latter are initialized to default values instead. As with clone(), the new object can be provided in the optional argument CONTEXT (if CONTEXT is an object of the same class); otherwise a brand new object is used. Only properties recognized by CGI::Portable::Errors are set in this object; others are not touched.
take_context_output( CONTEXT[, LEAVE_SCALARS[, REPLACE_LISTS]] )
This method takes another CGI::Portable::Errors (or subclass) object as its CONTEXT argument and copies some of its properties to this object, potentially overwriting any versions already in this object. If CONTEXT is not a valid CGI::Portable::Errors (or subclass) object then this method returns without changing anything. The properties that get copied are the "output" properties that presumably need to work their way back to the user. In other words, this method copies everything that make_new_context() did not. This method will never copy any properties which are undefined scalars or empty lists, so a CONTEXT with no "output" properties set will not cause any changes. If any scalar output properties of CONTEXT are defined, they will overwrite any defined corresponding properties of this object by default; however, if the optional boolean argument LEAVE_SCALARS is true, then the scalar values are only copied if the ones in this object are not defined. If any list output properties of CONTEXT have elements, then they will be appended to any corresponding ones of this object by default, thereby preserving both (except with hash properties, where like hash keys will overwrite); however, if the optional boolean argument REPLACE_LISTS is true, then any existing list values are overwritten by any copied CONTEXT equivalents.
METHODS FOR ERROR MESSAGES
These methods are accessors for the "error list" property of this object, which is designed to accumulate any error strings that should be printed to the program's error log or shown to the user before the program exits. See the DESCRIPTION for more details.
get_errors()
This method returns a list of the stored error messages with any undefined strings (no error) filtered out.
get_error([ INDEX ])
This method returns a single error message. If the numerical argument INDEX is defined then the message is taken from that element in the error list. INDEX defaults to -1 if not defined, so the most recent message is returned.
add_error( MESSAGE )
This method appends the scalar argument MESSAGE to the error list.
add_no_error()
This message appends an undefined value to the error list, a "no error" message.
AUTHOR
Copyright (c) 1999-2001, Darren R. Duncan. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. However, I do request that this copyright information remain attached to the file. If you modify this module and redistribute a changed version then please attach a note listing the modifications.
I am always interested in knowing how my work helps others, so if you put this module to use in any of your own code then please send me the URL. Also, if you make modifications to the module because it doesn't work the way you need, please send me a copy so that I can roll desirable changes into the main release.
Address comments, suggestions, and bug reports to perl@DarrenDuncan.net.
SEE ALSO
perl(1), CGI::Portable::Files, CGI::Portable.