ppm::xml::validatingelement(3)
NAME
PPM::XML::ValidatingElement - XML Element with DTD-like
validation rules
SYNOPSIS
use PPM::XML::ValidatingElement; package PPM::XML::MyElement; @ISA = qw( PPM::XML::ValidatingElement ); @oattrs = qw( BAR ); # Allow for both FOO and BAR attributes @rattrs = qw( FOO ); @okids = qw( BLEARGH ); # Allow for both BLEARGH and FOOBAR children @rkids = qw( FOOBAR );
DESCRIPTION
PPM::XML::ValidatingElement inherits from PPM::XML::Ele
ment. It extends this class to support methods for vali
dation to allow for DTD-like restrictions to be places on
documents read in with the XML::Parser module.
VALIDATION RULES
In order to set up rules for validation of elements, each
element should define four list values in it's own package
namespace. When validating, this module will check to
ensure that any parsed attributes or child elements are
actually ones that are possible for this element, as well
as checking to see that any required attributes/child ele
ments are present.
Note that an attribute/child element only has to be pre
sent in either the optional or required list; when check
ing for possible attributes/children, these lists will be
combined.
Validation lists:
- @oattrs
- List of optional attributes.
- @rattrs
- List of required attributes.
- @opkids
- List of optional child elements.
- @rkids
- List of required child elements.
METHODS
- validate( err_handler )
- Validates the current element. This method calls four
other methods to validate all of requirements for the
element. Returns non-zero on success and zero if any
errors occurred. - rvalidate( err_handler )
- Validates the current element, and recursively vali
dates all child elements. This method calls four
other methods to validate all of the requirements for
the element. Returns non-zero on success and zero if
any errors occurred. - validate_possible_attrs( err_handler )
- Checks against the list of attributes possible for
this element (taken from @oattr and @rattr) to ensure
that all of the parsed attributes are valid. If any
parsed attributes are not in the list of possible
attributes for this element, err_handler will be
called with a message stating the error. Returns nonzero on success and zero if any errors occurred. - validate_required_attrs( err_handler )
- Checks against the list of required attributes (taken
from @rattr) to ensure that all of the required
attributes are present and have been parsed. If any
required attributes are missing, err_handler will be
called with a message stating the error. Returns nonzero on success and zero if any errors occurred. - validate_possible_kids( err_handler )
- Checks against the list of child elements this element
can contain (taken from @okids and @rkids) to ensure
that any child elements that have been read in are
valid. If any child elements have been parsed which
are not in the list of possible children, err_handler
will be called with a message stating the error.
Returns non-zero on success and zero if any errors
occurred. - validate_required_kids( err_handler )
- Checks against the lsit of required child elements
(taken from @rkids) to ensure that all of the required
child elements are present and have been parsed. If
any of the required child elements are missing,
err_handler will be called with a message stating the
error. Returns non-zero on success and zero if any
errors occurred.
LIMITATIONS
The PPM::XML::ValidatingElement module only provides
checks for determining whether or not the possi
ble/required attributes/children are present. This module
currently has no support for determining whether or not
the values provided are actually valid (although I imagine
it wouldn't be too hard to add this in somewhere). This
also includes elements which have been declared in a DTD
as being 'EMPTY' elements.
AUTHORS
Graham TerMarsch <grahamt@activestate.com>
HISTORY
v0.2 - Added failure return values to each of the methods.
v0.1 - Initial version
SEE ALSO
- PPM::XML::Element, XML::Parser