ch05_07.htm

Perl & XML. by Erik T. Ray and Jason McIntosh ISBN 0-596-00205-X First Edition, published April

strongly encouraged to do so. You should check to make sure that you
have a locator before trying to access it. Don't try
to use the locator except inside an event handler, or
you'll get unpredictable results.
</p>
</dd>


<a name="INDEX-433" /><dt><b><tt class="literal">start_document(</tt> <em class="replaceable">document</em> <tt class="literal">)</tt></b></dt>
<dd>
<p>This handler routine is called right after
<tt class="literal">set_document_locator( )</tt>, just as parsing on a
document begins. The parameter, <em class="replaceable">document</em>,
is an empty reference, as there are no properties for this event.
</p>
</dd>


<a name="INDEX-434" /><dt><b><tt class="literal">end_document(</tt> <em class="replaceable">document</em> <tt class="literal">)</tt></b></dt>
<dd>
<p>This is the last handler method called. If the parser has reached the
end of input or has encountered an error and given up, it sends
notification of this event. The return value for this method is used
as the value returned by the parser's
<tt class="literal">parse( )</tt> method. Again, the
<em class="replaceable">document</em> parameter is empty.
</p>
</dd>


<a name="INDEX-435" /><dt><b><tt class="literal">start_element(</tt> <em class="replaceable">element</em> <tt class="literal">)</tt></b></dt>
<dd>
<p>Whenever the parser encounters a new element start tag, it calls this
method. The parameter <em class="replaceable">element</em> is a hash
containing properties of the element, including:
</p>


<dl>
<dt><b><tt class="literal">Name</tt></b></dt>
<dd>
<p>The string containing the name of the element, including its
namespace prefix.
</p>
</dd>


<dt><b><tt class="literal">Attributes</tt></b></dt>
<dd>
<p>The hash of attributes, in which each key is encoded as
<tt class="literal">{</tt><em class="replaceable">NamespaceURI</em><tt class="literal">}</tt><em class="replaceable">LocalName</em>.
The value of each item in the hash is a hash of attribute properties.
</p>
</dd>


<dt><b><tt class="literal">NamespaceURI</tt></b></dt>
<dd>
<p>The element's namespace.</p>
</dd>


<dt><b><tt class="literal">Prefix</tt></b></dt>
<dd>
<p>The prefix part of the qualified name.</p>
</dd>


<dt><b><tt class="literal">LocalName</tt></b></dt>
<dd>
<p>The local part of the qualified name.</p>
</dd>

</dl>



<p>Properties for attributes include:</p>

<dl>
<dt><b><tt class="literal">Name</tt></b></dt>
<dd>
<p>The qualified name (prefix + local).</p>
</dd>


<dt><b><tt class="literal">Value</tt></b></dt>
<dd>
<p>The attribute's value, normalized (leading and
trailing spaces are removed).
</p>
</dd>


<dt><b><tt class="literal">NamespaceURI</tt></b></dt>
<dd>
<p>The source of the namespace.</p>
</dd>


<dt><b><tt class="literal">Prefix</tt></b></dt>
<dd>
<p>The prefix part of the qualified name.</p>
</dd>


<dt><b><tt class="literal">LocalName</tt></b></dt>
<dd>
<p>The local part of the qualified name.</p>
</dd>

</dl>

<p>The properties <tt class="literal">NamespaceURI</tt>,
<tt class="literal">LocalName</tt>, and <tt class="literal">Prefix</tt> are given
only if the parser supports the namespaces feature.
</p>
</dd>


<a name="INDEX-436" /><dt><b><tt class="literal">end_element(</tt> <em class="replaceable">element</em> <tt class="literal">)</tt></b></dt>
<dd>
<p>After all the content is processed and an element's
end tag has come into view, the parser calls this method. It is even
called for empty elements. The parameter
<em class="replaceable">element</em> is a hash containing these
properties:
</p>

<dl>
<dt><b><tt class="literal">Name</tt></b></dt>
<dd>
<p>The string containing the element's name, including
its namespace prefix.
</p>
</dd>


<dt><b><tt class="literal">NamespaceURI</tt></b></dt>
<dd>
<p>The element's namespace.</p>
</dd>


<dt><b><tt class="literal">Prefix</tt></b></dt>
<dd>
<p>The prefix part of the qualified name.</p>
</dd>


<dt><b><tt class="literal">LocalName</tt></b></dt>
<dd>
<p>The local part of the qualified name.</p>
</dd>

</dl>

<p>The properties <tt class="literal">NamespaceURI</tt>,
<tt class="literal">LocalName</tt>, and <tt class="literal">Prefix</tt> are given
only if the parser supports the namespaces feature.
</p>
</dd>


