On Apache/1.3.41 (Unix) PHP/5.2.5 mod_perl/1.30 mod_gzip/1.3.26.1a
Under GNU General Public License
2009-01-09 03:37 @38.103.63.58 CrawledBy CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
XML::Checker(3) User Contributed Perl Documentation XML::Checker(3)
NAME
XML::Checker - A perl module for validating XML
SYNOPSIS
XML::Checker::Parser - an XML::Parser that validates at parse time
XML::DOM::ValParser - an XML::DOM::Parser that validates at parse time
(Some of the package names may change! This is only an alpha release...)
DESCRIPTION
XML::Checker can be used in different ways to validate XML. See the manual pages of
XML::Checker::Parser and XML::DOM::ValParser for more information.
This document only describes common topics like error handling and the XML::Checker
class itself.
WARNING: Not all errors are currently checked. Almost everything is subject to
change. Some reported errors may not be real errors.
ERROR HANDLING
Whenever XML::Checker (or one of the packages that uses XML::Checker) detects a
potential error, the ’fail handler’ is called. It is currently also called to
report information, like how many times an Entity was referenced. (The whole error
handling mechanism is subject to change, I’m afraid...)
The default fail handler is XML::Checker::print_error(), which prints an error mes-
sage to STDERR. It does not stop the XML::Checker, so it will continue looking for
other errors. The error message is created with XML::Checker::error_string().
You can define your own fail handler in two ways, locally and globally. Use a local
variable to temporarily override the fail handler. This way the default fail han-
dler is restored when the local variable goes out of scope, esp. when exceptions
are thrown e.g.
# Using a local variable to temporarily override the fail handler (preferred)
{ # new block - start of local scope
local $XML::Checker::FAIL = \&my_fail;
... your code here ...
} # end of block - the previous fail handler is restored
You can also set the error handler globally, risking that your code may not be
reusable or may clash with other modules that use XML::Checker.
# Globally setting the fail handler (not recommended)
$XML::Checker::FAIL = \&my_fail;
... rest of your code ...
The fail handler is called with the following parameters ($code, $msg, @context),
where $code is the error code, $msg is the error description and @context contains
information on where the error occurred. The @context is a (ordered) list of
(key,value) pairs and can easily be turned into a hash. It contains the following
information:
Element - tag name of Element node (if applicable)
Attr - attribute name (if applicable)
ChildElementIndex - if applicable (see error 157)
line - only when parsing
column - only when parsing
byte - only when parsing (-1 means: end of file)
Some examples of fail handlers:
# Don’t print info messages
sub my_fail
{
my $code = shift;
print STDERR XML::Checker::error_message ($code, @_)
if $code < 300;
}
# Die when the first error is encountered - this will stop
# the parsing process. Ignore information messages.
sub my_fail
{
my $code = shift;
die XML::Checker::error_message ($code, @_) if $code < 300;
}
# Count the number of undefined NOTATION references
# and print the error as usual
sub my_fail
{
my $code = shift;
$count_undef_notations++ if $code == 100;
XML::Checker::print_error ($code, @_);
}
# Die when an error is encountered.
# Don’t die if a warning or info message is encountered, just print a message.
sub my_fail {
my $code = shift;
die XML::Checker::error_string ($code, @_) if $code < 200;
XML::Checker::print_error ($code, @_);
}
INSIGNIFICANT WHITESPACE
XML::Checker keeps track of whether whitespace found in character data is signifi-
cant or not. It is considered insignicant if it is found inside an element that has
a ELEMENT rule that is not of type Mixed or of type ANY. (A Mixed ELEMENT rule
does contains the #PCDATA keyword. An ANY rule contains the ANY keyword. See the
XML spec for more info.)
XML::Checker can not determine whether whitespace is insignificant in those two
cases, because they both allow regular character data to appear within XML elements
and XML::Checker can therefore not deduce whether whitespace is part of the actual
data or was just added for readability of the XML file.
XML::Checker::Parser and XML::DOM::ValParser both have the option to skip insignif-
icant whitespace when setting SkipInsignifWS to 1 in their constructor. If set,
they will not call the Char handler when insignificant whitespace is encountered.
This means that in XML::DOM::ValParser no Text nodes are created for insignificant
whitespace.
Regardless of whether the SkipInsignifWS options is set, XML::Checker always keeps
track of whether whitespace is insignificant. After making a call to XML::Checker’s
Char handler, you can find out if it was insignificant whitespace by calling the
isInsignifWS method.
When using multiple (nested) XML::Checker instances or when using XML::Checker
without using XML::Checker::Parser or XML::DOM::ValParser (which hardly anybody
probably will), make sure to set a local variable in the scope of your checking
code, e.g.
{ # new block - start of local scope
local $XML::Checker::INSIGNIF_WS = 0;
... insert your code here ...
} # end of scope
ERROR CODES
There are 3 categories, errors, warnings and info messages. (The codes are still
subject to change, as well the error descriptions.)
Most errors have a link to the appropriate Validaty Constraint (VC) or other sec-
tion in the XML specification.
ERROR Messages
100 - 109
· 100 - undefined NOTATION [$notation] in ATTLIST
The ATTLIST contained a Notation reference that was not defined in a NOTATION
definition. VC: Notation Attributes
· 101 - undefined ELEMENT [$tagName]
The specified Element was never defined in an ELEMENT definition. This is not
an error according to the XML spec. See Element Type Declarations
· 102 - undefined unparsed ENTITY [$entity]
The attribute value referenced an undefined unparsed entity. VC: Entity Name
· 103 - undefined attribute [$attrName]
The specified attribute was not defined in an ATTLIST for that Element. VC:
Attribute Value Type
110 - 119
· 110 - attribute [$attrName] of element [$tagName] already defined
The specified attribute was already defined in this ATTLIST definition or in a
previous one. This is not an error according to the XML spec. See Attribute-
List Declarations
· 111 - ID [$value] already defined
An ID with the specified value was already defined in an attribute within the
same document. VC: ID
· 112 - unparsed ENTITY [$entity] already defined
This is not an error according to the XML spec. See Entity Declarations
· 113 - NOTATION [$notation] already defined
· 114 - ENTITY [$entity] already defined
This is not an error according to the XML spec. See Entity Declarations
· 115 - ELEMENT [$name] already defined VC: Unique Element Type Declaration
120 - 129
· 120 - invalid default ENTITY [$default]
(Or IDREF or NMTOKEN instead of ENTITY.) The ENTITY, IDREF or NMTOKEN refer-
ence in the default attribute value for an attribute with types ENTITY, IDREF
or NMTOKEN was not valid. VC: Attribute Default Legal
· 121 - invalid default [$token] in ENTITIES [$default]
(Or IDREFS or NMTOKENS instead of ENTITIES) One of the ENTITY, IDREF or NMTOKEN
references in the default attribute value for an attribute with types ENTITIES,
IDREFS or NMTOKENS was not valid. VC: Attribute Default Legal
· 122 - invalid default attribute value [$default]
The specified default attribute value is not a valid attribute value. VC:
Attribute Default Legal
· 123 - invalid default ID [$default], must be #REQUIRED or #IMPLIED
The default attribute value for an attribute of type ID has to be #REQUIRED or
#IMPLIED. VC: ID Attribute Default
· 124 - bad model [$model] for ELEMENT [$name]
The model in the ELEMENT definition did not conform to the XML syntax for Mixed
models. See Mixed Content
130 - 139
· 130 - invalid NMTOKEN [$attrValue]
The attribute value is not a valid NmToken token. VC: Enumeration
· 131 - invalid ID [$attrValue]
The specified attribute value is not a valid Name token. VC: ID
· 132 - invalid IDREF [$value]
The specified attribute value is not a valid Name token. VC: IDREF
· 133 - invalid ENTITY name [$name]
The specified attribute value is not a valid Name token. VC: Entity Name
· 134 - invalid Enumeration value [$value] in ATTLIST
The specified value is not a valid NmToken (see XML spec for def.) See defini-
tion of NmToken
· 135 - empty NOTATION list in ATTLIST
The NOTATION list of the ATTLIST definition did not contain any NOTATION refer-
ences. See definition of NotationType
· 136 - empty Enumeration list in ATTLIST
The ATTLIST definition of the attribute of type Enumeration did not contain any
values. See definition of Enumeration
· 137 - invalid ATTLIST type [$type]
The attribute type has to be one of: ID, IDREF, IDREFS, ENTITY, ENTITIES, NMTO-
KEN, NMTOKENS, CDATA, NOTATION or an Enumeration. See definition of AttType
150 - 159
· 150 - bad #FIXED attribute value [$value], it should be [$default]
The specified attribute was defined as #FIXED in the ATTLIST definition and the
found attribute $value differs from the specified $default value. VC: Fixed
Attribute Default
· 151 - only one ID allowed in ATTLIST per element first=[$attrName]
The ATTLIST definitions for an Element may contain only one attribute with the
type ID. The specified $attrName is the one that was found first. VC: One ID
per Element Type
· 152 - Element should be EMPTY, found Element [$tagName]
The ELEMENT definition for the specified Element said it should be EMPTY, but a
child Element was found. VC: Element Valid (sub1)
· 153 - Element should be EMPTY, found text [$text]
The ELEMENT definition for the specified Element said it should be EMPTY, but
text was found. Currently, whitespace is not allowed between the open and close
tag. (This may be wrong, please give feedback.) To allow whitespace (subject
to change), set:
$XML::Checker::Context::EMPTY::ALLOW_WHITE_SPACE = 1;
VC: Element Valid (sub1)
· 154 - bad order of Elements Found=[$found] RE=[$re]
The child elements of the specified Element did not match the regular expres-
sion found in the ELEMENT definition. $found contains a comma separated list of
all the child element tag names that were found. $re contains the (decoded)
regular expression that was used internally. VC: Element Valid
· 155 - more than one root Element [$tags]
An XML Document may only contain one Element. $tags is a comma separated list
of element tag names encountered sofar. XML::Parser (expat) throws ’no element
found’ exception. See two_roots.xml for an example. See definition of docu-
ment
· 156 - unexpected root Element [$tagName], expected [$rootTagName]
The tag name of the root Element of the XML Document differs from the name
specified in the DOCTYPE section. XML::Parser (expat) throws ’not well-formed’
exception. See bad_root.xml for an example. VC: Root Element Type
· 157 - unexpected Element [$tagName]
The ELEMENT definition for the specified Element does not allow child Elements
with the specified $tagName. VC: Element Valid
The error context contains ChildElementIndex which is the index within its par-
ent Element (counting only Element nodes.)
· 158 - unspecified value for #IMPLIED attribute [$attrName]
The ATTLIST for the specified attribute said the attribute was #IMPLIED, which
means the user application should supply a value, but the attribute value was
not specified. (User applications should pass a value and set $specified to 1
in the Attr handler.)
· 159 - unspecified value for #REQUIRED attribute [$attrName]
The ATTLIST for the specified attribute said the attribute was #REQUIRED, which
means that a value should have been specified. VC: Required Attribute
160 - 169
· 160 - invalid Enumeration value [$attrValue]
The specified attribute value does not match one of the Enumeration values in
the ATTLIST. VC: Enumeration
· 161 - invalid NOTATION value [$attrValue]
The specifed attribute value was not found in the list of possible NOTATION
references as found in the ATTLIST definition. VC: Notation Attributes
· 162 - undefined NOTATION [$attrValue]
The NOTATION referenced by the specified attribute value was not defined. VC:
Notation Attributes
WARNING Messages (200 and up)
· 200 - undefined ID [$id] was referenced [$n] times
The specified ID was referenced $n times, but never defined in an attribute
value with type ID. VC: IDREF
INFO Messages (300 and up)
· 300 - [$n] references to ID [$id]
The specified ID was referenced $n times.
Not checked
The following errors are already checked by XML::Parser (expat) and are currently
not checked by XML::Checker:
(?? TODO - add more info)
root element is missing
XML::Parser (expat) throws ’no element found’ exception. See no_root.xml for
an example.
XML::Checker
XML::Checker can be easily plugged into your application. It uses mostly the same
style of event handlers (or callbacks) as XML::Parser. See XML::Parser manual page
for descriptions of most handlers.
It also implements PerlSAX style event handlers. See "PerlSAX interface".
Currently, the XML::Checker object is a blessed hash with the following (poten-
tially useful) entries:
$checker->{RootElement} - root element name as found in the DOCTYPE
$checker->{NOTATION}->{$notation} - is 1 if the NOTATION was defined
$checker->{ENTITY}->{$name} - contains the (first) ENTITY value if defined
$checker->{Unparsed}->{$entity} - is 1 if the unparsed ENTITY was defined
$checker->{ID}->{$id} - is 1 if the ID was defined
$checker->{IDREF}->{$id} - number of times the ID was referenced
# Less useful:
$checker->{ERule}->{$tag} - the ELEMENT rules by Element tag name
$checker->{ARule}->{$tag} - the ATTLIST rules by Element tag name
$checker->{Context} - context stack used internally
$checker->{CurrARule} - current ATTLIST rule for the current Element
XML:Checker methods
This section is only interesting when using XML::Checker directly. XML::Checker
supports most event handlers that XML::Parser supports with minor differences. Note
that the XML::Checker event handler methods are instance methods and not static, so
don’t forget to call them like this, without passing $expat (as in the XML::Parser)
handlers:
$checker->Start($tagName);
Constructor
$checker = new XML::Checker;
$checker = new XML::Checker (%user_args);
User data may be stored by client applications. Only $checker->{User} is guar-
anteed not to clash with internal hash keys.
getRootElement ()
$tagName = $checker->getRootElement;
Returns the root element name as found in the DOCTYPE
Expat interface
XML::Checker supports what I call the Expat interface, which is the collection of
methods you normally specify as the callback handlers when using XML::Parser.
Only the following XML::Parser handlers are currently supported: Init, Final, Char,
Start, End, Element, Attlist, Doctype, Unparsed, Entity, Notation.
I don’t know how to correctly support the Default handler for all XML::Parser
releases. The Start handler works a little different (see below) and I added Attr,
InitDomElem, FinalDomElem, CDATA and EntityRef handlers. See XML::Parser for a
description of the handlers that are not listed below.
Note that this interface may disappear, when the PerlSAX interface stabilizes.
Start ($tag)
$checker->Start($tag);
Call this when an Element with the specified $tag name is encountered. Differ-
ent from the Start handler in XML::Parser, in that no attributes are passed in
(use the Attr handler for those.)
Attr ($tag, $attrName, $attrValue, $isSpecified)
$checker->Attr($tag,$attrName,$attrValue,$spec);
Checks an attribute with the specified $attrName and $attrValue against the
ATTLIST definition of the element with the specified $tag name. $isSpecified
means whether the attribute was specified (1) or defaulted (0).
EndAttr ()
$checker->EndAttr;
This should be called after all attributes are passed with Attr(). It will
check which of the #REQUIRED attributes were not specified and generate the
appropriate error (159) for each one that is missing.
CDATA ($text)
$checker->CDATA($text);
This should be called whenever CDATASections are encountered. Similar to Char
handler (but might perform different checks later...)
EntityRef ($entity, $isParameterEntity)
$checker->EntityRef($entity,$isParameterEntity);
Checks the ENTITY reference. Set $isParameterEntity to 1 for entity references
that start with ’%’.
InitDomElem () and FinalDomElem ()
Used by XML::DOM::Element::check() to initialize (and cleanup) the context
stack when checking a single element.
PerlSAX interface
XML::Checker now also supports the PerlSAX interface, so you can use XML::Checker
wherever you use PerlSAX handlers.
XML::Checker implements the following methods: start_document, end_document,
start_element, end_element, characters, processing_instruction, comment,
start_cdata, end_cdata, entity_reference, notation_decl, unparsed_entity_decl,
entity_decl, element_decl, attlist_decl, doctype_decl, xml_decl
Not implemented: set_document_locator, ignorable_whitespace
See PerlSAX.pod for details. (It is called lib/PerlSAX.pod in the libxml-perl dis-
tribution which can be found at CPAN.)
CAVEATS
This is an alpha release. Almost everything is subject to change.
AUTHOR
Send bug reports, hints, tips, suggestions to Enno Derksen at <enno AT att.com>.
SEE ALSO
The home page of XML::Checker at <http://www.erols.com/enno/checker/index.html>
The XML spec (Extensible Markup Language 1.0) at <http://www.w3.org/TR/REC-xml>
The XML::Parser and XML::Parser::Expat manual pages.
The other packages that come with XML::Checker: XML::Checker::Parser,
XML::DOM::ValParser
The DOM Level 1 specification at <http://www.w3.org/TR/REC-DOM-Level-1>
The PerlSAX specification. It is currently in lib/PerlSAX.pod in the libxml-perl
distribution by Ken MacLeod.
The original SAX specification (Simple API for XML) can be found at
<http://www.megginson.com/SAX> and <http://www.megginson.com/SAX/SAX2>
perl v5.8.5 2000-01-31 XML::Checker(3)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache/1.3.41 (Unix) PHP/5.2.5 mod_perl/1.30 mod_gzip/1.3.26.1a
Under GNU General Public License
2009-01-09 03:37 @38.103.63.58 CrawledBy CCBot/1.0 (+http://www.commoncrawl.org/bot.html)