PC Professionell 2004 December/PCpro_2004_12.ISO/files/webserver/tsw/TSW_3.4.0.exe/Apache2/perl/Document.pod

Text File | 2003-08-22 | 16.7 KB | 592 lines

=head1 NAME

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

=head1 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);


=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 are conform to the DOM Core naming style.

It inherits all functions from XML::LibXML::Node as specified 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.

=over 4

=item B<new>

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

alias for createDocument()


=item B<createDocument>

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

The constructor for the document class. As Parameter it takes the version
string and (optionally) the ecoding 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 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" );


=item B<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.


=item B<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 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.


=item B<version>

  $strVersion = $doc->version();

returns the version string of the document

getVersion() is an alternative form of this function.


=item B<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).


=item B<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.


=item B<compression>

  my $compression = $doc->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.


=item B<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.


=item B<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 ignoreable 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()


=item B<toStringC14N>

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


=item B<serialize>

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

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


=item B<serialize_c14n>

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

Alternative form of toStringC14N().


=item B<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 usefull, if one needs to store large
documents.

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


=item B<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().


=item B<toStringHTML>

  $str = $document->toStringHTML();

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


=item B<serialize_html>

  $str = $document->serialize_html();

Alternative form of toStringHTML().


=item B<is_valid>

  $bool = $dom->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!");
   }


=item B<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 B<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.


=item B<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.


=item B<createElement>

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

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


=item B<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.


=item B<createTextNode>

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

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


=item B<createComment>

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

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


=item B<createAttribute>

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

Creates a new Attribute node.


=item B<createAttributeNS>

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

Creates an Attribute bound to a namespace.


=item B<createDocumentFragment>

  $fragment = $doc->createDocumentFragment()

This function creates a DocumentFragment.


=item B<createCDATASection>

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

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


=item B<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().


=item B<createEntityReference>

  my $entref = $doc->createEntityReference($refname);

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


=item B<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">


=item B<createExternalSubset>

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

This function is similar to createInternalSubset() but this DTD is concidered
to be external and is therefore not added to the document itself. Nevertheless
it can be used for validation purposes.


=item B<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.


=item B<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.


=item B<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!


=item B<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!


=item B<setExternalSubset>

  $doc->setExternalSubset($dtd);

EXPERIMENTAL!

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


=item B<setInternalSubset>

  $doc->setInternalSubset($dtd);

EXPERIMENTAL!

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


=item B<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.


=item B<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.


=item B<getElementsByTagName>

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

Implements the DOM Level 2 function

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


=item B<getElementsByTagNameNS>

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

Implements the DOM Level 2 function

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


=item B<getElementsByLocalName>

  my @nodelist = $doc->getElementsByLocalName($localname);

This allows to fetch all nodes from a given document with the given Localname.

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


=item B<getElementsById>

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

This allows to fetch the node at a given position in the DOM.

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



=back

=head1 AUTHORS

Matt Sergeant,
Christian Glahn,
=head1 VERSION

1.56

=head1 COPYRIGHT

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

=cut