Commits

pa...@9ae0c189-cd1f-4510-a509-f4891f5cf20d  committed e1a6494

updated documentation

  • Participants
  • Parent commits c525343

Comments (0)

Files changed (2)

 Revision history for Perl extension XML::LibXML
 
 1.62pre
-   - reader API (most of the code contributed by Heiko Klein)
+   - interface to libxml2's pull-parser XML::LibXML::Reader
+     (initiated by Heiko Klein)
    - make error messages intended to the user report the line of the
      application call rather than that of the internal XS call
    - XML::LibXML::Attr->serializeContent added (convenience function)

File docs/libxml.dbk

             </author>
         </authorgroup>
 
-        <edition>1.61</edition>
+        <edition>1.62</edition>
 
         <copyright>
             <year>2001-2006</year>
                 </varlistentry>
 
                 <varlistentry>
+                    <term>XML::LibXML::Reader</term>
+
+                    <listitem>
+                        <para>Reading XML with a pull-parser</para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
                     <term>XML::LibXML::Document</term>
 
                     <listitem>
                 </varlistentry>
 
                 <varlistentry>
+                    <term>XML::LibXML::Schema</term>
+
+                    <listitem>
+                        <para>XML::LibXML frontend for W3C Schema schema validation</para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>XML::LibXML::XPathContext</term>
+                    <listitem>
+                        <para>API for evaluating XPath expressions</para>
+                    </listitem>
+                </varlistentry>
+
+
+                <varlistentry>
                     <term>XML::LibXMLguts</term>
-
                     <listitem>
                         <para>Internal of the Perl Layer for libxml2 (not done yet)</para>
                     </listitem>
                             <funcsynopsisinfo>$Version_String = XML::LibXML::LIBXML_DOTTED_VERSION;</funcsynopsisinfo>
                         </funcsynopsis>
 
-                        <para>Returns the Versionstring of the libxml2 version XML::LibXML was compiled for. This will be "2.6.2" for "libxml2
+                        <para>Returns the version string of the
+                        libxml2 version XML::LibXML was compiled
+                        for. This will be "2.6.2" for "libxml2
                         2.6.2".</para>
                     </listitem>
                 </varlistentry>
                             <funcsynopsisinfo>$Version_ID = XML::LibXML::LIBXML_VERSION;</funcsynopsisinfo>
                         </funcsynopsis>
 
-                        <para>Returns the version id of the libxml2 version XML::LibXML was compiled for. This will be "20602" for "libxml2
-                        2.6.2". Don't mix this version id with $XML::LibXML::VERSION. The latter contains the version of XML::LibXML itself while the
-                        first contains the version of libxml2 XML::LibXML was compiled for.</para>
+                        <para>Returns the version id of the libxml2
+                        version XML::LibXML was compiled for. This
+                        will be "20602" for "libxml2 2.6.2". Don't mix
+                        this version id with
+                        $XML::LibXML::VERSION. The latter contains the
+                        version of XML::LibXML itself while the first
+                        contains the version of libxml2 XML::LibXML
+                        was compiled for.</para>
                     </listitem>
                 </varlistentry>
                 <varlistentry>
                             <para>Similar to parse_file() but parses HTML (strict) documents;
 		               $htmlfile can be filename or URL.
                             </para>
-                            <para>An optional second argument can be used to pass some options to the
-                               HTML parser as a HASH reference. Possible options are:
-                               Possible options are:
-		               encoding and URI for libxml2 < 2.6.27, and for later versions of libxml2 additionally:
-                               recover, suppress_errors, suppress_warnings, pedantic_parser,
-		               no_blanks, and no_network.
+                            <para>An optional second argument can be
+                               used to pass some options to the HTML
+                               parser as a HASH reference. Possible
+                               options are: Possible options are:
+                               encoding and URI for libxml2 &lt;
+                               2.6.27, and for later versions of
+                               libxml2 additionally: recover,
+                               suppress_errors, suppress_warnings,
+                               pedantic_parser, no_blanks, and
+                               no_network.
 	                    </para>
                         </listitem>
                     </varlistentry>
                             </funcsynopsis>
                             <para>Similar to parse_fh() but parses HTML (strict) streams.</para>
                             <para>
