XML::Checker man page on OpenServer

Man page or keyword search:  
man Server   5388 pages
apropos Keyword Search (all sections)
Output format
OpenServer logo
[printable version]

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 cur-
       rently 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 message 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 handler 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 significant 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 insignificant 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 white-
       space.

       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 section in the XML specification.

       ERROR Messages

       100 - 109

       o   100 - undefined NOTATION [$notation] in ATTLIST

	   The ATTLIST contained a Notation reference that was not defined in
	   a NOTATION definition.  VC: Notation Attributes

       o   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

       o   102 - undefined unparsed ENTITY [$entity]

	   The attribute value referenced an undefined unparsed entity.	 VC:
	   Entity Name

       o   103 - undefined attribute [$attrName]

	   The specified attribute was not defined in an ATTLIST for that Ele-
	   ment.  VC: Attribute Value Type

       110 - 119

       o   110 - attribute [$attrName] of element [$tagName] already defined

	   The specified attribute was already defined in this ATTLIST defini-
	   tion or in a previous one.  This is not an error according to the
	   XML spec.  See Attribute-List Declarations

       o   111 - ID [$value] already defined

	   An ID with the specified value was already defined in an attribute
	   within the same document.  VC: ID

       o   112 - unparsed ENTITY [$entity] already defined

	   This is not an error according to the XML spec.  See Entity Decla-
	   rations

       o   113 - NOTATION [$notation] already defined

       o   114 - ENTITY [$entity] already defined

	   This is not an error according to the XML spec.  See Entity Decla-
	   rations

       o   115 - ELEMENT [$name] already defined VC: Unique Element Type Dec-
	   laration

       120 - 129

       o   120 - invalid default ENTITY [$default]

	   (Or IDREF or NMTOKEN instead of ENTITY.)  The ENTITY, IDREF or
	   NMTOKEN reference in the default attribute value for an attribute
	   with types ENTITY, IDREF or NMTOKEN was not valid.  VC: Attribute
	   Default Legal

       o   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

       o   122 - invalid default attribute value [$default]

	   The specified default attribute value is not a valid attribute
	   value.  VC: Attribute Default Legal

       o   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

       o   124 - bad model [$model] for ELEMENT [$name]

	   The model in the ELEMENT definition did not conform to the XML syn-
	   tax for Mixed models.  See Mixed Content

       130 - 139

       o   130 - invalid NMTOKEN [$attrValue]

	   The attribute value is not a valid NmToken token.  VC: Enumeration

       o   131 - invalid ID [$attrValue]

	   The specified attribute value is not a valid Name token.  VC: ID

       o   132 - invalid IDREF [$value]

	   The specified attribute value is not a valid Name token.  VC: IDREF

       o   133 - invalid ENTITY name [$name]

	   The specified attribute value is not a valid Name token.  VC:
	   Entity Name

       o   134 - invalid Enumeration value [$value] in ATTLIST

	   The specified value is not a valid NmToken (see XML spec for def.)
	   See definition of NmToken

       o   135 - empty NOTATION list in ATTLIST

	   The NOTATION list of the ATTLIST definition did not contain any
	   NOTATION references.	 See definition of NotationType

       o   136 - empty Enumeration list in ATTLIST

	   The ATTLIST definition of the attribute of type Enumeration did not
	   contain any values.	See definition of Enumeration

       o   137 - invalid ATTLIST type [$type]

	   The attribute type has to be one of: ID, IDREF, IDREFS, ENTITY,
	   ENTITIES, NMTOKEN, NMTOKENS, CDATA, NOTATION or an Enumeration.
	   See definition of AttType

       150 - 159

       o   150 - bad #FIXED attribute value [$value], it should be [$default]

	   The specified attribute was defined as #FIXED in the ATTLIST defi-
	   nition and the found attribute $value differs from the specified
	   $default value.  VC: Fixed Attribute Default

       o   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

       o   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)

       o   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)

       o   154 - bad order of Elements Found=[$found] RE=[$re]

	   The child elements of the specified Element did not match the regu-
	   lar expression 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

       o   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 document

       o   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 exam-
	   ple.	 VC: Root Element Type

       o   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 parent Element (counting only Element nodes.)

       o   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.)

       o   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

       o   160 - invalid Enumeration value [$attrValue]

	   The specified attribute value does not match one of the Enumeration
	   values in the ATTLIST.  VC: Enumeration

       o   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: Nota-
	   tion Attributes

       o   162 - undefined NOTATION [$attrValue]

	   The NOTATION referenced by the specified attribute value was not
	   defined.  VC: Notation Attributes

       WARNING Messages (200 and up)

       o   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)

       o   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 inter-
       face".

       Currently, the XML::Checker object is a blessed hash with the following
       (potentially 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 meth-
       ods 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 guaranteed 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 sta-
       bilizes.

       Start ($tag)
	    $checker->Start($tag);

	   Call this when an Element with the specified $tag name is encoun-
	   tered.  Different 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 miss-
	   ing.

       CDATA ($text)
	    $checker->CDATA($text);

	   This should be called whenever CDATASections are encountered.  Sim-
	   ilar 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_doc-
       ument, 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, doc-
       type_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 distribution 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@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.8			  2000-01-31		       XML::Checker(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net