parser.html

perl教程

of entity references inside attribute values.</p>
</li>
<li><strong><a name="item_stream_delimiter">Stream_Delimiter</a></strong>

<p>This is an Expat option. It takes a string value. When this string is found
alone on a line while parsing from a stream, then the parse is ended as if it
saw an end of file. The intended use is with a stream of xml documents in a
MIME multipart format. The string should not contain a trailing newline.</p>
</li>
<li><strong><a name="item_parseparament">ParseParamEnt</a></strong>

<p>This is an Expat option. Unless standalone is set to &quot;yes&quot; in the XML
declaration, setting this to a true value allows the external DTD to be read,
and parameter entities to be parsed and expanded.</p>
</li>
<li><strong><a name="item_nolwp">NoLWP</a></strong>

<p>This option has no effect if the ExternEnt or ExternEntFin handlers are
directly set. Otherwise, if true, it forces the use of a file based external
entity handler.</p>
</li>
<li><strong><a name="item_non_2dexpat_2doptions">Non-Expat-Options</a></strong>

<p>If provided, this should be an anonymous hash whose keys are options that
shouldn't be passed to Expat. This should only be of concern to those
subclassing XML::Parser.</p>
</li>
</ul>
<dt><strong><a name="item_sethandlers">setHandlers(TYPE, HANDLER [, TYPE, HANDLER [...]])</a></strong>

<dd>
<p>This method registers handlers for various parser events. It overrides any
previous handlers registered through the Style or Handler options or through
earlier calls to setHandlers. By providing a false or undefined value as
the handler, the existing handler can be unset.</p>
</dd>
<dd>
<p>This method returns a list of type, handler pairs corresponding to the
input. The handlers returned are the ones that were in effect prior to
the call.</p>
</dd>
<dd>
<p>See a description of the handler types in <a href="#handlers">HANDLERS</a>.</p>
</dd>
</li>
<dt><strong><a name="item_parse">parse(SOURCE [, OPT =&gt; OPT_VALUE [...]])</a></strong>

<dd>
<p>The SOURCE parameter should either be a string containing the whole XML
document, or it should be an open IO::Handle. Constructor options to
XML::Parser::Expat given as keyword-value pairs may follow the SOURCE
parameter. These override, for this call, any options or attributes passed
through from the XML::Parser instance.</p>
</dd>
<dd>
<p>A die call is thrown if a parse error occurs. Otherwise it will return 1
or whatever is returned from the <strong>Final</strong> handler, if one is installed.
In other words, what parse may return depends on the style.</p>
</dd>
</li>
<dt><strong><a name="item_parsestring">parsestring</a></strong>

<dd>
<p>This is just an alias for parse for backwards compatibility.</p>
</dd>
</li>
<dt><strong><a name="item_parsefile">parsefile(FILE [, OPT =&gt; OPT_VALUE [...]])</a></strong>

<dd>
<p>Open FILE for reading, then call parse with the open handle. The file
is closed no matter how parse returns. Returns what parse returns.</p>
</dd>
</li>
<dt><strong><a name="item_parse_start">parse_start([ OPT =&gt; OPT_VALUE [...]])</a></strong>