-                               An optional second argument can be used to pass some options to the
-                               HTML parser as a HASH reference.
-                               Possible options are:
-		               encoding and URI for libxml2 < 2.6.27, and for later versions of libxml2 additionally:
-                               recover, suppress_errors, suppress_warnings, pedantic_parser,
-		               no_blanks, and no_network. Note: encoding option may not work correctly
-                               with this function in libxml2 < 2.6.27 if the HTML file declares charset
-                               using a META tag.
+                               An optional second argument can be used
+                               to pass some options to the HTML parser
+                               as a HASH reference.  Possible options
+                               are: encoding and URI for libxml2 &lt;
+                               2.6.27, and for later versions of
+                               libxml2 additionally: recover,
+                               suppress_errors, suppress_warnings,
+                               pedantic_parser, no_blanks, and
+                               no_network. Note: encoding option may
+                               not work correctly with this function
+                               in libxml2 &lt; 2.6.27 if the HTML file
+                               declares charset using a META tag.
 	                    </para>
                         </listitem>
                     </varlistentry>
                             <para>Similar to parse_string() but parses HTML (strict) strings.</para>
                             <para>An optional second argument can be used to pass some options to the
                                HTML parser as a HASH reference. Possible options are:
-		               encoding and URI for libxml2 < 2.6.27, and for later versions of libxml2 additionally:
+		               encoding and URI for libxml2 &lt; 2.6.27, and for later versions of libxml2 additionally:
                                recover, suppress_errors, suppress_warnings, pedantic_parser,
 		               no_blanks, and no_network.
 	                    </para>
 
         <titleabbrev>XML::LibXML::Node</titleabbrev>
 
-        <para>XML::LibXML::Node defines functions that are common to all Node Types. A LibXML::Node should never be created standalone, but as an instance of a
-        high level class such as LibXML::Element or LibXML::Text. The class itself should provide only common functionality. In XML::LibXML each node is part
-        either of a document or a document-fragment. Because of this there is no node without a parent. This may causes confusion with "unbound" nodes.</para>
+        <para>XML::LibXML::Node defines functions that are common to
+        all Node Types. A LibXML::Node should never be created
+        standalone, but as an instance of a high level class such as
+        LibXML::Element or LibXML::Text. The class itself should
+        provide only common functionality. In XML::LibXML each node is
+        part either of a document or a document-fragment. Because of
+        this there is no node without a parent. This may causes
+        confusion with "unbound" nodes.</para>
 
         <variablelist>
             <varlistentry>
                         <funcsynopsisinfo>$name = $node-&gt;nodeName;</funcsynopsisinfo>
                     </funcsynopsis>
 
-                    <para>Returns the node's name. This Function is aware of namesaces and returns the full name of the current node (<function>prefix:localname</function>)</para>
+                    <para>Returns the node's name. This function is
+	              aware of namespaces and returns the full name of
+                      the current node (<function>prefix:localname</function>).
+	            </para>
+                    <para>Since 1.62 this function also returns the correct
+	              DOM names for node types with constant names, namely:
+                      #text, #cdata-section, #comment, #document, 
+	              #document-fragment.
+	            </para>
                 </listitem>
             </varlistentry>
         
-
-        
             <varlistentry>
                 <term>setNodeName</term>
 
                         <funcsynopsisinfo>$bool = $node-&gt;isSameNode( $other_node );</funcsynopsisinfo>
                     </funcsynopsis>
 
-                    <para>returns TRUE (1) if the given nodes refer to the same node structure, otherwise FALSE (0) is returned.</para>
+                    <para>returns TRUE (1) if the given nodes refer to
+                    the same node structure, otherwise FALSE (0) is
+                    returned.</para>
                 </listitem>
             </varlistentry>
         
                         <funcsynopsisinfo>$newnode =$node-&gt;cloneNode( $deep );</funcsynopsisinfo>
                     </funcsynopsis>
 
