1XML::LibXML::Document(3U)ser Contributed Perl DocumentatiXoMnL::LibXML::Document(3)
2
6 XML::LibXML::Document - XML::LibXML DOM Document Class
7
9 $dom = XML::LibXML::Document->new( $version, $encoding );
10 $dom = XML::LibXML::Document->createDocument( $version, $encoding );
11 $strEncoding = $doc->encoding();
12 $doc->setEncoding($new_encoding);
13 $strVersion = $doc->version();
14 $doc->standalone
15 $doc->setStandalone($numvalue);
16 my $compression = $doc->compression;
17 $doc->setCompression($ziplevel);
18 $docstring = $dom->toString($format);
19 $c14nstr = $doc->toStringC14N($comment_flag,$xpath);
20 $str = $doc->serialze($format);
21 $c14nstr = $doc->serialize_c14n($comment_flag,$xpath);
22 $state = $doc->toFile($filename, $format);
23 $state = $doc->toFH($fh, $format);
24 $str = $document->toStringHTML();
25 $str = $document->serialize_html();
26 $bool = $dom->is_valid();
27 $dom->validate();
28 $root = $dom->documentElement();
29 $dom->setDocumentElement( $root );
30 $element = $dom->createElement( $nodename );
31 $element = $dom->createElementNS( $namespaceURI, $qname );
32 $text = $dom->createTextNode( $content_text );
33 $comment = $dom->createComment( $comment_text );
34 $attrnode = $doc->createAttribute($name [,$value]);
35 $attrnode = $doc->createAttributeNS( namespaceURI, $name [,$value] );
36 $fragment = $doc->createDocumentFragment();
37 $cdata = $dom->create( $cdata_content );
38 my $pi = $doc->createProcessingInstruction( $target, $data );
39 my $entref = $doc->createEntityReference($refname);
40 $dtd = $document->createInternalSubset( $rootnode, $public, $system);
41 $dtd = $document->createExternalSubset( $rootnode, $public, $system);
42 $document->importNode( $node );
43 $document->adoptNode( $node );
44 my $dtd = $doc->externalSubset;
45 my $dtd = $doc->internalSubset;
46 $doc->setExternalSubset($dtd);
47 $doc->setInternalSubset($dtd);
48 my $dtd = $doc->removeExternalSubset();
49 my $dtd = $doc->removeInternalSubset();
50 my @nodelist = $doc->getElementsByTagName($tagname);
51 my @nodelist = $doc->getElementsByTagName($nsURI,$tagname);
52 my @nodelist = $doc->getElementsByLocalName($localname);
53 my $node = $doc->getElementById($id);
54 $dom->indexElements();
55
57 The Document Class is in most cases the result of a parsing process.
58 But sometimes it is necessary to create a Document from scratch. The
59 DOM Document Class provides functions that conform to the DOM Core nam‐
60 ing style.
61 It inherits all functions from XML::LibXML::Node as specified in the
63 DOM specification. This enables access to the nodes besides the root
64 element on document level - a DTD for example. The support for these
65 nodes is limited at the moment.
66 While generaly nodes are bound to a document in the DOM concept it is
68 suggested that one should always create a node not bound to any docu‐
69 ment. There is no need of really including the node to the document,
70 but once the node is bound to a document, it is quite safe that all
71 strings have the correct encoding. If an unbound textnode with an iso
72 encoded string is created (e.g. with $CLASS->new()), the toString func‐
73 tion may not return the expected result.
74 All this seems like a limitation as long as UTF-8 encoding is assured.
76 If iso encoded strings come into play it is much safer to use the node
77 creation functions of XML::LibXML::Document.
78 new
80 $dom = XML::LibXML::Document->new( $version, $encoding );
81 alias for createDocument()
83 createDocument
85 $dom = XML::LibXML::Document->createDocument( $version, $encoding );
86 The constructor for the document class. As Parameter it takes the
88 version string and (optionally) the encoding string. Simply calling
89 createDocument() will create the document:
90 <?xml version="your version" encoding="your encoding"?>
92 Both parameter are optional. The default value for $version is 1.0,
94 of course. If the $encoding parameter is not set, the encoding
95 will be left unset, which means UTF-8 is implied.
96 The call of createDocument() without any parameter will result the
98 following code:
99 <?xml version="1.0"?>
101 Alternatively one can call this constructor directly from the
103 XML::LibXML class level, to avoid some typing. This will not have
104 any effect on the class instance, which is always XML::LibXML::Doc‐
105 ument.
106 my $document = XML::LibXML->createDocument( "1.0", "UTF-8" );
108 is therefore a shortcut for
110 my $document = XML::LibXML::Document->createDocument( "1.0", "UTF-8" );
112 encoding
114 $strEncoding = $doc->encoding();
115 returns the encoding string of the document.
117 my $doc = XML::LibXML->createDocument( "1.0", "ISO-8859-15" );
119 print $doc->encoding; # prints ISO-8859-15
120 Optionally this function can be accessed by actualEncoding or
122 getEncoding.
123 setEncoding
125 $doc->setEncoding($new_encoding);
126 From time to time it is useful to change the effective encoding of
128 a document. This method provides the interface to manipulate the
129 encoding of a document.
130 Note that this function has to be used very carefully, since you
132 can't simply convert one encoding in any other, since some (or even
133 all) characters may not exist in the new encoding. XML::LibXML will
134 not test if the operation is allowed or possible for the given doc‐
135 ument. The only switching assured to work is to UTF-8.
136 version
138 $strVersion = $doc->version();
139 returns the version string of the document
141 getVersion() is an alternative form of this function.
143 standalone
145 $doc->standalone
146 This function returns the Numerical value of a documents XML decla‐
148 rations standalone attribute. It returns 1 if standalone="yes" was
149 found, 0 if standalone="no" was found and -1 if standalone was not
150 specified (default on creation).
151 setStandalone
153 $doc->setStandalone($numvalue);
154 Through this method it is possible to alter the value of a docu‐
156 ments standalone attribute. Set it to 1 to set standalone="yes", to
157 0 to set standalone="no" or set it to -1 to remove the standalone
158 attribute from the XML declaration.
159 compression
161 my $compression = $doc->compression;
162 libxml2 allows reading of documents directly from gziped files. In
164 this case the compression variable is set to the compression level
165 of that file (0-8). If XML::LibXML parsed a different source or the
166 file wasn't compressed, the returned value will be -1.
167 setCompression
169 $doc->setCompression($ziplevel);
170 If one intends to write the document directly to a file, it is pos‐
172 sible to set the compression level for a given document. This level
173 can be in the range from 0 to 8. If XML::LibXML should not try to
174 compress use -1 (default).
175 Note that this feature will only work if libxml2 is compiled with
177 zlib support and toFile() is used for output.
178 toString
180 $docstring = $dom->toString($format);
181 toString is a deparsing function, so the DOM Tree can be translated
183 into a string, ready for output.
184 The optional $format parameter sets the indenting of the output.
186 This parameter is expected to be an integer value, that specifies
187 that indentation should be used. The format parameter can have
188 three different values if it is used:
189 If $format is 0, than the document is dumped as it was originally
191 parsed
192 If $format is 1, libxml2 will add ignorable whitespaces, so the
194 nodes content is easier to read. Existing text nodes will not be
195 altered
196 If $format is 2 (or higher), libxml2 will act as $format == 1 but
198 it add a leading and a trailing linebreak to each text node.
199 libxml2 uses a hardcoded indentation of 2 space characters per
201 indentation level. This value can not be altered on runtime.
202 NOTE: XML::LibXML::Document::toString returns the data in the docu‐
204 ment encoding rather than UTF-8! If you want UTF-8 ecoded XML, you
205 have to change the conding by using setEncoding()
206 toStringC14N
208 $c14nstr = $doc->toStringC14N($comment_flag,$xpath); A variation to
209 toString, that returns the canonized form of the given document.
210 serialize
212 $str = $doc->serialze($format);
213 Alternative form of toString(). This function name added to be more
215 conformant with libxml2's examples.
216 serialize_c14n
218 $c14nstr = $doc->serialize_c14n($comment_flag,$xpath);
219 Alternative form of toStringC14N().
221 toFile
223 $state = $doc->toFile($filename, $format);
224 This function is similar to toString(), but it writes the document
226 directly into a filesystem. This function is very useful, if one
227 needs to store large documents.
228 The format parameter has the same behaviour as in toString().
230 toFH
232 $state = $doc->toFH($fh, $format);
233 This function is similar to toString(), but it writes the document
235 directly to a filehandler or a stream.
236 The format parameter has the same behaviour as in toString().
238 toStringHTML
240 $str = $document->toStringHTML();
241 toStringHTML deparses the tree to a string as HTML. With this
243 method indenting is automatic and managed by libxml2 internally.
244 serialize_html
246 $str = $document->serialize_html();
247 Alternative form of toStringHTML().
249 is_valid
251 $bool = $dom->is_valid();
252 Returns either TRUE or FALSE depending on whether the DOM Tree is a
254 valid Document or not.
255 You may also pass in a XML::LibXML::Dtd object, to validate against
257 an external DTD:
258 if (!$dom->is_valid($dtd)) {
260 warn("document is not valid!");
261 }
262 validate
264 $dom->validate();
265 This is an exception throwing equivalent of is_valid. If the docu‐
267 ment is not valid it will throw an exception containing the error.
268 This allows you much better error reporting than simply is_valid or
269 not.
270 Again, you may pass in a DTD object
272 documentElement
274 $root = $dom->documentElement();
275 Returns the root element of the Document. A document can have just
277 one root element to contain the documents data.
278 Optionaly one can use getDocumentElement.
280 setDocumentElement
282 $dom->setDocumentElement( $root );
283 This function enables you to set the root element for a document.
285 The function supports the import of a node from a different docu‐
286 ment tree.
287 createElement
289 $element = $dom->createElement( $nodename );
290 This function creates a new Element Node bound to the DOM with the
292 name $nodename.
293 createElementNS
295 $element = $dom->createElementNS( $namespaceURI, $qname );
296 This function creates a new Element Node bound to the DOM with the
298 name $nodename and placed in the given namespace.
299 createTextNode
301 $text = $dom->createTextNode( $content_text );
302 As an equivalent of createElement, but it creates a Text Node bound
304 to the DOM.
305 createComment
307 $comment = $dom->createComment( $comment_text );
308 As an equivalent of createElement, but it creates a Comment Node
310 bound to the DOM.
311 createAttribute
313 $attrnode = $doc->createAttribute($name [,$value]);
314 Creates a new Attribute node.
316 createAttributeNS
318 $attrnode = $doc->createAttributeNS( namespaceURI, $name [,$value] );
319 Creates an Attribute bound to a namespace.
321 createDocumentFragment
323 $fragment = $doc->createDocumentFragment();
324 This function creates a DocumentFragment.
326 createCDATASection
328 $cdata = $dom->create( $cdata_content );
329 Similar to createTextNode and createComment, this function creates
331 a CDataSection bound to the current DOM.
332 createProcessingInstruction
334 my $pi = $doc->createProcessingInstruction( $target, $data );
335 create a processing instruction node.
337 Since this method is quite long one may use its short form cre‐
339 atePI().
340 createEntityReference
342 my $entref = $doc->createEntityReference($refname);
343 If a document has a DTD specified, one can create entity references
345 by using this function. If one wants to add a entity reference to
346 the document, this reference has to be created by this function.
347 An entity reference is unique to a document and cannot be passed to
349 other documents as other nodes can be passed.
350 NOTE: A text content containing something that looks like an entity
352 reference, will not be expanded to a real entity reference unless
353 it is a predefined entity
354 my $string = "&foo;";
356 $some_element->appendText( $string );
357 print $some_element->textContent; # prints "&foo;"
358 createInternalSubset
360 $dtd = $document->createInternalSubset( $rootnode, $public, $system);
361 This function creates and adds an internal subset to the given doc‐
363 ument. Because the function automaticly adds the DTD to the docu‐
364 ment there is no need to add the created node explicitly to the
365 document.
366 my $document = XML::LibXML::Document->new();
368 my $dtd = $document->createInternalSubset( "foo", undef, "foo.dtd" );
369 will result in the following XML document:
371 <?xml version="1.0"?>
373 <!DOCTYPE foo SYSTEM "foo.dtd">
374 By setting the public parameter it is possible to set PUBLIC dtds
376 to a given document. So
377 my $document = XML::LibXML::Document->new();
379 my $dtd = $document->createInternalSubset( "foo", "-//FOO//DTD FOO 0.1//EN", undef );
380 will cause the following declaration to be created on the document:
382 <?xml version="1.0"?>
384 <!DOCTYPE foo PUBLIC "-//FOO//DTD FOO 0.1//EN">
385 createExternalSubset
387 $dtd = $document->createExternalSubset( $rootnode, $public, $system);
388 This function is similar to createInternalSubset() but this DTD is
390 considered to be external and is therefore not added to the docu‐
391 ment itself. Nevertheless it can be used for validation purposes.
392 importNode
394 $document->importNode( $node );
395 If a node is not part of a document, it can be imported to another
397 document. As specified in DOM Level 2 Specification the Node will
398 not be altered or removed from its original document ($node->clo‐
399 neNode(1) will get called implicitly).
400 NOTE: Don't try to use importNode() to import subtrees that contain
402 an entity reference - even if the entity reference is the root node
403 of the subtree. This will cause serious problems to your program.
404 This is a limitation of libxml2 and not of XML::LibXML itself.
405 adoptNode
407 $document->adoptNode( $node );
408 If a node is not part of a document, it can be imported to another
410 document. As specified in DOM Level 3 Specification the Node will
411 not be altered but it will removed from its original document.
412 After a document adopted a node, the node, its attributes and all
414 its descendants belong to the new document. Because the node does
415 not belong to the old document, it will be unlinked from its old
416 location first.
417 NOTE: Don't try to adoptNode() to import subtrees that contain
419 entity references - even if the entity reference is the root node
420 of the subtree. This will cause serious problems to your program.
421 This is a limitation of libxml2 and not of XML::LibXML itself.
422 externalSubset
424 my $dtd = $doc->externalSubset;
425 If a document has an external subset defined it will be returned by
427 this function.
428 NOTE Dtd nodes are no ordinary nodes in libxml2. The support for
430 these nodes in XML::LibXML is still limited. In particular one may
431 not want use common node function on doctype declaration nodes!
432 internalSubset
434 my $dtd = $doc->internalSubset;
435 If a document has an internal subset defined it will be returned by
437 this function.
438 NOTE Dtd nodes are no ordinary nodes in libxml2. The support for
440 these nodes in XML::LibXML is still limited. In particular one may
441 not want use common node function on doctype declaration nodes!
442 setExternalSubset
444 $doc->setExternalSubset($dtd);
445 EXPERIMENTAL!
447 This method sets a DTD node as an external subset of the given doc‐
449 ument.
450 setInternalSubset
452 $doc->setInternalSubset($dtd);
453 EXPERIMENTAL!
455 This method sets a DTD node as an internal subset of the given doc‐
457 ument.
458 removeExternalSubset
460 my $dtd = $doc->removeExternalSubset();
461 EXPERIMENTAL!
463 If a document has an external subset defined it can be removed from
465 the document by using this function. The removed dtd node will be
466 returned.
467 removeInternalSubset
469 my $dtd = $doc->removeInternalSubset();
470 EXPERIMENTAL!
472 If a document has an internal subset defined it can be removed from
474 the document by using this function. The removed dtd node will be
475 returned.
476 getElementsByTagName
478 my @nodelist = $doc->getElementsByTagName($tagname);
479 Implements the DOM Level 2 function
481 In SCALAR context this function returns a XML::LibXML::NodeList
483 object.
484 getElementsByTagNameNS
486 my @nodelist = $doc->getElementsByTagName($nsURI,$tagname);
487 Implements the DOM Level 2 function
489 In SCALAR context this function returns a XML::LibXML::NodeList
491 object.
492 getElementsByLocalName
494 my @nodelist = $doc->getElementsByLocalName($localname);
495 This allows the fetching of all nodes from a given document with
497 the given Localname.
498 In SCALAR context this function returns a XML::LibXML::NodeList
500 object.
501 getElementById
503 my $node = $doc->getElementById($id);
504 Returns the element that has an ID attribute with the given value.
506 If no such element exists, this returns undef.
507 Note: the ID of an element may change while manipulating the docu‐
509 ment. For documents with a DTD, the information about ID attributes
510 is only available if DTD loading/validation has been requested. For
511 HTML documents parsed with the HTML parser ID detection is done
512 automatically. In XML documents, all "xml:id" attributes are con‐
513 sidered to be of type ID. You can test ID-ness of an attribute node
514 with $attr->isId().
515 In versions 1.59 and earlier this method was called getElements‐
517 ById() (plural) by mistake. Starting from 1.60 this name is main‐
518 tained as an alias only for backward compatibility.
519 indexElements
521 $dom->indexElements();
522 This function causes libxml2 to stamp all elements in a document
524 with their document position index which considerably speeds up
525 XPath queries for large documents. It should only be used with
526 static documents that won't be further changed by any DOM methods,
527 because once a document is indexed, XPath will always prefer the
528 index to other methods of determining the document order of nodes.
529 XPath could therefore return improperly ordered node-lists when
530 applied on a document that has been changed after being indexed. It
531 is of course possible to use this method to re-index a modified
532 document before using it with XPath again. This function is not a
533 part of the DOM specification.
534 This function returns number of elements indexed, -1 if error
536 occurred, or -2 if this feature is not available in the running
537 libxml2.
538
540 Matt Sergeant, Christian Glahn, Petr Pajas,
541
543 1.62
544
546 2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas,
547 All rights reserved.
548perl v5.8.8 2006-11-17 XML::LibXML::Document(3)