<dd>
<p>Create and return a new instance of XML::Parser::ExpatNB. Constructor
options may be provided. If an init handler has been provided, it is
called before returning the ExpatNB object. Documents are parsed by
making incremental calls to the parse_more method of this object, which
takes a string. A single call to the parse_done method of this object,
which takes no arguments, indicates that the document is finished.</p>
</dd>
<dd>
<p>If there is a final handler installed, it is executed by the parse_done
method before returning and the parse_done method returns whatever is
returned by the final handler.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="handlers">HANDLERS</a></h1>
<p>Expat is an event based parser. As the parser recognizes parts of the
document (say the start or end tag for an XML element), then any handlers
registered for that type of an event are called with suitable parameters.
All handlers receive an instance of XML::Parser::Expat as their first
argument. See <a href="../../lib/XML/Parser/Expat.html#methods">METHODS in the XML::Parser::Expat manpage</a> for a discussion of the
methods that can be called on this object.</p>
<p>
</p>
<h2><a name="init__expat_">Init                (Expat)</a></h2>
<p>This is called just before the parsing of the document starts.</p>
<p>
</p>
<h2><a name="final__expat_">Final                (Expat)</a></h2>
<p>This is called just after parsing has finished, but only if no errors
occurred during the parse. Parse returns what this returns.</p>
<p>
</p>
<h2><a name="start__expat__element____attr__val_________">Start                (Expat, Element [, Attr, Val [,...]])</a></h2>
<p>This event is generated when an XML start tag is recognized. Element is the
name of the XML element type that is opened with the start tag. The Attr &amp;
Val pairs are generated for each attribute in the start tag.</p>
<p>
</p>
<h2><a name="end__expat__element_">End                (Expat, Element)</a></h2>
<p>This event is generated when an XML end tag is recognized. Note that
an XML empty tag (&lt;foo/&gt;) generates both a start and an end event.</p>
<p>
</p>
<h2><a name="char__expat__string_">Char                (Expat, String)</a></h2>
<p>This event is generated when non-markup is recognized. The non-markup
sequence of characters is in String. A single non-markup sequence of
characters may generate multiple calls to this handler. Whatever the
encoding of the string in the original document, this is given to the
handler in UTF-8.</p>
<p>
</p>
<h2><a name="proc__expat__target__data_">Proc                (Expat, Target, Data)</a></h2>
<p>This event is generated when a processing instruction is recognized.</p>
<p>
</p>
<h2><a name="comment__expat__data_">Comment                (Expat, Data)</a></h2>
<p>This event is generated when a comment is recognized.</p>
<p>
</p>
<h2><a name="cdatastart__expat_">CdataStart        (Expat)</a></h2>
<p>This is called at the start of a CDATA section.</p>
<p>
</p>
<h2><a name="cdataend__expat_">CdataEnd                (Expat)</a></h2>
<p>This is called at the end of a CDATA section.</p>
<p>
</p>
<h2><a name="default__expat__string_">Default                (Expat, String)</a></h2>
<p>This is called for any characters that don't have a registered handler.
This includes both characters that are part of markup for which no
events are generated (markup declarations) and characters that
could generate events, but for which no handler has been registered.</p>
<p>Whatever the encoding in the original document, the string is returned to
the handler in UTF-8.</p>
<p>
</p>
<h2><a name="unparsed__expat__entity__base__sysid__pubid__notation_">Unparsed                (Expat, Entity, Base, Sysid, Pubid, Notation)</a></h2>
<p>This is called for a declaration of an unparsed entity. Entity is the name
of the entity. Base is the base to be used for resolving a relative URI.
Sysid is the system id. Pubid is the public id. Notation is the notation
name. Base and Pubid may be undefined.</p>
<p>
</p>
<h2><a name="notation__expat__notation__base__sysid__pubid_">Notation                (Expat, Notation, Base, Sysid, Pubid)</a></h2>
<p>This is called for a declaration of notation. Notation is the notation name.
Base is the base to be used for resolving a relative URI. Sysid is the system
id. Pubid is the public id. Base, Sysid, and Pubid may all be undefined.</p>
<p>
</p>
<h2><a name="externent__expat__base__sysid__pubid_">ExternEnt        (Expat, Base, Sysid, Pubid)</a></h2>
<p>This is called when an external entity is referenced. Base is the base to be
used for resolving a relative URI. Sysid is the system id. Pubid is the public
id. Base, and Pubid may be undefined.</p>
<p>This handler should either return a string, which represents the contents of
the external entity, or return an open filehandle that can be read to obtain
the contents of the external entity, or return undef, which indicates the
external entity couldn't be found and will generate a parse error.</p>
<p>If an open filehandle is returned, it must be returned as either a glob
(*FOO) or as a reference to a glob (e.g. an instance of IO::Handle).</p>
<p>A default handler is installed for this event. The default handler is
XML::Parser::lwp_ext_ent_handler unless the NoLWP option was provided with
a true value, otherwise XML::Parser::file_ext_ent_handler is the default
handler for external entities. Even without the NoLWP option, if the
URI or LWP modules are missing, the file based handler ends up being used
after giving a warning on the first external entity reference.</p>
<p>The LWP external entity handler will use proxies defined in the environment
(http_proxy, ftp_proxy, etc.).</p>
<p>Please note that the LWP external entity handler reads the entire
entity into a string and returns it, where as the file handler opens a
filehandle.</p>
<p>Also note that the file external entity handler will likely choke on
absolute URIs or file names that don't fit the conventions of the local
operating system.</p>
<p>The expat base method can be used to set a basename for
relative pathnames. If no basename is given, or if the basename is itself