--- /dev/null
+=head1 NAME
+
+XML::LibXML::Document - XML::LibXML DOM Document Class
+
+=head1 SYNOPSIS
+
+
+
+ use XML::LibXML;
+ # Only methods specific to Document nodes are listed here,
+ # see XML::LibXML::Node manpage for other methods
+
+ $dom = XML::LibXML::Document->new( $version, $encoding );
+ $dom = XML::LibXML::Document->createDocument( $version, $encoding );
+ $strURI = $doc->URI();
+ $doc->setURI($strURI);
+ $strEncoding = $doc->encoding();
+ $strEncoding = $doc->actualEncoding();
+ $doc->setEncoding($new_encoding);
+ $strVersion = $doc->version();
+ $doc->standalone
+ $doc->setStandalone($numvalue);
+ my $compression = $doc->compression;
+ $doc->setCompression($ziplevel);
+ $docstring = $dom->toString($format);
+ $c14nstr = $doc->toStringC14N($comment_flag, $xpath [, $xpath_context ]);
+ $ec14nstr = $doc->toStringEC14N($comment_flag, $xpath [, $xpath_context ], $inclusive_prefix_list);
+ $str = $doc->serialize($format);
+ $state = $doc->toFile($filename, $format);
+ $state = $doc->toFH($fh, $format);
+ $str = $document->toStringHTML();
+ $str = $document->serialize_html();
+ $bool = $dom->is_valid();
+ $dom->validate();
+ $root = $dom->documentElement();
+ $dom->setDocumentElement( $root );
+ $element = $dom->createElement( $nodename );
+ $element = $dom->createElementNS( $namespaceURI, $qname );
+ $text = $dom->createTextNode( $content_text );
+ $comment = $dom->createComment( $comment_text );
+ $attrnode = $doc->createAttribute($name [,$value]);
+ $attrnode = $doc->createAttributeNS( namespaceURI, $name [,$value] );
+ $fragment = $doc->createDocumentFragment();
+ $cdata = $dom->create( $cdata_content );
+ my $pi = $doc->createProcessingInstruction( $target, $data );
+ my $entref = $doc->createEntityReference($refname);
+ $dtd = $document->createInternalSubset( $rootnode, $public, $system);
+ $dtd = $document->createExternalSubset( $rootnode_name, $publicId, $systemId);
+ $document->importNode( $node );
+ $document->adoptNode( $node );
+ my $dtd = $doc->externalSubset;
+ my $dtd = $doc->internalSubset;
+ $doc->setExternalSubset($dtd);
+ $doc->setInternalSubset($dtd);
+ my $dtd = $doc->removeExternalSubset();
+ my $dtd = $doc->removeInternalSubset();
+ my @nodelist = $doc->getElementsByTagName($tagname);
+ my @nodelist = $doc->getElementsByTagNameNS($nsURI,$tagname);
+ my @nodelist = $doc->getElementsByLocalName($localname);
+ my $node = $doc->getElementById($id);
+ $dom->indexElements();
+
+=head1 DESCRIPTION
+
+The Document Class is in most cases the result of a parsing process. But
+sometimes it is necessary to create a Document from scratch. The DOM Document
+Class provides functions that conform to the DOM Core naming style.
+
+It inherits all functions from L<<<<<< XML::LibXML::Node >>>>>> as specified in the DOM specification. This enables access to the nodes besides
+the root element on document level - a C<<<<<< DTD >>>>>> for example. The support for these nodes is limited at the moment.
+
+While generally nodes are bound to a document in the DOM concept it is
+suggested that one should always create a node not bound to any document. There
+is no need of really including the node to the document, but once the node is
+bound to a document, it is quite safe that all strings have the correct
+encoding. If an unbound text node with an ISO encoded string is created (e.g.
+with $CLASS->new()), the C<<<<<< toString >>>>>> function may not return the expected result.
+
+To prevent such problems, it is recommended to pass all data to XML::LibXML
+methods as character strings (i.e. UTF-8 encoded, with the UTF8 flag on).
+
+
+=head1 METHODS
+
+Many functions listed here are extensively documented in the DOM Level 3 specification (L<<<<<< http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>). Please refer to the specification for extensive documentation.
+
+=over 4
+
+=item new
+
+ $dom = XML::LibXML::Document->new( $version, $encoding );
+
+alias for createDocument()
+
+
+=item createDocument
+
+ $dom = XML::LibXML::Document->createDocument( $version, $encoding );
+
+The constructor for the document class. As Parameter it takes the version
+string and (optionally) the encoding string. Simply calling I<<<<<< createDocument >>>>>>() will create the document:
+
+
+
+ <?xml version="your version" encoding="your encoding"?>
+
+Both parameter are optional. The default value for I<<<<<< $version >>>>>> is C<<<<<< 1.0 >>>>>>, of course. If the I<<<<<< $encoding >>>>>> parameter is not set, the encoding will be left unset, which means UTF-8 is
+implied.
+
+The call of I<<<<<< createDocument >>>>>>() without any parameter will result the following code:
+
+
+
+ <?xml version="1.0"?>
+
+Alternatively one can call this constructor directly from the XML::LibXML class
+level, to avoid some typing. This will not have any effect on the class
+instance, which is always XML::LibXML::Document.
+
+
+
+ my $document = XML::LibXML->createDocument( "1.0", "UTF-8" );
+
+is therefore a shortcut for
+
+
+
+ my $document = XML::LibXML::Document->createDocument( "1.0", "UTF-8" );
+
+
+=item URI
+
+ $strURI = $doc->URI();
+
+Returns the URI (or filename) of the original document. For documents obtained
+by parsing a string of a FH without using the URI parsing argument of the
+corresponding C<<<<<< parse_* >>>>>> function, the result is a generated string unknown-XYZ where XYZ is some
+number; for documents created with the constructor C<<<<<< new >>>>>>, the URI is undefined.
+
+The value can be modified by calling C<<<<<< setURI >>>>>> method on the document node.
+
+
+=item setURI
+
+ $doc->setURI($strURI);
+
+Sets the URI of the document reported by the method URI (see also the URI
+argument to the various C<<<<<< parse_* >>>>>> functions).
+
+
+=item encoding
+
+ $strEncoding = $doc->encoding();
+
+returns the encoding string of the document.
+
+
+
+ my $doc = XML::LibXML->createDocument( "1.0", "ISO-8859-15" );
+ print $doc->encoding; # prints ISO-8859-15
+
+
+=item actualEncoding
+
+ $strEncoding = $doc->actualEncoding();
+
+returns the encoding in which the XML will be returned by $doc->toString().
+This is usually the original encoding of the document as declared in the XML
+declaration and returned by $doc->encoding. If the original encoding is not
+known (e.g. if created in memory or parsed from a XML without a declared
+encoding), 'UTF-8' is returned.
+
+
+
+ my $doc = XML::LibXML->createDocument( "1.0", "ISO-8859-15" );
+ print $doc->encoding; # prints ISO-8859-15
+
+
+=item setEncoding
+
+ $doc->setEncoding($new_encoding);
+
+This method allows to change the declaration of encoding in the XML declaration
+of the document. The value also affects the encoding in which the document is
+serialized to XML by $doc->toString(). Use setEncoding() to remove the encoding
+declaration.
+
+
+=item version
+
+ $strVersion = $doc->version();
+
+returns the version string of the document
+
+I<<<<<< getVersion() >>>>>> is an alternative form of this function.
+
+
+=item standalone
+
+ $doc->standalone
+
+This function returns the Numerical value of a documents XML declarations
+standalone attribute. It returns I<<<<<< 1 >>>>>> if standalone="yes" was found, I<<<<<< 0 >>>>>> if standalone="no" was found and I<<<<<< -1 >>>>>> if standalone was not specified (default on creation).
+
+
+=item setStandalone
+
+ $doc->setStandalone($numvalue);
+
+Through this method it is possible to alter the value of a documents standalone
+attribute. Set it to I<<<<<< 1 >>>>>> to set standalone="yes", to I<<<<<< 0 >>>>>> to set standalone="no" or set it to I<<<<<< -1 >>>>>> to remove the standalone attribute from the XML declaration.
+
+
+=item compression
+
+ my $compression = $doc->compression;
+
+libxml2 allows reading of documents directly from gzipped files. In this case
+the compression variable is set to the compression level of that file (0-8). If
+XML::LibXML parsed a different source or the file wasn't compressed, the
+returned value will be I<<<<<< -1 >>>>>>.
+
+
+=item setCompression
+
+ $doc->setCompression($ziplevel);
+
+If one intends to write the document directly to a file, it is possible to set
+the compression level for a given document. This level can be in the range from
+0 to 8. If XML::LibXML should not try to compress use I<<<<<< -1 >>>>>> (default).
+
+Note that this feature will I<<<<<< only >>>>>> work if libxml2 is compiled with zlib support and toFile() is used for output.
+
+
+=item toString
+
+ $docstring = $dom->toString($format);
+
+I<<<<<< toString >>>>>> is a DOM serializing function, so the DOM Tree is serialized into a XML string,
+ready for output.
+
+IMPORTANT: unlike toString for other nodes, on document nodes this function
+returns the XML as a byte string in the original encoding of the document (see
+the actualEncoding() method)! This means you can simply do:
+
+
+
+ open OUT, $file;
+ print OUT $doc->toString;
+
+regardless of the actual encoding of the document. See the section on encodings
+in L<<<<<< XML::LibXML >>>>>> for more details.
+
+The optional I<<<<<< $format >>>>>> parameter sets the indenting of the output. This parameter is expected to be an C<<<<<< integer >>>>>> value, that specifies that indentation should be used. The format parameter can
+have three different values if it is used:
+
+If $format is 0, than the document is dumped as it was originally parsed
+
+If $format is 1, libxml2 will add ignorable white spaces, so the nodes content
+is easier to read. Existing text nodes will not be altered
+
+If $format is 2 (or higher), libxml2 will act as $format == 1 but it add a
+leading and a trailing line break to each text node.
+
+libxml2 uses a hard-coded indentation of 2 space characters per indentation
+level. This value can not be altered on run-time.
+
+
+=item toStringC14N
+
+ $c14nstr = $doc->toStringC14N($comment_flag, $xpath [, $xpath_context ]);
+
+See the documentation in L<<<<<< XML::LibXML::Node >>>>>>.
+
+
+=item toStringEC14N
+
+ $ec14nstr = $doc->toStringEC14N($comment_flag, $xpath [, $xpath_context ], $inclusive_prefix_list);
+
+See the documentation in L<<<<<< XML::LibXML::Node >>>>>>.
+
+
+=item serialize
+
+ $str = $doc->serialize($format);
+
+An alias for toString(). This function was name added to be more consistent
+with libxml2.
+
+
+=item serialize_c14n
+
+An alias for toStringC14N().
+
+
+=item serialize_exc_c14n
+
+An alias for toStringEC14N().
+
+
+=item toFile
+
+ $state = $doc->toFile($filename, $format);
+
+This function is similar to toString(), but it writes the document directly
+into a filesystem. This function is very useful, if one needs to store large
+documents.
+
+The format parameter has the same behaviour as in toString().
+
+
+=item toFH
+
+ $state = $doc->toFH($fh, $format);
+
+This function is similar to toString(), but it writes the document directly to
+a filehandle or a stream. A byte stream in the document encoding is passed to
+the file handle. Do NOT apply any C<<<<<< :encoding(...) >>>>>> or C<<<<<< :utf8 >>>>>> PerlIO layer to the filehandle! See the section on encodings in L<<<<<< XML::LibXML >>>>>> for more details.
+
+The format parameter has the same behaviour as in toString().
+
+
+=item toStringHTML
+
+ $str = $document->toStringHTML();
+
+I<<<<<< toStringHTML >>>>>> serialize the tree to a byte string in the document encoding as HTML. With this
+method indenting is automatic and managed by libxml2 internally.
+
+
+=item serialize_html
+
+ $str = $document->serialize_html();
+
+An alias for toStringHTML().
+
+
+=item is_valid
+
+ $bool = $dom->is_valid();
+
+Returns either TRUE or FALSE depending on whether the DOM Tree is a valid
+Document or not.
+
+You may also pass in a L<<<<<< XML::LibXML::Dtd >>>>>> object, to validate against an external DTD:
+
+
+
+ if (!$dom->is_valid($dtd)) {
+ warn("document is not valid!");
+ }
+
+
+=item validate
+
+ $dom->validate();
+
+This is an exception throwing equivalent of is_valid. If the document is not
+valid it will throw an exception containing the error. This allows you much
+better error reporting than simply is_valid or not.
+
+Again, you may pass in a DTD object
+
+
+=item documentElement
+
+ $root = $dom->documentElement();
+
+Returns the root element of the Document. A document can have just one root
+element to contain the documents data.
+
+Optionally one can use I<<<<<< getDocumentElement >>>>>>.
+
+
+=item setDocumentElement
+
+ $dom->setDocumentElement( $root );
+
+This function enables you to set the root element for a document. The function
+supports the import of a node from a different document tree, but does not
+support a document fragment as $root.
+
+
+=item createElement
+
+ $element = $dom->createElement( $nodename );
+
+This function creates a new Element Node bound to the DOM with the name C<<<<<< $nodename >>>>>>.
+
+
+=item createElementNS
+
+ $element = $dom->createElementNS( $namespaceURI, $qname );
+
+This function creates a new Element Node bound to the DOM with the name C<<<<<< $nodename >>>>>> and placed in the given namespace.
+
+
+=item createTextNode
+
+ $text = $dom->createTextNode( $content_text );
+
+As an equivalent of I<<<<<< createElement >>>>>>, but it creates a I<<<<<< Text Node >>>>>> bound to the DOM.
+
+
+=item createComment
+
+ $comment = $dom->createComment( $comment_text );
+
+As an equivalent of I<<<<<< createElement >>>>>>, but it creates a I<<<<<< Comment Node >>>>>> bound to the DOM.
+
+
+=item createAttribute
+
+ $attrnode = $doc->createAttribute($name [,$value]);
+
+Creates a new Attribute node.
+
+
+=item createAttributeNS
+
+ $attrnode = $doc->createAttributeNS( namespaceURI, $name [,$value] );
+
+Creates an Attribute bound to a namespace.
+
+
+=item createDocumentFragment
+
+ $fragment = $doc->createDocumentFragment();
+
+This function creates a DocumentFragment.
+
+
+=item createCDATASection
+
+ $cdata = $dom->create( $cdata_content );
+
+Similar to createTextNode and createComment, this function creates a
+CDataSection bound to the current DOM.
+
+
+=item createProcessingInstruction
+
+ my $pi = $doc->createProcessingInstruction( $target, $data );
+
+create a processing instruction node.
+
+Since this method is quite long one may use its short form I<<<<<< createPI() >>>>>>.
+
+
+=item createEntityReference
+
+ my $entref = $doc->createEntityReference($refname);
+
+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.
+
+An entity reference is unique to a document and cannot be passed to other
+documents as other nodes can be passed.
+
+I<<<<<< NOTE: >>>>>> 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
+
+
+
+ my $string = "&foo;";
+ $some_element->appendText( $string );
+ print $some_element->textContent; # prints "&foo;"
+
+
+=item createInternalSubset
+
+ $dtd = $document->createInternalSubset( $rootnode, $public, $system);
+
+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.
+
+
+
+ my $document = XML::LibXML::Document->new();
+ my $dtd = $document->createInternalSubset( "foo", undef, "foo.dtd" );
+
+will result in the following XML document:
+
+
+
+ <?xml version="1.0"?>
+ <!DOCTYPE foo SYSTEM "foo.dtd">
+
+By setting the public parameter it is possible to set PUBLIC DTDs to a given
+document. So
+
+
+
+ my $document = XML::LibXML::Document->new();
+ my $dtd = $document->createInternalSubset( "foo", "-//FOO//DTD FOO 0.1//EN", undef );
+
+will cause the following declaration to be created on the document:
+
+
+
+ <?xml version="1.0"?>
+ <!DOCTYPE foo PUBLIC "-//FOO//DTD FOO 0.1//EN">
+
+
+=item createExternalSubset
+
+ $dtd = $document->createExternalSubset( $rootnode_name, $publicId, $systemId);
+
+This function is similar to C<<<<<< createInternalSubset() >>>>>> but this DTD is considered to be external and is therefore not added to the
+document itself. Nevertheless it can be used for validation purposes.
+
+
+=item importNode
+
+ $document->importNode( $node );
+
+If a node is not part of a document, it can be imported to another document. As
+specified in DOM Level 2 Specification the Node will not be altered or removed
+from its original document (C<<<<<< $node->cloneNode(1) >>>>>> will get called implicitly).
+
+I<<<<<< NOTE: >>>>>> Don't try to use importNode() to import sub-trees that contain an entity
+reference - even if the entity reference is the root node of the sub-tree. This
+will cause serious problems to your program. This is a limitation of libxml2
+and not of XML::LibXML itself.
+
+
+=item adoptNode
+
+ $document->adoptNode( $node );
+
+If a node is not part of a document, it can be imported to another document. As
+specified in DOM Level 3 Specification the Node will not be altered but it will
+removed from its original document.
+
+After a document adopted a node, the node, its attributes and all its
+descendants belong to the new document. Because the node does not belong to the
+old document, it will be unlinked from its old location first.
+
+I<<<<<< NOTE: >>>>>> Don't try to adoptNode() to import sub-trees that contain entity references -
+even if the entity reference is the root node of the sub-tree. This will cause
+serious problems to your program. This is a limitation of libxml2 and not of
+XML::LibXML itself.
+
+
+=item externalSubset
+
+ my $dtd = $doc->externalSubset;
+
+If a document has an external subset defined it will be returned by this
+function.
+
+I<<<<<< NOTE >>>>>> Dtd nodes are no ordinary nodes in libxml2. The support for these nodes in
+XML::LibXML is still limited. In particular one may not want use common node
+function on doctype declaration nodes!
+
+
+=item internalSubset
+
+ my $dtd = $doc->internalSubset;
+
+If a document has an internal subset defined it will be returned by this
+function.
+
+I<<<<<< NOTE >>>>>> Dtd nodes are no ordinary nodes in libxml2. The support for these nodes in
+XML::LibXML is still limited. In particular one may not want use common node
+function on doctype declaration nodes!
+
+
+=item setExternalSubset
+
+ $doc->setExternalSubset($dtd);
+
+I<<<<<< EXPERIMENTAL! >>>>>>
+
+This method sets a DTD node as an external subset of the given document.
+
+
+=item setInternalSubset
+
+ $doc->setInternalSubset($dtd);
+
+I<<<<<< EXPERIMENTAL! >>>>>>
+
+This method sets a DTD node as an internal subset of the given document.
+
+
+=item removeExternalSubset
+
+ my $dtd = $doc->removeExternalSubset();
+
+I<<<<<< EXPERIMENTAL! >>>>>>
+
+If a document has an external subset defined it can be removed from the
+document by using this function. The removed dtd node will be returned.
+
+
+=item removeInternalSubset
+
+ my $dtd = $doc->removeInternalSubset();
+
+I<<<<<< EXPERIMENTAL! >>>>>>
+
+If a document has an internal subset defined it can be removed from the
+document by using this function. The removed dtd node will be returned.
+
+
+=item getElementsByTagName
+
+ my @nodelist = $doc->getElementsByTagName($tagname);
+
+Implements the DOM Level 2 function
+
+In SCALAR context this function returns a L<<<<<< XML::LibXML::NodeList >>>>>> object.
+
+
+=item getElementsByTagNameNS
+
+ my @nodelist = $doc->getElementsByTagNameNS($nsURI,$tagname);
+
+Implements the DOM Level 2 function
+
+In SCALAR context this function returns a L<<<<<< XML::LibXML::NodeList >>>>>> object.
+
+
+=item getElementsByLocalName
+
+ my @nodelist = $doc->getElementsByLocalName($localname);
+
+This allows the fetching of all nodes from a given document with the given
+Localname.
+
+In SCALAR context this function returns a L<<<<<< XML::LibXML::NodeList >>>>>> object.
+
+
+=item getElementById
+
+ my $node = $doc->getElementById($id);
+
+Returns the element that has an ID attribute with the given value. If no such
+element exists, this returns undef.
+
+Note: the ID of an element may change while manipulating the document. For
+documents with a DTD, the information about ID attributes is only available if
+DTD loading/validation has been requested. For HTML documents parsed with the
+HTML parser ID detection is done automatically. In XML documents, all "xml:id"
+attributes are considered to be of type ID. You can test ID-ness of an
+attribute node with $attr->isId().
+
+In versions 1.59 and earlier this method was called getElementsById() (plural)
+by mistake. Starting from 1.60 this name is maintained as an alias only for
+backward compatibility.
+
+
+=item indexElements
+
+ $dom->indexElements();
+
+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.
+
+This function returns number of elements indexed, -1 if error occurred, or -2
+if this feature is not available in the running libxml2.
+
+
+
+=back
+
+=head1 AUTHORS
+
+Matt Sergeant,
+Christian Glahn,
+Petr Pajas
+
+
+=head1 VERSION
+
+1.70
+
+=head1 COPYRIGHT
+
+2001-2007, AxKit.com Ltd.
+
+2002-2006, Christian Glahn.
+
+2006-2009, Petr Pajas.
+
+=cut
projects / catagits/Gitalist.git / blobdiff