XML-LibXML

 view release on metacpan or  search on metacpan

docs/libxml.dbk  view on Meta::CPAN

              <para>pedantic error reporting; possible values are 0 and 1</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>no_blanks</term>
            <listitem>
	      <para>/parser, html, reader/</para>
              <para>remove blank nodes; possible values are 0 and 1</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>no_defdtd</term>
            <listitem>
	      <para>/html/</para>
              <para>do not add a default DOCTYPE; possible values are 0 and 1</para>
              <para>the default is (0) to add a DTD when the input html lacks one</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>expand_xinclude or xinclude</term>
            <listitem>
	      <para>/parser, reader/</para>
              <para>Implement XInclude substitution; possible values are 0 and 1</para>
              <para>Expands XInclude tags immediately while parsing the document.
		Note that the parser will use the URI resolvers installed
		via <function>XML::LibXML::InputCallback</function> to parse the included document (if any).</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>no_xinclude_nodes</term>
            <listitem>
	      <para>/parser, reader/</para>
              <para>do not generate XINCLUDE START/END nodes; possible values are 0 and 1</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>no_network</term>
            <listitem>
	      <para>/parser, html, reader/</para>
              <para>Forbid network access; possible values are 0 and 1</para>
              <para>If set to true, all
                attempts to fetch non-local resources (such as
                DTD or external entities) will fail (unless
                custom callbacks are defined).</para>
	      <para>It may be
                necessary to use the flag <literal>recover</literal> for
                processing documents requiring such resources
                while networking is off.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>clean_namespaces</term>
            <listitem>
	      <para>/parser, reader/</para>
              <para>remove redundant namespaces declarations during parsing; possible values are 0 and 1.
	      </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>no_cdata</term>
            <listitem>
	      <para>/parser, html, reader/</para>
              <para>merge CDATA as text nodes; possible values are 0 and 1</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>no_basefix</term>
            <listitem>
	      <para>/parser, reader/</para>
              <para>not fixup XINCLUDE xml#base URIS; possible values are 0 and 1</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>huge</term>
            <listitem>
	      <para>/parser, html, reader/</para>
              <para>relax any hardcoded limit from the parser; possible values are 0 and 1. Unless specified,
		XML::LibXML sets this option to 0.</para>
              <para>Note: the default value for this option was changed to protect against denial
                of service through entity expansion attacks.  Before enabling the option ensure
                you have taken alternative measures to protect your application against this type
                of attack.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>gdome</term>
            <listitem>
	      <para>/parser/</para>
              <para>THIS OPTION IS EXPERIMENTAL!</para>
              <para>Although quite powerful, XML::LibXML's DOM implementation is incomplete with respect to
		the DOM level 2 or level 3 specifications.
                XML::GDOME is based on libxml2 as well, and provides a rather complete DOM implementation by wrapping libgdome.
		This flag allows you to make
                use of XML::LibXML's full parser options and XML::GDOME's DOM implementation at the same time.</para>
              <para>To make use of this function, one has to install libgdome and configure XML::LibXML to use this library.
		For this you need to rebuild XML::LibXML!</para>
	      <para>Note: this feature was not seriously tested in recent XML::LibXML releases.</para>
            </listitem>
	  </varlistentry>
	</variablelist>
	    <para>For compatibility with XML::LibXML versions prior to 1.70,
	      the following methods are also supported for querying and setting the corresponding parser options
	      (if called without arguments, the methods return
	      the current value of the corresponding parser options; with an argument sets the option to a given value):
	    </para>
	    <programlisting>$parser->validation();
$parser->recover();
$parser->pedantic_parser();
$parser->line_numbers();
$parser->load_ext_dtd();
$parser->complete_attributes();
$parser->expand_xinclude();
$parser->gdome_dom();
$parser->clean_namespaces();
$parser->no_network();</programlisting>
	    <para>The following obsolete methods trigger parser options in some
	      special way:</para>
	    <variablelist>
                <varlistentry>
                    <term>recover_silently</term>

