document(3)

NAME

XML::LibXML::Document - DOM Document Class
synopsis: use XML::LibXML; $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);
$state = $doc->toFile($filename, $format);
$state = $doc->toFH($fh, $format);
$document->toStringHTML();
$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]);
$fragment = $doc->createDocumentFragment()
$attrnode = $doc->createAttributeNS( namespaceURI, $name; [,$value] );
$cdata = $dom->create( $cdata_content );
my $pi = $doc->createProcessingInstruction( $target, $da; ta );
my $entref = $doc->createEntityReference($refname);
$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();

DESCRIPTION

The Document Class is in most cases the result of a pars
ing process. But sometimes it is necessary to create a
Document from scratch. The DOM Document Class provides
functions that are conform to the DOM Core naming style.

It inherits all functions from XML::LibXML::Node as speci fied in the DOM specification. This enables to access the
nodes beside 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 UTF8 encoding is
ashured. If iso encoded strings come into play it is much
safer to use the node creation functions of
XML::LibXML::Document.

Methods

new alias for createDocument()

createDocument: The constructor for the document class. As Parameter
it takes the version string and (optionally) the ecod
ing string. Simply calling createDocument will create the document:

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

ing"?>; 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 typ
ing. This will not cause any effect to the class
instance, which is alway 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
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 actualEn coding or getEncoding.; setEncoding
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 careful,
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 ashured to work is to
UTF8.; version
returns the version string of the document

ggeettVVeerrssiioonn(()) is an alternative form of this function.; standalone
This function returns the Numerical value of a docu
ments XML declarations standalone attribute. It
returns 1 if standalone="yes" was found, 0 if stan
dalone="no" was found and -1 if standalone was not
specified (default on creation).; setStandalone
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
libxml2 allows to read 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
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.; toString
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 inte_
ger 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 ignoreable whites
paces, so the nodes content is easier to read. Exist
ing text nodes will not be altered

If $format is 2 (or higher), libxml2 will act as $for
mat == 1 but it add a leading and a trailing linebreak
to each text node.

libxml2 uses a hardcoded indentation of 2 space char
acters 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!; toFile
This function is similar to toString(), but it writes the document directly into a filesystem. This function
is very usefull, if one needs to store large docu
ments.

The format parameter has the same behaviour as in
toString().; toFH
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
toStringHTML deparses the tree to a string as HTML. With this method indenting is automatic and managed by
libxml2 internally.; is_valid
Returns either TRUE or FALSE depending on 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

This is an exception throwing equivalent of is_valid.
If the document is not valid it will throw an excep
tion 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

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

Optionaly one can use getDocumentElement.

setDocumentElement

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

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

createElementNS

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

createTextNode

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

createComment

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

createAttribute

Creates a new Attribute node.

createDocumentFragment

This function creates a DocumentFragment.

createAttributeNS

Creates an Attribute bound to a namespace.

createCDATASection

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

createProcessingInstruction

create a processing instruction node.

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

createEntityReference

If a docuemnt has a DTD specified, one can create
entity refereferences 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
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;"

importNode

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-cloneN_ ode(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 lim
itation of libxml2 and not of XML::LibXML itself.

adoptNode

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

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 lim
ited. In particular one may not want use common node
function on doctype declaration nodes!

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 lim
ited. In particular one may not want use common node
function on doctype declaration nodes!

setExternalSubset

EXPERIMENTAL!

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

setInternalSubset

EXPERIMENTAL!

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

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

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.

AUTHOR

Matt Sergeant, Christian Glahn

VERSION

1.53

docs.sk

comprehensive documentation repository

In section

See also

document(3)

NAME

DESCRIPTION

AUTHOR

SEE ALSO

VERSION