-                    <para><emphasis>cloneNode</emphasis> creates a copy of <function>$node</function>. When $deep is set to 1 (true) the function will copy all
-                    childnodes as well. If $deep is 0 only the current node will be copied.</para>
-
-                    <para><emphasis>cloneNode</emphasis> will not copy any namespace information if it is not run recursivly.</para>
+                    <para><emphasis>cloneNode</emphasis> creates a
+                    copy of <function>$node</function>. When $deep is
+                    set to 1 (true) the function will copy all
+                    childnodes as well. If $deep is 0 only the current
+                    node will be copied. Note that in case of element,
+                    attributes are copied iven if $deep is 0.
+                    </para>
+                    <para>Note that the behavior of this function for $deep=0
+	              has changed in 1.62 in order to be consistent with the DOM spec
+                      (in older versions attributes and namespace information
+                      was not copied for elements).</para>
                 </listitem>
             </varlistentry>
         
       </para>
     </sect1>
   </chapter>
-
-
+  <chapter>
+    <title>XML::LibXML::Reader - interface to libxml2 pull parser</title>
+    <titleabbrev>XML::LibXML::Reader</titleabbrev>
+    <sect1>
+      <title>Synopsis</title>
+      <programlisting>use XML::LibXML::Reader;</programlisting>
+      <programlisting>$reader = new XML::LibXML::Reader("file.xml")
+       or die "cannot read file.xml\n";
+while ($reader-&gt;read) {
+  processNode($reader);
+}</programlisting>
+      <programlisting>
+sub processNode {
+    $reader = shift;
+    printf "%d %d %s %d\n", ($reader-&gt;depth,
+                             $reader-&gt;nodeType,
+                             $reader-&gt;name,
+                             $reader-&gt;isEmptyElement);
+}
+</programlisting>
+      <para>or</para>
+      <programlisting>
+  $reader = new XML::LibXML::Reader("file.xml")
+       or die "cannot read file.xml\n";
+  $reader-&gt;preservePattern('//table/tr');
+  $reader-&gt;finish;
+  print $reader-&gt;document-&gt;toString(1);
+</programlisting>
+    </sect1>
+    <sect1>
+      <title>DESCRIPTION</title>
+      <para>This is a perl interface to libxml2's pull-parser implementation
+	xmlTextReader
+	<emphasis>http://xmlsoft.org/html/libxml-xmlreader.html</emphasis>. 
+	Pull-parser (StAX in Java, XmlReader in C#) use an iterator
+	approach to parse a xml-file. They are easier to program than
+	event-based parser (SAX) and much more lightweight than
+	tree-based parser (DOM), which load the complete tree into
+	memory.</para>
+      <para>The Reader acts as a cursor going forward on the document
+	stream and stopping at each node in the way. At every point
+	DOM-like methods of the Reader object allow to examine the
+	current node (name, namespace, attributes, etc.)</para>
+      <para>The user's code keeps control of the progress and simply
+	calls the <literal>read()</literal> function repeatedly to
+	progress to the next node in the document order. Other
+	functions provide means for skipping complete subtrees, or
+	nodes until a specific element, etc.</para>
+      <para>At every time, only a very limitted portion of the
+	document is kept in the memory, which makes the API more
+	memory-efficient than using DOM. However, it is also possible
+	to mix Reader with DOM. At every point the user may copy the
+	current node (optionally expanded into a complete subtree)
+	from the processed document to another DOM tree, or to
+	instruct the Reader to collect sub-document in form of a DOM
+	tree consisting of selected nodes.</para>
+      <para>Reader API also supports namespaces, xml:base, entity
+	handling, and DTD validation. Schema and RelaxNG validation
+	support will probably be added in some later revision of the
+	Perl interface.</para>
+      <para>The naming of methods compared to libxml2 and C#
+	XmlTextReader has been changed slightly to match the
+	conventions of XML::LibXML. Some functions have been changed
+	or added with respect to the C interface.</para>
+    </sect1>
+    <sect1>
+      <title>CONSTRUCTOR</title>
+      <para>Depending on the XML source, the Reader object can be created with either of:</para>
+      <programlisting>
+  my $reader = XML::LibXML::Reader-&gt;new( location =&gt; "file.xml", ... );
+  my $reader = XML::LibXML::Reader-&gt;new( string =&gt; $xml_string, ... );
+  my $reader = XML::LibXML::Reader-&gt;new( IO =&gt; $file_handle, ... );
+  my $reader = XML::LibXML::Reader-&gt;new( DOM =&gt; $dom, ... );
+</programlisting>
+      <para>where ... are (optional) reader options described below in Parser options.
+	The constructor recognizes the following XML sources:</para>
+      <sect2>
+        <title>Source specification</title>
+        <variablelist>
+          <varlistentry>
+            <term>location</term>
+            <listitem>
+              <para>Read XML from a local file or URL.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>string</term>
+            <listitem>
+              <para>Read XML from a string.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>IO</term>
+            <listitem>
+              <para>Read XML a Perl IO filehandle.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>FD</term>
+            <listitem>
+              <para>Read XML from a file descriptor (bypasses Perl I/O
+		layer, only applicable to filehandles for regular
+		files or pipes). Possibly faster than IO.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>DOM</term>
+            <listitem>
+              <para>Use reader API to walk through a preparsed
+		XML::LibXML::Document.</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </sect2>
+      <sect2>
+        <title>Parsing options</title>
+        <variablelist>
+          <varlistentry>
+            <term>URI</term>
+            <listitem>
+              <para>can be used to provide baseURI when parsing
+		strings or filehandles.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>encoding</term>
+            <listitem>
+              <para>override document encoding.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>RelaxNG</term>
+            <listitem>
+              <para>can be used to pass either a XML::LibXML::RelaxNG
+		object or a filename or URL of a RelaxNG schema to the
+		constructor. The schema is then used to validate the
+		document as it is processed.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>Schema</term>
+            <listitem>
+              <para>can be used to pass either a XML::LibXML::Schema
+		object or a filename or URL of a W3C XSD schema to the
+		constructor. The schema is then used to validate the
+		document as it is processed.</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>recover</term>
+            <listitem>
+              <para>recover on errors (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>expand_entities</term>
+            <listitem>
+              <para>substitute entities (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>load_ext_dtd</term>
+            <listitem>
+              <para>load the external subset (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>complete_attributes</term>
+            <listitem>
+              <para>default DTD attributes (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>validation</term>
+            <listitem>
+              <para>validate with the DTD (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>suppress_errors</term>
+            <listitem>
+              <para>suppress error reports (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>suppress_warnings</term>
+            <listitem>
+              <para>suppress warning reports (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>pedantic_parser</term>
+            <listitem>
+              <para>pedantic error reporting (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>no_blanks</term>
+            <listitem>
+              <para>remove blank nodes (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>expand_xinclude</term>
+            <listitem>
+              <para>Implement XInclude substitition (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>no_network</term>
+            <listitem>
+              <para>Forbid network access (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>clean_namespaces</term>
+            <listitem>
+              <para>remove redundant namespaces declarations (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>no_cdata</term>
+            <listitem>
+              <para>merge CDATA as text nodes (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>no_xinclude_nodes</term>
+            <listitem>
+              <para>do not generate XINCLUDE START/END nodes (0 or 1)</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </sect2>
+    </sect1>
+    <sect1>
+      <title>METHODS CONTROLLING PARSING PROGRESS</title>
+<variablelist>
+        <varlistentry>
+          <term>read ()</term>
+          <listitem>
+            <para>Moves the position to the next node in the stream,
+	      exposing its properties.</para>
+            <para>Returns 1 if the node was read successfully, 0 if
+	      there is no more nodes to read, or -1 in case of
+	      error</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>readAttributeValue ()</term>
+          <listitem>
+            <para>Parses an attribute value into one or more Text and
+	      EntityReference nodes.</para>
+            <para>Returns 1 in case of success, 0 if the reader was not positionned on an attribute node or all the attribute values have been read, or -1 in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>readState ()</term>
+          <listitem>
+            <para>Gets the read state of the reader. Returns the state
+	      value, or -1 in case of error. The module exports
+	      constants for the Reader states, see STATES
+	      below.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>depth ()</term>
+          <listitem>
+            <para>The depth of the node in the tree, starts at 0 for
+	      the root node.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>next ()</term>
+          <listitem>
+            <para>Skip to the node following the current one in the
+	      document order while avoiding the subtree if any.
+	      Returns 1 if the node was read successfully, 0 if there
+	      is no more nodes to read, or -1 in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>nextElement (localname?,nsURI?)</term>
+          <listitem>
+            <para>Skip nodes following the current one in the document
+	      order until a specific element is reached. The element's
+	      name must be equal to a given localname if defined, and
+	      its namespace must equal to a given nsURI if defined.
+	      Either of the arguments can be undefined (or omitted, in
+	      case of the latter or both).</para>
+            <para>Returns 1 if the element was found, 0 if there is no more nodes to read, or -1 in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>skipSiblings ()</term>
+          <listitem>
+            <para>Skip all nodes on the same or lower level until the
+	      first node on a higher level is reached. In particular,
+	      if the current node occurs in an element, the reader
+	      stops at the end tag of the parent element, otherwise it
+	      stops at a node immediately following the parent
+	      node.</para>
+            <para>Returns 1 if successful, 0 if end of the document is reached, or -1 in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>nextSibling ()</term>
+          <listitem>
+            <para>It skips to the node following the current one in
+	      the document order while avoiding the subtree if
+	      any.</para>
+            <para>Returns 1 if the node was read successfully, 0 if
+	      there is no more nodes to read, or -1 in case of
+	      error</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>nextSiblingElement (name?,nsURI?)</term>
+          <listitem>
+            <para>Like nextElement but only processes sibling elements
+	      of the current node (moving forward using
+	      <literal>nextSibling ()</literal>  rather than
+	      <literal>read ()</literal>,  internally).</para>
+            <para>Returns 1 if the element was found, 0 if there is no
+	      more sibling nodes, or -1 in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>finish ()</term>
+          <listitem>
+            <para>Skip all remaining nodes in the document, reaching end of the document.</para>
+            <para>Returns 1 if successful, 0 in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>close ()</term>
+          <listitem>
+            <para>This method releases any resources allocated by the
+	      current instance and closes any underlying input. It
+	      returns 0 on failure and 1 on success. This method is
+	      automatically called by the destructor when the reader
+	      is forgotten, therefore you do not have to call it
+	      directly.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect1>
+    <sect1>
+      <title>METHODS EXTRACTING INFORMATION</title>
+<variablelist>
+        <varlistentry>
+          <term>name ()</term>
+          <listitem>
+            <para>Returns the qualified name of the current node, equal to (Prefix:)LocalName.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>nodeType ()</term>
+          <listitem>
+            <para>Returns the type of the current node. See NODE TYPES below.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>localName ()</term>
+          <listitem>
+            <para>Returns the local name of the node.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>prefix ()</term>
+          <listitem>
+            <para>Returns the prefix of the namespace associated with the node.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>namespaceURI ()</term>
+          <listitem>
+            <para>Returns the URI defining the namespace associated with the node.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>isEmptyElement ()</term>
+          <listitem>
+            <para>Check if the current node is empty, this is a bit
+	      bizarre in the sense that &lt;a/&gt; will be considered
+	      empty while &lt;a&gt;&lt;/a&gt; will not.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>hasValue ()</term>
+          <listitem>
+            <para>Returns true if the node can have a text value.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>value ()</term>
+          <listitem>
+            <para>Provides the text value of the node if present or undef if not available.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>readInnerXml ()</term>
+          <listitem>
+            <para>Reads the contents of the current node, including
+	      child nodes and markup. Returns a string containing the
+	      XML of the node's content, or undef if the current node
+	      is neither an element nor attribute, or has no child
+	      nodes.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>readOuterXml ()</term>
+          <listitem>
+            <para>Reads the contents of the current node, including
+	      child nodes and markup.</para>
+            <para>Returns a string containing the XML of the node
+	      including its content, or undef if the current node is
+	      neither an element nor attribute.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect1>
+    <sect1>
+      <title>METHODS EXTRACTING DOM NODES</title>
+<variablelist>
+        <varlistentry>
+          <term>document ()</term>
+          <listitem>
+            <para>Provides access to the document tree built by the
+	      reader. This function can be used to collect the
+	      preserved nodes (see <literal>preserveNode()</literal>
+	      and preservePattern).</para>
+            <para>CAUTION: Never use this function to modify the tree
+	      unless reading of the whole document is
+	      completed!</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>copyCurrentNode (deep)</term>
+          <listitem>
+            <para>This function is similar a DOM function
+	      <literal>copyNode()</literal>. It returns a copy of the
+	      currently processed node as a corresponding DOM object.
+	      Use deep = 1 to obtain the full subtree.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>preserveNode ()</term>
+          <listitem>
+            <para>This tells the XML Reader to preserve the current
+	      node in the document tree. A document tree consisting of
+	      the preserved nodes and their content can be obtained
+	      using the method <literal>document()</literal> once
+	      parsing is finished.</para>
+            <para>Returns the node or NULL in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>preservePattern (pattern,\%ns_map)</term>
+          <listitem>
+            <para>This tells the XML Reader to preserve all nodes
+	      matched by the pattern (which is a streaming XPath
+	      subset). A document tree consisting of the preserved
+	      nodes and their content can be obtained using the method
+	      <literal>document()</literal> once parsing is
+	      finished.</para>
+            <para>An optional second argument can be used to provide a
+	      HASH reference mapping prefixes used by the XPath to
+	      namespace URIs.</para>
+            <para>The XPath subset available with this function is
+	      described at</para>
+            <programlisting>http://www.w3.org/TR/xmlschema-1/#Selector</programlisting>
+            <para>and matches the production</para>
+            <programlisting>Path ::= ('.//')? ( Step '/' )* ( Step | '@' NameTest )</programlisting>
+            <para>Returns a positive number in case of success and -1
+	      in case of error</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect1>
+    <sect1>
+      <title>METHODS PROCESSING ATTRIBUTES</title>
+<variablelist>
+        <varlistentry>
+          <term>attributeCount ()</term>
+          <listitem>
+            <para>Provides the number of attributes of the current
+	      node.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>hasAttributes ()</term>
+          <listitem>
+            <para>Whether the node has attributes.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>getAttribute (name)</term>
+          <listitem>
+            <para>Provides the value of the attribute with the
+	      specified qualified name.</para>
+            <para>Returns a string containing the value of the
+	      specified attribute, or undef in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>getAttributeNs (localName, namespaceURI)</term>
+          <listitem>
+            <para>Provides the value of the specified
+	      attribute.</para>
+            <para>Returns a string containing the value of the
+	      specified attribute, or undef in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>getAttributeNo (no)</term>
+          <listitem>
+            <para>Provides the value of the attribute with the
+	      specified index relative to the containing
+	      element.</para>
+            <para>Returns a string containing the value of the
+	      specified attribute, or undef in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>isDefault ()</term>
+          <listitem>
+            <para>Returns true if the current attribute node was
+	      generated from the default value defined in the
+	      DTD.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>moveToAttribute (name)</term>
+          <listitem>
+            <para>Moves the position to the attribute with the
+	      specified local name and namespace URI.</para>
+            <para>Returns 1 in case of success, -1 in case of error, 0
+	      if not found</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>moveToAttributeNo (no)</term>
+          <listitem>
+            <para>Moves the position to the attribute with the
+	      specified index relative to the containing
+	      element.</para>
+            <para>Returns 1 in case of success, -1 in case of error, 0
+	      if not found</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>moveToAttributeNs (localName,namespaceURI)</term>
+          <listitem>
+            <para>Moves the position to the attribute with the
+	      specified local name and namespace URI.</para>
+            <para>Returns 1 in case of success, -1 in case of error, 0
+	      if not found</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>moveToFirstAttribute ()</term>
+          <listitem>
+            <para>Moves the position to the first attribute associated
+	      with the current node.</para>
+            <para>Returns 1 in case of success, -1 in case of error, 0
+	      if not found</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>moveToNextAttribute ()</term>
+          <listitem>
+            <para>Moves the position to the next attribute associated
+	      with the current node.</para>
+            <para>Returns 1 in case of success, -1 in case of error, 0
+	      if not found</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>moveToElement ()</term>
+          <listitem>
+            <para>Moves the position to the node that contains the
+	      current attribute node.</para>
+            <para>Returns 1 in case of success, -1 in case of error, 0
+	      if not moved</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>isNamespaceDecl ()</term>
+          <listitem>
+            <para>Determine whether the current node is a namespace
+	      declaration rather than a regular attribute.</para>
+            <para>Returns 1 if the current node is a namespace
+	      declaration, 0 if it is a regular attribute or other
+	      type of node, or -1 in case of error.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect1>
+    <sect1>
+      <title>OTHER METHODS</title>
+<variablelist>
+        <varlistentry>
+          <term>lookupNamespace (prefix)</term>
+          <listitem>
+            <para>Resolves a namespace prefix in the scope of the
+	      current element.</para>
+            <para>Returns a string containing the namespace URI to
+	      which the prefix maps or undef in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>encoding ()</term>
+          <listitem>
+            <para>Returns a string containing the encoding of the
+	      document or undef in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>standalone ()</term>
+          <listitem>
+            <para>Determine the standalone status of the document
+	      being read. Returns 1 if the document was declared to be
+	      standalone, 0 if it was declared to be not standalone,
+	      or -1 if the document did not specify its standalone
+	      status or in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>xmlVersion ()</term>
+          <listitem>
+            <para>Determine the XML version of the document being
+	      read. Returns a string containing the XML version of the
+	      document or undef in case of error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>baseURI ()</term>
+          <listitem>
+            <para>The base URI of the node. See the XML Base W3C
+	      specification.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>isValid ()</term>
+          <listitem>
+            <para>Retrieve the validity status from the parser.</para>
+            <para>Returns 1 if valid, 0 if no, and -1 in case of
+	      error.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>xmlLang ()</term>
+          <listitem>
+            <para>The xml:lang scope within which the node
+	      resides.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>lineNumber ()</term>
+          <listitem>
+            <para>Provide the line number of the current parsing
+	      point. Available if libxml2 &gt;= 2.6.17.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>columnNumber ()</term>
+          <listitem>
+            <para>Provide the column number of the current parsing
+	      point. Available if libxml2 &gt;= 2.6.17.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>byteConsumed ()</term>
+          <listitem>
+            <para>This function provides the current index of the
+	      parser relative to the start of the current entity. This
+	      function is computed in bytes from the beginning
+	      starting at zero and finishing at the size in bytes of
+	      the file if parsing a file. The function is of constant
+	      cost if the input is UTF-8 but can be costly if run on
+	      non-UTF-8 input. Available if libxml2 &gt;=
+	      2.6.18.</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>setParserProp (prop =&gt; value, ...)</term>
+          <listitem>
+            <para>Change the parser processing behaviour by changing
+	      some of its internal properties. The following
+	      properties are available with this function:
+	      ``load_ext_dtd'', ``complete_attributes'',
+	      ``validation'', ``expand_entities''.</para>
+            <para>Since some of the properties can only be changed
+	      before any read has been done, it is best to set the
+	      parsing properties at the constructor.</para>
+            <para>Returns 0 if the call was successful, or -1 in case
+	      of error</para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term>getParserProp (prop)</term>
+          <listitem>
+            <para>Get value of an parser internal property. The
+	      following property names can be used: ``load_ext_dtd'',
+	      ``complete_attributes'', ``validation'',
+	      ``expand_entities''.</para>
+            <para>Returns the value, usually 0 or 1, or -1 in case of
+	      error.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </sect1>
+    <sect1>
+      <title>DESTRUCTION</title>
+      <para>XML::LibXML takes care of the reader object destruction
+	when the last reference to the reader object goes out of
+	scope. The document tree is preserved, though, if either of
+	$reader-&gt;document or $reader-&gt;preserveNode was used and
+	references to the document tree exist.</para>
+    </sect1>
+    <sect1>
+      <title>NODE TYPES</title>
+      <para>The reader interface provides the following constants for
+	node types (the constant symbols are exported by default or if
+	tag <literal>:types</literal> is used).</para>
+      <programlisting>
+  XML_READER_TYPE_NONE                    =&gt; 0
+  XML_READER_TYPE_ELEMENT                 =&gt; 1
+  XML_READER_TYPE_ATTRIBUTE               =&gt; 2
+  XML_READER_TYPE_TEXT                    =&gt; 3
+  XML_READER_TYPE_CDATA                   =&gt; 4
+  XML_READER_TYPE_ENTITY_REFERENCE        =&gt; 5
+  XML_READER_TYPE_ENTITY                  =&gt; 6
+  XML_READER_TYPE_PROCESSING_INSTRUCTION  =&gt; 7
+  XML_READER_TYPE_COMMENT                 =&gt; 8
+  XML_READER_TYPE_DOCUMENT                =&gt; 9
+  XML_READER_TYPE_DOCUMENT_TYPE           =&gt; 10
+  XML_READER_TYPE_DOCUMENT_FRAGMENT       =&gt; 11
+  XML_READER_TYPE_NOTATION                =&gt; 12
+  XML_READER_TYPE_WHITESPACE              =&gt; 13
+  XML_READER_TYPE_SIGNIFICANT_WHITESPACE  =&gt; 14
+  XML_READER_TYPE_END_ELEMENT             =&gt; 15
+  XML_READER_TYPE_END_ENTITY              =&gt; 16
+  XML_READER_TYPE_XML_DECLARATION         =&gt; 17
+</programlisting>
+    </sect1>
+    <sect1>
+      <title>STATES</title>
+      <para>The following constants represent the values returned by
+	<literal>readState()</literal>. They are exported by default,
+	or if tag <literal>:states</literal> is used:</para>
+      <programlisting>
+  XML_READER_NONE      =&gt; -1
+  XML_READER_START     =&gt;  0
+  XML_READER_ELEMENT   =&gt;  1
+  XML_READER_END       =&gt;  2
+  XML_READER_EMPTY     =&gt;  3
+  XML_READER_BACKTRACK =&gt;  4
+  XML_READER_DONE      =&gt;  5
+  XML_READER_ERROR     =&gt;  6
+</programlisting>
+    </sect1>
+    <sect1>
+      <title>VERSION</title>
+      <para>0.02</para>
+    </sect1>
+    <sect1>
+      <title>AUTHORS</title>
+      <para>Heiko Klein, &lt;H.Klein@gmx.net&lt;gt&gt; and Petr Pajas,
+	&lt;pajas@matfyz.cz&lt;gt&gt;</para>
+    </sect1>
+    <sect1>
+      <title>SEE ALSO</title>
+      <para>http://xmlsoft.org/html/libxml-xmlreader.html</para>
+      <para>http://dotgnu.org/pnetlib-doc/System/Xml/XmlTextReader.html</para>
+    </sect1>
+  </chapter>
 </book>