docs/libxml.dbk  view on Meta::CPAN

                        <funcsynopsisinfo>$text = $dom-&gt;createTextNode( $content_text );</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>As an equivalent of <emphasis>createElement</emphasis>, but it creates a <emphasis>Text Node</emphasis> bound to the DOM.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>createComment</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$comment = $dom-&gt;createComment( $comment_text );</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>As an equivalent of <emphasis>createElement</emphasis>, but it creates a <emphasis>Comment Node</emphasis> bound to the DOM.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>createAttribute</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$attrnode = $doc-&gt;createAttribute($name [,$value]);</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>Creates a new Attribute node.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>createAttributeNS</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$attrnode = $doc-&gt;createAttributeNS( namespaceURI, $name [,$value] );</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>Creates an Attribute bound to a namespace.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>createDocumentFragment</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$fragment = $doc-&gt;createDocumentFragment();</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>This function creates a DocumentFragment.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>createCDATASection</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$cdata = $dom-&gt;createCDATASection( $cdata_content );</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>Similar to createTextNode and createComment, this function creates a CDataSection bound to the current DOM.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>createProcessingInstruction</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>my $pi = $doc-&gt;createProcessingInstruction( $target, $data );</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>create a processing instruction node.</para>

                    <para>Since this method is quite long one may use its short form <emphasis>createPI()</emphasis>.</para>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>createEntityReference</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>my $entref = $doc-&gt;createEntityReference($refname);</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>If a document has a DTD specified, one can create entity references by using this function. If one wants to add a entity reference to
                    the document, this reference has to be created by this function.</para>

                    <para>An entity reference is unique to a document and cannot be passed to other documents as other nodes can be passed.</para>

                    <para><emphasis>NOTE:</emphasis> A text content containing something that looks like an entity reference, will not be expanded to a real
                    entity reference unless it is a predefined entity</para>

                    <programlisting> my $string = "&amp;foo;";
 $some_element-&gt;appendText( $string );
 print $some_element-&gt;textContent; # prints "&amp;amp;foo;"</programlisting>
                </listitem>
            </varlistentry>

            <varlistentry>
                <term>createInternalSubset</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$dtd = $document-&gt;createInternalSubset( $rootnode, $public, $system);</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>This function creates and adds an internal subset to the given document. Because the function automatically adds the DTD to the document
                    there is no need to add the created node explicitly to the document.</para>

                    <programlisting> my $document = XML::LibXML::Document-&gt;new();
 my $dtd      = $document-&gt;createInternalSubset( "foo", undef, "foo.dtd" );</programlisting>

                    <para>will result in the following XML document:</para>

                    <programlisting>&lt;?xml version="1.0"?&gt;
 &lt;!DOCTYPE foo SYSTEM "foo.dtd"&gt;                    </programlisting>

docs/libxml.dbk  view on Meta::CPAN

                    <funcsynopsis>
                        <funcsynopsisinfo>$dom-&gt;indexElements();</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>This function causes libxml2 to stamp all elements in a document with their document position index which considerably speeds up XPath
                    queries for large documents. It should only be used with static documents that won't be further changed by any DOM methods, because once
                    a document is indexed, XPath will always prefer the index to other methods of determining the document order of nodes. XPath could therefore
                    return improperly ordered node-lists when applied on a document that has been changed after being indexed. It is of course possible to use
                    this method to re-index a modified document before using it with XPath again. This function is not a part of the DOM specification.</para>

                    <para>This function returns number of elements indexed, -1 if error occurred, or -2 if this feature is not available in the running libxml2.</para>
                </listitem>
            </varlistentry>
        </variablelist>
      </sect1>
    </chapter>

    <chapter id="XML-LibXML-Node">
        <title>Abstract Base Class of XML::LibXML Nodes</title>

        <titleabbrev>XML::LibXML::Node</titleabbrev>
        <sect1>
            <title>Synopsis</title>
            <programlisting>use XML::LibXML;</programlisting>
        </sect1>
        <sect1>
            <title>Description</title>

        <para>XML::LibXML::Node defines functions that are common to
        all Node Types. An XML::LibXML::Node should never be created
        standalone, but as an instance of a high level class such as
        XML::LibXML::Element or XML::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>
	</sect1>
        <sect1>
            <title>Methods</title>
		    <para>
	      Many functions listed here are
	      extensively documented in the <ulink url="http://www.w3.org/TR/DOM-Level-3-Core/">DOM Level 3 specification</ulink>. Please refer to
	      the specification for extensive documentation.
	    </para>

        <variablelist>
            <varlistentry>
                <term>nodeName</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$name = $node-&gt;nodeName;</funcsynopsisinfo>
                    </funcsynopsis>

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

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$node-&gt;setNodeName( $newName );</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>In very limited situations, it is useful to change a nodes name. In the DOM specification this should throw an error. This Function is
                    aware of namespaces.</para>
                </listitem>
            </varlistentry>



            <varlistentry>
                <term>isSameNode</term>

                <listitem>
                    <funcsynopsis>
                        <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>
                </listitem>
            </varlistentry>



            <varlistentry>
                <term>isEqual</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$bool = $node-&gt;isEqual( $other_node );</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>deprecated version of isSameNode().</para>

                    <para><emphasis>NOTE</emphasis> isEqual will change behaviour to follow the DOM specification</para>
                </listitem>
            </varlistentry>



            <varlistentry>
                <term>unique_key</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$num = $node-&gt;unique_key;</funcsynopsisinfo>
                    </funcsynopsis>

