Menu
▾
▴
[perl-xml-cvs] CVS: libxml-perl/doc sax-2.0-adv.html,1.6,1.7 sax-2.0.html,1.6,1.7
|
From: Petr C. <pci...@us...> - 2004-02-04 17:04:23
|
Update of /cvsroot/perl-xml/libxml-perl/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv9536/doc Modified Files: sax-2.0-adv.html sax-2.0.html Log Message: minor editorial changes Index: sax-2.0-adv.html =================================================================== RCS file: /cvsroot/perl-xml/libxml-perl/doc/sax-2.0-adv.html,v retrieving revision 1.6 retrieving revision 1.7 diff -u -d -r1.6 -r1.7 --- sax-2.0-adv.html 9 Nov 2001 18:19:48 -0000 1.6 +++ sax-2.0-adv.html 4 Feb 2004 17:01:58 -0000 1.7 @@ -22,7 +22,7 @@ <p>SAX supports several classes of event handlers: content handlers, declaration handlers, DTD handlers, error handlers, entity resolvers, -and other extensions. For each class of events, a seperate handler +and other extensions. For each class of events, a separate handler can be used to handle those events. If a handler is not defined for a class of events, then the default handler, <tt>Handler</tt>, is used. Each of these handlers is described in the sections below. @@ -31,8 +31,8 @@ <p>SAX's basic interface defines methods for parsing system identifiers (URIs), open files, and strings. Behind the scenes, -though, SAX uses a <tt>Source</tt> hash that contains that -information, plus encoding, system and public identifiers if +though, SAX uses a <tt>Source</tt> hash reference that contains +that information, plus encoding, system and public identifiers if available. These are described below under the <tt>Source</tt> option.</p> @@ -44,8 +44,8 @@ <dl><dt><b><tt class='function'>parse</tt></b>(<var>options</var>)</dt> <dd> Parses the XML instance identified by the <tt>Source</tt> option. -<var>options</var> can be a list of option, value pairs or a hash. -<tt>parse()</tt> returns the result of calling the +<var>options</var> can be a list of options, value pairs or a hash +(reference). <tt>parse()</tt> returns the result of calling the <tt>end_document()</tt> handler.</dd></dl></p> <p> @@ -86,24 +86,21 @@ <p> <dl><dt><b><tt>Source</tt></b></dt> <dd> -A hash containing information about the XML instance to be parsed. +A hash reference containing information about the XML instance to be parsed. See <a href="#InputSources">Input Sources</a> below. Note that <tt>Source</tt> cannot be changed during the parse</dd></dl></p> <p> - <dl> - <dt><strong><tt>Features</tt></strong></dt> - <dd> - A hash containing Feature information, as described below. - Features can be set at runtime but not directly on the Features - hash (at least, not reliably. You can do it, but the results - might not be what you expect as it doesn't give the parser a - chance to look at what you've set so that it can't react properly - to errors, or Features that it doesn't support). You should use - the <code>set_feature()</code> method instead. - </dd> - </dl> -</p> +<dl><dt><strong><tt>Features</tt></strong></dt> +<dd> +A hash reference containing Feature information, as described +below. Features can be set at runtime but not directly on the +Features hash (at least, not reliably. You can do it, but the +results might not be what you expect as it doesn't give the +parser a chance to look at what you've set so that it can't +react properly to errors, or Features that it doesn't support). +You should use the <code>set_feature()</code> method instead. +</dd></dl></p> <h2><a name="Features">Features</a></h2> @@ -148,7 +145,7 @@ <p> Also, Features are things that are supposed to be <strong>turned on</strong>, and thus should normally be off by default, especially if - the parser doesn't support turning them off. Due to backwards + the parser doesn't support turning them off. Due to backward compatibility problems, the one exception to this rule is the "<tt>http://xml.org/sax/features/namespaces</tt>" Feature which is on by default and which a number of parsers may not be able to turn off. Thus, @@ -222,26 +219,24 @@ <p> - <dl> - <dt><strong><code class='function'>get_features</code></strong>()</dt> - <dd> - Look up all Features that this parser claims to support. - <p> - This method returns a hash of Features which the parser - claims to support. The value of the hash is currently - unspecified though it may be used later. This method is meant - to be inherited so that Features supported by the base parser - class (XML::SAX::Base) are declared to be supported by - subclasses. - </p> - <p> - Calling this method is probably only moderately useful to end - users. It is mostly meant for use by XML::SAX, so that it can - query parsers for Feature support and return an appropriate - parser depending on the Features that are required. - </p> - </dd> - </dl> +<dl> +<dt><strong><code class='function'>get_features</code></strong>()</dt> +<dd> +Look up all Features that this parser claims to support. +<p> +This method returns a reference to hash of Features which the parser +claims to support. The value of the hash is currently +unspecified though it may be used later. This method is meant +to be inherited so that Features supported by the base parser +class (XML::SAX::Base) are declared to be supported by subclasses. +</p> +<p> +Calling this method is probably only moderately useful to end +users. It is mostly meant for use by XML::SAX, so that it can +query parsers for Feature support and return an appropriate +parser depending on the Features that are required. +</p> +</dd></dl> </p> @@ -249,7 +244,7 @@ <h2><a name="InputSources">Input Sources</a></h2> <p>Input sources may be provided to parser objects or are returned by -entity resolvers. An input source is a hash with these +entity resolvers. An input source is a hash reference with these properties:</p> <dl> @@ -291,8 +286,8 @@ ignore any byte stream and will not attempt to open a URI connection to the system identifier.</p> -<p>Note: A CharacterStream is a filehandle that does not need any encoding -translation done on it. This is implemented as a regular filehandle +<p>Note: A CharacterStream is a file-handle that does not need any encoding +translation done on it. This is implemented as a regular file-handle and only works under Perl 5.7.2 or higher using PerlIO. To get a single character, or number of characters from it, use the perl core read() function. To get a single byte from it (or number of bytes), you can @@ -357,7 +352,7 @@ the invocation of the events in this interface. The application should not attempt to use it at any other time.</p> -<p>The locator is a hash with these properties:</p> +<p>The locator is a hash reference with these properties:</p> <blockquote> <table> @@ -396,14 +391,14 @@ <p>Note that <tt>start</tt>/<tt>end_prefix_mapping()</tt> events are not guaranteed to be properly nested relative to each-other: all -<tt>start_prefix_apping()</tt> events will occur before the +<tt>start_prefix_mapping()</tt> events will occur before the corresponding <tt>start_element()</tt> event, and all <tt>end_prefix_mapping</tt> events will occur after the corresponding <tt>end_element()</tt> event, but their order is not guaranteed. </p> -<p><var>mapping</var> is a hash with these properties:</p> +<p><var>mapping</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -425,7 +420,7 @@ the order of <tt>end_prefix_mapping</tt> events is not otherwise guaranteed.</p> -<p><var>mapping</var> is a hash with this property:</p> +<p><var>mapping</var> is a hash reference with this property:</p> <blockquote> <table> @@ -448,7 +443,7 @@ section 2.8) or a text declaration (XML 1.0, section 4.3.1) using this method.</p> -<p><var>pi</var> is a hash with these properties:</p> +<p><var>pi</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -475,7 +470,7 @@ "<tt>http://xml.org/sax/features/external-parameter-entities</tt>" Features.</p> -<p><var>entity</var> is a hash with these properties:</p> +<p><var>entity</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -499,7 +494,7 @@ handler, all of the events will occur between the <tt>start_dtd</tt> and the <tt>end_dtd</tt> events.</p> -<p>To set a seperate DeclHandler for an XML reader, set the +<p>To set a separate DeclHandler for an XML reader, set the "<tt>http://xml.org/sax/handlers/DeclHandler</tt>" Feature with the object to received declaration events. If the reader does not support declaration events, it will throw a <tt>XML::SAX::Exception::NotRecognized</tt> @@ -518,7 +513,7 @@ indicator. The model will be normalized so that all whitespace is removed, and will include the enclosing parentheses.</p> -<p><var>element</var> is a hash with these properties:</p> +<p><var>element</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -542,7 +537,7 @@ "<tt>ENTITIES</tt>", or "<tt>NOTATION</tt>", or a parenthesized token group with the separator "<tt>|</tt>" and all whitespace removed.</p> -<p><var>attribute</var> is a hash with these properties:</p> +<p><var>attribute</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -571,7 +566,7 @@ <p>Only the effective (first) declaration for each entity will be reported.</p> -<p><var>entity</var> is a hash with these properties:</p> +<p><var>entity</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -592,7 +587,7 @@ <p>Only the effective (first) declaration for each entity will be reported.</p> -<p><var>entity</var> is a hash with these properties:</p> +<p><var>entity</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -639,7 +634,7 @@ <p>If a system identifier is present, and it is a URL, the SAX parser must resolve it fully before passing it to the application.</p> -<p><var>notation</var> is a hash with these properties:</p> +<p><var>notation</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -667,7 +662,7 @@ <p>If the system identifier is a URL, the parser must resolve it fully before passing it to the application.</p> -<p><var>entity</var> is a hash with these properties:</p> +<p><var>entity</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -722,7 +717,7 @@ <p>If the system identifier is a URL, the SAX parser must resolve it fully before reporting it to the application.</p> -<p><var>entity</var> is a hash with these properties:</p> +<p><var>entity</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -749,9 +744,8 @@ renders any continuation of parsing impossible. </p> -<p>All error handlers receive a hash, <var>exception</var>, with the -properties defined in <a -href="sax-2.0.html#Exceptions">Exceptions</a>.</p> +<p>All error handlers receive a hash reference, <var>exception</var>, with +the properties defined in <a href="sax-2.0.html#Exceptions">Exceptions</a>.</p> <p> <dl><dt><b><tt class='function'>warning</tt></b>(<var>exception</var>)</dt> @@ -760,7 +754,7 @@ <p>SAX parsers will use this method to report conditions that are not errors or fatal errors as defined by the XML 1.0 recommendation. The -default behaviour is to take no action.</p> +default behavior is to take no action.</p> The SAX parser must continue to provide normal parsing events after invoking this method: it should still be possible for the application @@ -774,7 +768,7 @@ <p>This corresponds to the definition of "error" in section 1.2 of the W3C XML 1.0 Recommendation. For example, a validating parser would use this callback to report the violation of a validity constraint. The -default behaviour is to take no action.</p> +default behavior is to take no action.</p> The SAX parser must continue to provide normal parsing events after invoking this method: it should still be possible for the application @@ -828,7 +822,7 @@ within the <tt>start</tt>/<tt>end_document()</tt> events from Content Handler and before the first <tt>start_element()</tt> event.</p> -<p><var>dtd</var> is a hash with these properties:</p> +<p><var>dtd</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -868,7 +862,7 @@ <tt>skipped_entity()</tt> event, which is part of the ContentHandler interface.</p> -<p><var>entity</var> is a hash with these properties:</p> +<p><var>entity</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -884,7 +878,7 @@ <dd> Report the end of an entity. -<p><var>entity</var> is a hash with these properties:</p> +<p><var>entity</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -922,7 +916,7 @@ document element, including comments in the external DTD subset (if read).</p> -<p><var>comment</var> is a hash with these properties:</p> +<p><var>comment</var> is a hash reference with these properties:</p> <blockquote> <table> @@ -971,15 +965,15 @@ check the handlers for what methods they support. Note however that using XML::SAX::Base as your base class for Drivers and Filters will make your code a lot simpler, less error prone, and probably much more - correct with regard to this spec. Only reimplement that functionality + correct with regard to this spec. Only re-implement that functionality if you really need to. </li> -<li>The Attribute, InputSource, and SAXException (XML::SAX::Exception) -classes are only described as hashes (see below).</li> +<li>The Attributes, InputSource, and SAXException (XML::SAX::Exception) +classes are only described as hash references (see below).</li> -<li>Handlers are passed a hash (Node) containing properties as an -argument instead of positional arguments.</li> +<li>Handlers are passed a hash reference (Node) containing properties +as an argument instead of positional arguments.</li> <li><tt>parse()</tt> methods return the value returned by calling the <tt>end_document()</tt> handler.</li> Index: sax-2.0.html =================================================================== RCS file: /cvsroot/perl-xml/libxml-perl/doc/sax-2.0.html,v retrieving revision 1.6 retrieving revision 1.7 diff -u -d -r1.6 -r1.7 --- sax-2.0.html 21 Jan 2002 19:21:43 -0000 1.6 +++ sax-2.0.html 4 Feb 2004 17:01:58 -0000 1.7 @@ -84,12 +84,17 @@ get the events one is interested in. </p> +<p>If you generate SAX events, data are required to be passed to +handler methods with all properties defined in this document +unless otherwise specified. +</p> + <p> <dl><dt><b><tt class='function'>parse</tt></b>(<var>uri</var> [, <var>options</var>])</dt> <dd> Parses the XML instance identified by <var>uri</var> (a system -identifier). <var>options</var> can be a list of option, value pairs -or a hash. Options include <tt>Handler</tt>, features and properties, +identifier). <var>options</var> can be a list of options, value pairs +or a hash (reference). Options include <tt>Handler</tt>, features and properties, and advanced SAX parser options. <tt>parse()</tt> returns the result of calling the <tt>end_document()</tt> handler. The options supported by <tt>parse()</tt> may vary slightly if what is being "parsed" isn't @@ -166,7 +171,7 @@ element is empty). All of the element's content will be reported, in order, before the corresponding <tt>end_element()</tt> event.</p> -<var>element</var> is a hash with these properties: +<var>element</var> is a hash reference with these properties: <blockquote> <table> @@ -191,10 +196,10 @@ </table> </blockquote> -<tt>Attributes</tt> is a hash keyed by JClark namespace notation. That -is, the keys are of the form "{NamespaceURI}LocalName". If the attribute -has no NamespaceURI, then it is simply "{}LocalName". Each attribute is -a hash with these properties: +<tt>Attributes</tt> is a reference to hash keyed by JClark namespace +notation. That is, the keys are of the form "{NamespaceURI}LocalName". +If the attribute has no NamespaceURI, then it is simply "{}LocalName". +Each attribute is a hash reference with these properties: <blockquote> <table> @@ -225,7 +230,7 @@ class='function'>end_element()</tt> event (even when the element is empty).</p> -<var>element</var> is a hash with these properties: +<var>element</var> is a hash reference with these properties: <blockquote> <table> @@ -260,7 +265,7 @@ of the characters in any single event must come from the same external entity so that the Locator provides useful information).</p> -<p><var>characters</var> is a hash with this property:</p> +<p><var>characters</var> is a hash reference with this property:</p> <blockquote> <table> @@ -285,7 +290,7 @@ characters in any single event must come from the same external entity, so that the Locator provides useful information.</p> -<p><var>characters</var> is a hash with this property:</p> +<p><var>characters</var> is a hash reference with this property:</p> <blockquote> <table> @@ -316,8 +321,8 @@ on the SAX parser (see advanced SAX below).</p> <p> - Exception values (<tt>$@</tt>) in SAX are hashes blessed into the - package that defines their type, and have the following properties: + Exception values (<tt>$@</tt>) in SAX are hash references blessed + into the package that defines their type, and have the following properties: </p> <blockquote> |
