XML::LibXML::Document man page on Peanut

Man page or keyword search:  
man Server   7435 pages
apropos Keyword Search (all sections)
Output format
Peanut logo
[printable version]

XML::LibXML::Document(User Contributed Perl DocumentatXML::LibXML::Document(3)

NAME
       XML::LibXML::Document - XML::LibXML DOM Document Class

SYNOPSIS
	 $dom = XML::LibXML::Document->new( $version, $encoding );
	 $dom = XML::LibXML::Document->createDocument( $version, $encoding );
	 $strEncoding = $doc->encoding();
	 $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);
	 $str = $doc->serialze($format);
	 $c14nstr = $doc->serialize_c14n($comment_flag,$xpath);
	 $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, $public, $system);
	 $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->getElementsByTagName($nsURI,$tagname);
	 my @nodelist = $doc->getElementsByLocalName($localname);
	 my $node = $doc->getElementsById($id);
	 $dom->indexElements();

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 XML::LibXML::Node as specified in the
       DOM specification. This enables access to the nodes besides the root
       element on document level - a DTD for example. The support for these
       nodes is limited at the moment.

       While generaly 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 textnode with
       an iso encoded string is created (e.g. with $CLASS->new()), the
       toString function may not return the expected result.

       All this seems like a limitation as long as UTF8 encoding is assured.
       If iso encoded strings come into play it is much safer to use the node
       creation functions of XML::LibXML::Document.

       new
	     $dom = XML::LibXML::Document->new( $version, $encoding );

	   alias for createDocument()

       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
	   createDocument() will create the document:

	     <?xml version="your version" encoding="your encoding"?>

	   Both parameter are optional. The default value for $version is 1.0,
	   of course.  If the $encoding parameter is not set, the encoding
	   will be left unset, which means UTF8 is implied.

	   The call of 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", "UTF8" );

	   is therefore a shortcut for

	     my $document = XML::LibXML::Document->createDocument( "1.0", "UTF8" );

       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

	   Optionally this function can be accessed by actualEncoding or
	   getEncoding.

       setEncoding
	     $doc->setEncoding($new_encoding);

	   From time to time it is useful to change the effective encoding of
	   a document.	This method provides the interface to manipulate the
	   encoding of a document.

	   Note that this function has to be used very carefully, since you
	   can't simply convert one encoding in any other, since some (or even
	   all) characters may not exist in the new encoding. XML::LibXML will
	   not test if the operation is allowed or possible for the given
	   document. The only switching assured to work is to UTF8.

       version
	     $strVersion = $doc->version();

	   returns the version string of the document

	   getVersion() is an alternative form of this function.

       standalone
	     $doc->standalone

	   This function returns the Numerical value of a documents XML
	   declarations standalone attribute. It returns 1 if standalone="yes"
	   was found, 0 if standalone="no" was found and -1 if standalone was
	   not specified (default on creation).

       setStandalone
	     $doc->setStandalone($numvalue);

	   Through this method it is possible to alter the value of a
	   documents standalone attribute. Set it to 1 to set
	   standalone="yes", to 0 to set standalone="no" or set it to -1 to
	   remove the standalone attribute from the XML declaration.

       compression
	     my $compression = $doc->compression;

	   libxml2 allows reading of documents directly from gziped 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 -1.

       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 -1 (default).

	   Note that this feature will only work if libxml2 is compiled with
	   zlib support and toFile() is used for output.

       toString
	     $docstring = $dom->toString($format);

	   toString is a deparsing function, so the DOM Tree can be translated
	   into a string, ready for output.

	   The optional $format parameter sets the indenting of the output.
	   This parameter is expected to be an 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 whitespaces, 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 linebreak to each text node.

	   libxml2 uses a hardcoded indentation of 2 space characters per
	   indentation level. This value can not be altered on runtime.

	   NOTE: XML::LibXML::Document::toString returns the data in the
	   document encoding rather than UTF8! If you want UTF8 ecoded XML,
	   you have to change the conding by using setEncoding()

       toStringC14N
	   $c14nstr = $doc->toStringC14N($comment_flag,$xpath); A variation to
	   toString, that returns the canonized form of the given document.

       serialize
	     $str = $doc->serialze($format);

	   Alternative form of toString(). This function name added to be more
	   conformant with libxml2's examples.

       serialize_c14n
	     $c14nstr = $doc->serialize_c14n($comment_flag,$xpath);

	   Alternative form of toStringC14N().

       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().

       toFH
	     $state = $doc->toFH($fh, $format);

	   This function is similar to toString(), but it writes the document
	   directly to a filehandler or a stream.

	   The format parameter has the same behaviour as in toString().

       toStringHTML
	     $str = $document->toStringHTML();

	   toStringHTML deparses the tree to a string as HTML. With this
	   method indenting is automatic and managed by libxml2 internally.

       serialize_html
	     $str = $document->serialize_html();

	   Alternative form of toStringHTML().

       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 XML::LibXML::Dtd object, to validate against
	   an external DTD:

	      if (!$dom->is_valid($dtd)) {
		  warn("document is not valid!");
	      }

       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

       documentElement
	     $root = $dom->documentElement();

	   Returns the root element of the Document. A document can have just
	   one root element to contain the documents data.

	   Optionaly one can use getDocumentElement.

       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.

       createElement
	     $element = $dom->createElement( $nodename );

	   This function creates a new Element Node bound to the DOM with the
	   name $nodename.

       createElementNS
	     $element = $dom->createElementNS( $namespaceURI, $qname );

	   This function creates a new Element Node bound to the DOM with the
	   name $nodename and placed in the given namespace.

       createTextNode
	     $text = $dom->createTextNode( $content_text );

	   As an equivalent of createElement, but it creates a Text Node bound
	   to the DOM.

       createComment
	     $comment = $dom->createComment( $comment_text );

	   As an equivalent of createElement, but it creates a Comment Node
	   bound to the DOM.

       createAttribute
	     $attrnode = $doc->createAttribute($name [,$value]);

	   Creates a new Attribute node.

       createAttributeNS
	     $attrnode = $doc->createAttributeNS( namespaceURI, $name [,$value] );

	   Creates an Attribute bound to a namespace.

       createDocumentFragment
	     $fragment = $doc->createDocumentFragment()

	   This function creates a DocumentFragment.

       createCDATASection
	     $cdata = $dom->create( $cdata_content );

	   Similar to createTextNode and createComment, this function creates
	   a CDataSection bound to the current DOM.

       createProcessingInstruction
	     my $pi = $doc->createProcessingInstruction( $target, $data );

	   create a processing instruction node.

	   Since this method is quite long one may use its short form
	   createPI().

       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.

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

       createInternalSubset
	     $dtd = $document->createInternalSubset( $rootnode, $public, $system);

	   This function creates and adds an internal subset to the given
	   document.  Because the function automaticly 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">

       createExternalSubset
	     $dtd = $document->createExternalSubset( $rootnode, $public, $system);

	   This function is similar to 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.

       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
	   ($node->cloneNode(1) will get called implicitly).

	   NOTE: Don't try to use importNode() to import subtrees that contain
	   an entity reference - even if the entity reference is the root node
	   of the subtree. This will cause serious problems to your program.
	   This is a limitation of libxml2 and not of XML::LibXML itself.

       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.

	   NOTE: Don't try to adoptNode() to import subtrees that contain
	   entity references - even if the entity reference is the root node
	   of the subtree. This will cause serious problems to your program.
	   This is a limitation of libxml2 and not of XML::LibXML itself.

       externalSubset
	     my $dtd = $doc->externalSubset;

	   If a document has an external subset defined it will be returned by
	   this function.

	   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!

       internalSubset
	     my $dtd = $doc->internalSubset;

	   If a document has an internal subset defined it will be returned by
	   this function.

	   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!

       setExternalSubset
	     $doc->setExternalSubset($dtd);

	   EXPERIMENTAL!

	   This method sets a DTD node as an external subset of the given
	   document.

       setInternalSubset
	     $doc->setInternalSubset($dtd);

	   EXPERIMENTAL!

	   This method sets a DTD node as an internal subset of the given
	   document.

       removeExternalSubset
	     my $dtd = $doc->removeExternalSubset();

	   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.

       removeInternalSubset
	     my $dtd = $doc->removeInternalSubset();

	   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.

       getElementsByTagName
	     my @nodelist = $doc->getElementsByTagName($tagname);

	   Implements the DOM Level 2 function

	   In SCALAR context this function returns a XML::LibXML::NodeList
	   object.

       getElementsByTagNameNS
	     my @nodelist = $doc->getElementsByTagName($nsURI,$tagname);

	   Implements the DOM Level 2 function

	   In SCALAR context this function returns a XML::LibXML::NodeList
	   object.

       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 XML::LibXML::NodeList
	   object.

       getElementsById
	     my $node = $doc->getElementsById($id);

	   This allows the fetching of the node at a given position in the
	   DOM.

	   Note: The Id of a node might change while manipulating the
	   document.

       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.

AUTHORS
       Matt Sergeant, Christian Glahn, =head1 VERSION

       1.58

COPYRIGHT
       2001-2004, AxKit.com Ltd; 2002-2004 Christian Glahn, All rights
       reserved.

perl v5.10.0			  2004-03-31	      XML::LibXML::Document(3)
[top]

List of man pages available for Peanut

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net