docs/libxml.dbk  view on Meta::CPAN

	</sect1>
        <sect1>
            <title>Methods</title>
	  <para>
	    The class inherits from <xref linkend="XML-LibXML-Node"/>.
	    The documentation for Inherited methods is not listed here.
	  </para>
	  <para>
	    Many functions listed here are
	    extensively documented in the <ulink url="http://www.w3.org/TR/DOM-Level-3-Core/">DOM Level 3 specification</ulink>. Please refer to
	    the specification for extensive documentation.
	  </para>

        <variablelist>
            <varlistentry>
                <term>new</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$text = XML::LibXML::Text-&gt;new( $content ); </funcsynopsisinfo>
                    </funcsynopsis>

                    <para>The constructor of the class. It creates an unbound text node.</para>
                </listitem>
            </varlistentry>



            <varlistentry>
                <term>data</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$nodedata = $text-&gt;data;</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>Although there exists the <function>nodeValue</function> attribute in the Node class, the DOM specification defines data as a separate
                    attribute. <function>XML::LibXML</function> implements these two attributes not as different attributes, but as aliases, such as
                    <function>libxml2</function> does. Therefore</para>

                    <programlisting> $text-&gt;data;</programlisting>

                    <para>and</para>

                    <programlisting> $text-&gt;nodeValue;</programlisting>

                    <para>will have the same result and are not different entities.</para>
                </listitem>
            </varlistentry>



            <varlistentry>
                <term>setData($string)</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$text-&gt;setData( $text_content );</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>This function sets or replaces text content to a node. The node has to be of the type "text", "cdata" or
                    "comment".</para>
                </listitem>
            </varlistentry>



            <varlistentry>
                <term>substringData($offset,$length)</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$text-&gt;substringData($offset, $length);</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>Extracts a range of data from the node. (DOM Spec) This function takes the two parameters $offset and $length and returns the
                    sub-string, if available.</para>

                    <para>If the node contains no data or $offset refers to an non-existing string index, this function will return <emphasis>undef</emphasis>.
                    If $length is out of range <function>substringData</function> will return the data starting at $offset instead of causing an error.</para>
                </listitem>
            </varlistentry>



            <varlistentry>
                <term>appendData($string)</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$text-&gt;appendData( $somedata );</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>Appends a string to the end of the existing data. If the current text node contains no data, this function has the same effect as
                    <function>setData</function>.</para>
                </listitem>
            </varlistentry>



            <varlistentry>
                <term>insertData($offset,$string)</term>

                <listitem>
                    <funcsynopsis>
                        <funcsynopsisinfo>$text-&gt;insertData($offset, $string);</funcsynopsisinfo>
                    </funcsynopsis>

                    <para>Inserts the parameter $string at the given $offset of the existing data of the node. This operation will not remove existing data, but
                    change the order of the existing data.</para>

                    <para>The $offset has to be a positive value. If $offset is out of range, <function>insertData</function> will have the same behaviour as
                    <function>appendData</function>.</para>
                </listitem>
            </varlistentry>



            <varlistentry>
                <term>deleteData($offset, $length)</term>