<a name="INDEX-437" /><dt><b><tt class="literal">characters(</tt> <em class="replaceable">characters</em> <tt class="literal">)</tt></b></dt>
<dd>
<p>The parser calls this method whenever it finds a chunk of plain text
(character data). It might break up a chunk into pieces and deliver
each piece separately, but the pieces must always be sent in the same
order as they were read. Within a piece, all text must come from the
same source entity. The <em class="replaceable">characters</em>
parameter is a hash containing one property, <tt class="literal">Data</tt>,
which is a string containing the characters from the document.
</p>
</dd>


<a name="INDEX-438" /><dt><b><tt class="literal">ignorable_whitespace(</tt> <em class="replaceable">characters</em> <tt class="literal">)</tt></b></dt>
<dd>
<p>The term <em class="emphasis">ignorable
whitespace</em><a name="INDEX-439" /> is used to describe space
characters that appear in places where the element's
content model declaration doesn't specifically call
for character data. In other words, the newlines often used to make
XML more readable by spacing elements apart can be ignored because
they aren't really content in the document. A parser
can tell if whitespace is ignorable only by reading the DTD, and it
would do that only if it supports the validation feature. (If you
don't understand this, don't worry;
it's not important to most people.) The
<em class="replaceable">characters</em> parameter is a hash containing
one property, <tt class="literal">Data</tt>, containing the
document's whitespace characters.
</p>
</dd>


<a name="INDEX-440" /><dt><b><tt class="literal">start_prefix_mapping(</tt> <em class="replaceable">mapping</em> <tt class="literal">)</tt></b></dt>
<dd>
<p>This method is called when the parser detects a namespace coming into
scope. For parsers that are not namespace-aware, this event is
skipped, but element and attribute names still include the namespace
prefixes. This event always occurs before the start of the element
for which the scope holds. The parameter
<em class="replaceable">mapping</em> is a hash with these properties:
</p>

<dl>
<dt><b><tt class="literal">Prefix</tt></b></dt>
<dd>
<p>The namespace prefix.</p>
</dd>


<dt><b><tt class="literal">NamespaceURI</tt></b></dt>
<dd>
<p>The URI that the prefix maps to.</p>
</dd>

</dl>
</dd>



<a name="INDEX-441" /><dt><b><tt class="literal">end_prefix_mapping(</tt> <em class="replaceable">mapping</em> <tt class="literal">)</tt></b></dt>
<dd>
<p>This method is called when a namespace scope closes. This
routine's parameter
<em class="replaceable">mapping</em> is a hash with one property:
</p>

<dl>
<dt><b><tt class="literal">Prefix</tt></b></dt>
<dd>
<p>The namespace prefix.</p>
</dd>

</dl>

<p>This event is guaranteed to come after the end element event for the
element in which the scope is declared.
</p>
</dd>


<a name="INDEX-442" /><dt><b><tt class="literal">processing_instruction(</tt> <em class="replaceable">pi</em> <tt class="literal">)</tt></b></dt>
<dd>
<p>This routine handles processing instruction events from the parser,
including those found outside the document element. The
<em class="replaceable">pi</em> parameter is a hash with these
properties:
</p>

<dl>
<dt><b><tt class="literal">Target</tt></b></dt>
<dd>
<p>The target for the processing instruction.</p>
</dd>


<dt><b><tt class="literal">Data</tt></b></dt>
<dd>
<p>The instruction's data (or <tt class="literal">undef</tt>
if there isn't any).
</p>
</dd>

</dl>
</dd>


<a name="INDEX-443" /><dt><b><tt class="literal">skipped_entity(</tt> <em class="replaceable">entity</em> <tt class="literal">)</tt></b></dt>
<dd>
<p>Nonvalidating parsers may skip entities rather than resolve them. For
example, if they haven't seen a declaration, they
can just ignore the entity rather than abort with an error. This
method gives the handler a chance to do something with the entity,
and perhaps even implement its own entity resolution scheme.
</p>

<p>If a parser skips entities, it will have one or more of these
features set:
</p>


<ul><li>
<p>Handle external parameter entities (feature-ID is <em class="emphasis">http://xml.org/sax/features/external-parameter-entities</em>)
</p>
</li><li>
<p>Handle external general entities (feature-ID is <em class="emphasis">http://xml.org/sax/features/external-general-entities</em>)
</p>
</li></ul>
<p>(In XML, features are represented as URIs, which may or may not
actually exist. See <a href="ch10_01.htm">Chapter 10, "Coding Strategies"</a> for a fuller
explanation.)
</p>

<p>The parameter <em class="replaceable">entity</em> is a hash with this
property:
</p>

<dl>
<dt><b><tt class="literal">Name</tt></b></dt>
<dd>
<p>The name of the entity that was skipped. If it's a
parameter entity, the name will be prefixed with a percent sign (%).
</p>