local-lib5/man/man3/XML::LibXML::Document.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "XML::LibXML::Document 3"
 127 .TH XML::LibXML::Document 3 "2009-10-07" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 XML::LibXML::Document \- XML::LibXML DOM Document Class
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 3
 137 \&  use XML::LibXML;
 138 \&  # Only methods specific to Document nodes are listed here,
 139 \&  # see XML::LibXML::Node manpage for other methods
 140 \&
 141 \&  $dom = XML::LibXML::Document\->new( $version, $encoding );
 142 \&  $dom = XML::LibXML::Document\->createDocument( $version, $encoding );
 143 \&  $strURI = $doc\->URI();
 144 \&  $doc\->setURI($strURI);
 145 \&  $strEncoding = $doc\->encoding();
 146 \&  $strEncoding = $doc\->actualEncoding();
 147 \&  $doc\->setEncoding($new_encoding);
 148 \&  $strVersion = $doc\->version();
 149 \&  $doc\->standalone
 150 \&  $doc\->setStandalone($numvalue);
 151 \&  my $compression = $doc\->compression;
 152 \&  $doc\->setCompression($ziplevel);
 153 \&  $docstring = $dom\->toString($format);
 154 \&  $c14nstr = $doc\->toStringC14N($comment_flag, $xpath [, $xpath_context ]);
 155 \&  $ec14nstr = $doc\->toStringEC14N($comment_flag, $xpath [, $xpath_context ], $inclusive_prefix_list);
 156 \&  $str = $doc\->serialize($format);
 157 \&  $state = $doc\->toFile($filename, $format);
 158 \&  $state = $doc\->toFH($fh, $format);
 159 \&  $str = $document\->toStringHTML();
 160 \&  $str = $document\->serialize_html();
 161 \&  $bool = $dom\->is_valid();
 162 \&  $dom\->validate();
 163 \&  $root = $dom\->documentElement();
 164 \&  $dom\->setDocumentElement( $root );
 165 \&  $element = $dom\->createElement( $nodename );
 166 \&  $element = $dom\->createElementNS( $namespaceURI, $qname );
 167 \&  $text = $dom\->createTextNode( $content_text );
 168 \&  $comment = $dom\->createComment( $comment_text );
 169 \&  $attrnode = $doc\->createAttribute($name [,$value]);
 170 \&  $attrnode = $doc\->createAttributeNS( namespaceURI, $name [,$value] );
 171 \&  $fragment = $doc\->createDocumentFragment();
 172 \&  $cdata = $dom\->create( $cdata_content );
 173 \&  my $pi = $doc\->createProcessingInstruction( $target, $data );
 174 \&  my $entref = $doc\->createEntityReference($refname);
 175 \&  $dtd = $document\->createInternalSubset( $rootnode, $public, $system);
 176 \&  $dtd = $document\->createExternalSubset( $rootnode_name, $publicId, $systemId);
 177 \&  $document\->importNode( $node );
 178 \&  $document\->adoptNode( $node );
 179 \&  my $dtd = $doc\->externalSubset;
 180 \&  my $dtd = $doc\->internalSubset;
 181 \&  $doc\->setExternalSubset($dtd);
 182 \&  $doc\->setInternalSubset($dtd);
 183 \&  my $dtd = $doc\->removeExternalSubset();
 184 \&  my $dtd = $doc\->removeInternalSubset();
 185 \&  my @nodelist = $doc\->getElementsByTagName($tagname);
 186 \&  my @nodelist = $doc\->getElementsByTagNameNS($nsURI,$tagname);
 187 \&  my @nodelist = $doc\->getElementsByLocalName($localname);
 188 \&  my $node = $doc\->getElementById($id);
 189 \&  $dom\->indexElements();
 190 .Ve
 191 .SH "DESCRIPTION"
 192 .IX Header "DESCRIPTION"
 193 The Document Class is in most cases the result of a parsing process. But
 194 sometimes it is necessary to create a Document from scratch. The \s-1DOM\s0 Document
 195 Class provides functions that conform to the \s-1DOM\s0 Core naming style.
 196 .PP
 197 It inherits all functions from XML::LibXML::Node as specified in the \s-1DOM\s0 specification. This enables access to the nodes besides
 198 the root element on document level \- a \f(CW\*(C`DTD\*(C'\fR for example. The support for these nodes is limited at the moment.
 199 .PP
 200 While generally nodes are bound to a document in the \s-1DOM\s0 concept it is
 201 suggested that one should always create a node not bound to any document. There
 202 is no need of really including the node to the document, but once the node is
 203 bound to a document, it is quite safe that all strings have the correct
 204 encoding. If an unbound text node with an \s-1ISO\s0 encoded string is created (e.g.
 205 with \f(CW$CLASS\fR\->\fInew()\fR), the \f(CW\*(C`toString\*(C'\fR function may not return the expected result.
 206 .PP
 207 To prevent such problems, it is recommended to pass all data to XML::LibXML
 208 methods as character strings (i.e. \s-1UTF\-8\s0 encoded, with the \s-1UTF8\s0 flag on).
 209 .SH "METHODS"
 210 .IX Header "METHODS"
 211 Many functions listed here are extensively documented in the \s-1DOM\s0 Level 3 specification (<http://www.w3.org/TR/DOM\-Level\-3\-Core/>). Please refer to the specification for extensive documentation.
 212 .IP "new" 4
 213 .IX Item "new"
 214 .Vb 1
 215 \&  $dom = XML::LibXML::Document\->new( $version, $encoding );
 216 .Ve
 217 .Sp
 218 alias for \fIcreateDocument()\fR
 219 .IP "createDocument" 4
 220 .IX Item "createDocument"
 221 .Vb 1
 222 \&  $dom = XML::LibXML::Document\->createDocument( $version, $encoding );
 223 .Ve
 224 .Sp
 225 The constructor for the document class. As Parameter it takes the version
 226 string and (optionally) the encoding string. Simply calling \fIcreateDocument\fR() will create the document:
 227 .Sp
 228 .Vb 1
 229 \&  <?xml version="your version" encoding="your encoding"?>
 230 .Ve
 231 .Sp
 232 Both parameter are optional. The default value for \fI\f(CI$version\fI\fR is \f(CW1.0\fR, of course. If the \fI\f(CI$encoding\fI\fR parameter is not set, the encoding will be left unset, which means \s-1UTF\-8\s0 is
 233 implied.
 234 .Sp
 235 The call of \fIcreateDocument\fR() without any parameter will result the following code:
 236 .Sp
 237 .Vb 1
 238 \&  <?xml version="1.0"?>
 239 .Ve
 240 .Sp
 241 Alternatively one can call this constructor directly from the XML::LibXML class
 242 level, to avoid some typing. This will not have any effect on the class
 243 instance, which is always XML::LibXML::Document.
 244 .Sp
 245 .Vb 1
 246 \&  my $document = XML::LibXML\->createDocument( "1.0", "UTF\-8" );
 247 .Ve
 248 .Sp
 249 is therefore a shortcut for
 250 .Sp
 251 .Vb 1
 252 \&  my $document = XML::LibXML::Document\->createDocument( "1.0", "UTF\-8" );
 253 .Ve
 254 .IP "\s-1URI\s0" 4
 255 .IX Item "URI"
 256 .Vb 1
 257 \&  $strURI = $doc\->URI();
 258 .Ve
 259 .Sp
 260 Returns the \s-1URI\s0 (or filename) of the original document. For documents obtained
 261 by parsing a string of a \s-1FH\s0 without using the \s-1URI\s0 parsing argument of the
 262 corresponding \f(CW\*(C`parse_*\*(C'\fR function, the result is a generated string unknown-XYZ where \s-1XYZ\s0 is some
 263 number; for documents created with the constructor \f(CW\*(C`new\*(C'\fR, the \s-1URI\s0 is undefined.
 264 .Sp
 265 The value can be modified by calling \f(CW\*(C`setURI\*(C'\fR method on the document node.
 266 .IP "setURI" 4
 267 .IX Item "setURI"
 268 .Vb 1
 269 \&  $doc\->setURI($strURI);
 270 .Ve
 271 .Sp
 272 Sets the \s-1URI\s0 of the document reported by the method \s-1URI\s0 (see also the \s-1URI\s0
 273 argument to the various \f(CW\*(C`parse_*\*(C'\fR functions).
 274 .IP "encoding" 4
 275 .IX Item "encoding"
 276 .Vb 1
 277 \&  $strEncoding = $doc\->encoding();
 278 .Ve
 279 .Sp
 280 returns the encoding string of the document.
 281 .Sp
 282 .Vb 2
 283 \&  my $doc = XML::LibXML\->createDocument( "1.0", "ISO\-8859\-15" );
 284 \&  print $doc\->encoding; # prints ISO\-8859\-15
 285 .Ve
 286 .IP "actualEncoding" 4
 287 .IX Item "actualEncoding"
 288 .Vb 1
 289 \&  $strEncoding = $doc\->actualEncoding();
 290 .Ve
 291 .Sp
 292 returns the encoding in which the \s-1XML\s0 will be returned by \f(CW$doc\fR\->\fItoString()\fR.
 293 This is usually the original encoding of the document as declared in the \s-1XML\s0
 294 declaration and returned by \f(CW$doc\fR\->encoding. If the original encoding is not
 295 known (e.g. if created in memory or parsed from a \s-1XML\s0 without a declared
 296 encoding), '\s-1UTF\-8\s0' is returned.
 297 .Sp
 298 .Vb 2
 299 \&  my $doc = XML::LibXML\->createDocument( "1.0", "ISO\-8859\-15" );
 300 \&  print $doc\->encoding; # prints ISO\-8859\-15
 301 .Ve
 302 .IP "setEncoding" 4
 303 .IX Item "setEncoding"
 304 .Vb 1
 305 \&  $doc\->setEncoding($new_encoding);
 306 .Ve
 307 .Sp
 308 This method allows to change the declaration of encoding in the \s-1XML\s0 declaration
 309 of the document. The value also affects the encoding in which the document is
 310 serialized to \s-1XML\s0 by \f(CW$doc\fR\->\fItoString()\fR. Use \fIsetEncoding()\fR to remove the encoding
 311 declaration.
 312 .IP "version" 4
 313 .IX Item "version"
 314 .Vb 1
 315 \&  $strVersion = $doc\->version();
 316 .Ve
 317 .Sp
 318 returns the version string of the document
 319 .Sp
 320 \&\fI\fIgetVersion()\fI\fR is an alternative form of this function.
 321 .IP "standalone" 4
 322 .IX Item "standalone"
 323 .Vb 1
 324 \&  $doc\->standalone
 325 .Ve
 326 .Sp
 327 This function returns the Numerical value of a documents \s-1XML\s0 declarations
 328 standalone attribute. It returns \fI1\fR if standalone=\*(L"yes\*(R" was found, \fI0\fR if standalone=\*(L"no\*(R" was found and \fI\-1\fR if standalone was not specified (default on creation).
 329 .IP "setStandalone" 4
 330 .IX Item "setStandalone"
 331 .Vb 1
 332 \&  $doc\->setStandalone($numvalue);
 333 .Ve
 334 .Sp
 335 Through this method it is possible to alter the value of a documents standalone
 336 attribute. Set it to \fI1\fR to set standalone=\*(L"yes\*(R", to \fI0\fR to set standalone=\*(L"no\*(R" or set it to \fI\-1\fR to remove the standalone attribute from the \s-1XML\s0 declaration.
 337 .IP "compression" 4
 338 .IX Item "compression"
 339 .Vb 1
 340 \&  my $compression = $doc\->compression;
 341 .Ve
 342 .Sp
 343 libxml2 allows reading of documents directly from gzipped files. In this case
 344 the compression variable is set to the compression level of that file (0\-8). If
 345 XML::LibXML parsed a different source or the file wasn't compressed, the
 346 returned value will be \fI\-1\fR.
 347 .IP "setCompression" 4
 348 .IX Item "setCompression"
 349 .Vb 1
 350 \&  $doc\->setCompression($ziplevel);
 351 .Ve
 352 .Sp
 353 If one intends to write the document directly to a file, it is possible to set
 354 the compression level for a given document. This level can be in the range from
 355 0 to 8. If XML::LibXML should not try to compress use \fI\-1\fR (default).
 356 .Sp
 357 Note that this feature will \fIonly\fR work if libxml2 is compiled with zlib support and \fItoFile()\fR is used for output.
 358 .IP "toString" 4
 359 .IX Item "toString"
 360 .Vb 1
 361 \&  $docstring = $dom\->toString($format);
 362 .Ve
 363 .Sp
 364 \&\fItoString\fR is a \s-1DOM\s0 serializing function, so the \s-1DOM\s0 Tree is serialized into a \s-1XML\s0 string,
 365 ready for output.
 366 .Sp
 367 \&\s-1IMPORTANT:\s0 unlike toString for other nodes, on document nodes this function
 368 returns the \s-1XML\s0 as a byte string in the original encoding of the document (see
 369 the \fIactualEncoding()\fR method)! This means you can simply do:
 370 .Sp
 371 .Vb 2
 372 \&  open OUT, $file;
 373 \&  print OUT $doc\->toString;
 374 .Ve
 375 .Sp
 376 regardless of the actual encoding of the document. See the section on encodings
 377 in XML::LibXML for more details.
 378 .Sp
 379 The optional \fI\f(CI$format\fI\fR parameter sets the indenting of the output. This parameter is expected to be an \f(CW\*(C`integer\*(C'\fR value, that specifies that indentation should be used. The format parameter can
 380 have three different values if it is used:
 381 .Sp
 382 If \f(CW$format\fR is 0, than the document is dumped as it was originally parsed
 383 .Sp
 384 If \f(CW$format\fR is 1, libxml2 will add ignorable white spaces, so the nodes content
 385 is easier to read. Existing text nodes will not be altered
 386 .Sp
 387 If \f(CW$format\fR is 2 (or higher), libxml2 will act as \f(CW$format\fR == 1 but it add a
 388 leading and a trailing line break to each text node.
 389 .Sp
 390 libxml2 uses a hard-coded indentation of 2 space characters per indentation
 391 level. This value can not be altered on run-time.
 392 .IP "toStringC14N" 4
 393 .IX Item "toStringC14N"
 394 .Vb 1
 395 \&  $c14nstr = $doc\->toStringC14N($comment_flag, $xpath [, $xpath_context ]);
 396 .Ve
 397 .Sp
 398 See the documentation in XML::LibXML::Node.
 399 .IP "toStringEC14N" 4
 400 .IX Item "toStringEC14N"
 401 .Vb 1
 402 \&  $ec14nstr = $doc\->toStringEC14N($comment_flag, $xpath [, $xpath_context ], $inclusive_prefix_list);
 403 .Ve
 404 .Sp
 405 See the documentation in XML::LibXML::Node.
 406 .IP "serialize" 4
 407 .IX Item "serialize"
 408 .Vb 1
 409 \&  $str = $doc\->serialize($format);
 410 .Ve
 411 .Sp
 412 An alias for \fItoString()\fR. This function was name added to be more consistent
 413 with libxml2.
 414 .IP "serialize_c14n" 4
 415 .IX Item "serialize_c14n"
 416 An alias for \fItoStringC14N()\fR.
 417 .IP "serialize_exc_c14n" 4
 418 .IX Item "serialize_exc_c14n"
 419 An alias for \fItoStringEC14N()\fR.
 420 .IP "toFile" 4
 421 .IX Item "toFile"
 422 .Vb 1
 423 \&  $state = $doc\->toFile($filename, $format);
 424 .Ve
 425 .Sp
 426 This function is similar to \fItoString()\fR, but it writes the document directly
 427 into a filesystem. This function is very useful, if one needs to store large
 428 documents.
 429 .Sp
 430 The format parameter has the same behaviour as in \fItoString()\fR.
 431 .IP "toFH" 4
 432 .IX Item "toFH"
 433 .Vb 1
 434 \&  $state = $doc\->toFH($fh, $format);
 435 .Ve
 436 .Sp
 437 This function is similar to \fItoString()\fR, but it writes the document directly to
 438 a filehandle or a stream. A byte stream in the document encoding is passed to
 439 the file handle. Do \s-1NOT\s0 apply any \f(CW\*(C`:encoding(...)\*(C'\fR or \f(CW\*(C`:utf8\*(C'\fR PerlIO layer to the filehandle! See the section on encodings in XML::LibXML for more details.
 440 .Sp
 441 The format parameter has the same behaviour as in \fItoString()\fR.
 442 .IP "toStringHTML" 4
 443 .IX Item "toStringHTML"
 444 .Vb 1
 445 \&  $str = $document\->toStringHTML();
 446 .Ve
 447 .Sp
 448 \&\fItoStringHTML\fR serialize the tree to a byte string in the document encoding as \s-1HTML\s0. With this
 449 method indenting is automatic and managed by libxml2 internally.
 450 .IP "serialize_html" 4
 451 .IX Item "serialize_html"
 452 .Vb 1
 453 \&  $str = $document\->serialize_html();
 454 .Ve
 455 .Sp
 456 An alias for \fItoStringHTML()\fR.
 457 .IP "is_valid" 4
 458 .IX Item "is_valid"
 459 .Vb 1
 460 \&  $bool = $dom\->is_valid();
 461 .Ve
 462 .Sp
 463 Returns either \s-1TRUE\s0 or \s-1FALSE\s0 depending on whether the \s-1DOM\s0 Tree is a valid
 464 Document or not.
 465 .Sp
 466 You may also pass in a XML::LibXML::Dtd object, to validate against an external \s-1DTD:\s0
 467 .Sp
 468 .Vb 3
 469 \&  if (!$dom\->is_valid($dtd)) {
 470 \&       warn("document is not valid!");
 471 \&   }
 472 .Ve
 473 .IP "validate" 4
 474 .IX Item "validate"
 475 .Vb 1
 476 \&  $dom\->validate();
 477 .Ve
 478 .Sp
 479 This is an exception throwing equivalent of is_valid. If the document is not
 480 valid it will throw an exception containing the error. This allows you much
 481 better error reporting than simply is_valid or not.
 482 .Sp
 483 Again, you may pass in a \s-1DTD\s0 object
 484 .IP "documentElement" 4
 485 .IX Item "documentElement"
 486 .Vb 1
 487 \&  $root = $dom\->documentElement();
 488 .Ve
 489 .Sp
 490 Returns the root element of the Document. A document can have just one root
 491 element to contain the documents data.
 492 .Sp
 493 Optionally one can use \fIgetDocumentElement\fR.
 494 .IP "setDocumentElement" 4
 495 .IX Item "setDocumentElement"
 496 .Vb 1
 497 \&  $dom\->setDocumentElement( $root );
 498 .Ve
 499 .Sp
 500 This function enables you to set the root element for a document. The function
 501 supports the import of a node from a different document tree, but does not
 502 support a document fragment as \f(CW$root\fR.
 503 .IP "createElement" 4
 504 .IX Item "createElement"
 505 .Vb 1
 506 \&  $element = $dom\->createElement( $nodename );
 507 .Ve
 508 .Sp
 509 This function creates a new Element Node bound to the \s-1DOM\s0 with the name \f(CW$nodename\fR.
 510 .IP "createElementNS" 4
 511 .IX Item "createElementNS"
 512 .Vb 1
 513 \&  $element = $dom\->createElementNS( $namespaceURI, $qname );
 514 .Ve
 515 .Sp
 516 This function creates a new Element Node bound to the \s-1DOM\s0 with the name \f(CW$nodename\fR and placed in the given namespace.
 517 .IP "createTextNode" 4
 518 .IX Item "createTextNode"
 519 .Vb 1
 520 \&  $text = $dom\->createTextNode( $content_text );
 521 .Ve
 522 .Sp
 523 As an equivalent of \fIcreateElement\fR, but it creates a \fIText Node\fR bound to the \s-1DOM\s0.
 524 .IP "createComment" 4
 525 .IX Item "createComment"
 526 .Vb 1
 527 \&  $comment = $dom\->createComment( $comment_text );
 528 .Ve
 529 .Sp
 530 As an equivalent of \fIcreateElement\fR, but it creates a \fIComment Node\fR bound to the \s-1DOM\s0.
 531 .IP "createAttribute" 4
 532 .IX Item "createAttribute"
 533 .Vb 1
 534 \&  $attrnode = $doc\->createAttribute($name [,$value]);
 535 .Ve
 536 .Sp
 537 Creates a new Attribute node.
 538 .IP "createAttributeNS" 4
 539 .IX Item "createAttributeNS"
 540 .Vb 1
 541 \&  $attrnode = $doc\->createAttributeNS( namespaceURI, $name [,$value] );
 542 .Ve
 543 .Sp
 544 Creates an Attribute bound to a namespace.
 545 .IP "createDocumentFragment" 4
 546 .IX Item "createDocumentFragment"
 547 .Vb 1
 548 \&  $fragment = $doc\->createDocumentFragment();
 549 .Ve
 550 .Sp
 551 This function creates a DocumentFragment.
 552 .IP "createCDATASection" 4
 553 .IX Item "createCDATASection"
 554 .Vb 1
 555 \&  $cdata = $dom\->create( $cdata_content );
 556 .Ve
 557 .Sp
 558 Similar to createTextNode and createComment, this function creates a
 559 CDataSection bound to the current \s-1DOM\s0.
 560 .IP "createProcessingInstruction" 4
 561 .IX Item "createProcessingInstruction"
 562 .Vb 1
 563 \&  my $pi = $doc\->createProcessingInstruction( $target, $data );
 564 .Ve
 565 .Sp
 566 create a processing instruction node.
 567 .Sp
 568 Since this method is quite long one may use its short form \fI\fIcreatePI()\fI\fR.
 569 .IP "createEntityReference" 4
 570 .IX Item "createEntityReference"
 571 .Vb 1
 572 \&  my $entref = $doc\->createEntityReference($refname);
 573 .Ve
 574 .Sp
 575 If a document has a \s-1DTD\s0 specified, one can create entity references by using
 576 this function. If one wants to add a entity reference to the document, this
 577 reference has to be created by this function.
 578 .Sp
 579 An entity reference is unique to a document and cannot be passed to other
 580 documents as other nodes can be passed.
 581 .Sp
 582 \&\fI\s-1NOTE:\s0\fR A text content containing something that looks like an entity reference, will
 583 not be expanded to a real entity reference unless it is a predefined entity
 584 .Sp
 585 .Vb 3
 586 \&  my $string = "&foo;";
 587 \&   $some_element\->appendText( $string );
 588 \&   print $some_element\->textContent; # prints "&amp;foo;"
 589 .Ve
 590 .IP "createInternalSubset" 4
 591 .IX Item "createInternalSubset"
 592 .Vb 1
 593 \&  $dtd = $document\->createInternalSubset( $rootnode, $public, $system);
 594 .Ve
 595 .Sp
 596 This function creates and adds an internal subset to the given document.
 597 Because the function automatically adds the \s-1DTD\s0 to the document there is no
 598 need to add the created node explicitly to the document.
 599 .Sp
 600 .Vb 2
 601 \&  my $document = XML::LibXML::Document\->new();
 602 \&   my $dtd      = $document\->createInternalSubset( "foo", undef, "foo.dtd" );
 603 .Ve
 604 .Sp
 605 will result in the following \s-1XML\s0 document:
 606 .Sp
 607 .Vb 2
 608 \&  <?xml version="1.0"?>
 609 \&   <!DOCTYPE foo SYSTEM "foo.dtd">
 610 .Ve
 611 .Sp
 612 By setting the public parameter it is possible to set \s-1PUBLIC\s0 DTDs to a given
 613 document. So
 614 .Sp
 615 .Vb 2
 616 \&  my $document = XML::LibXML::Document\->new();
 617 \&  my $dtd      = $document\->createInternalSubset( "foo", "\-//FOO//DTD FOO 0.1//EN", undef );
 618 .Ve
 619 .Sp
 620 will cause the following declaration to be created on the document:
 621 .Sp
 622 .Vb 2
 623 \&  <?xml version="1.0"?>
 624 \&  <!DOCTYPE foo PUBLIC "\-//FOO//DTD FOO 0.1//EN">
 625 .Ve
 626 .IP "createExternalSubset" 4
 627 .IX Item "createExternalSubset"
 628 .Vb 1
 629 \&  $dtd = $document\->createExternalSubset( $rootnode_name, $publicId, $systemId);
 630 .Ve
 631 .Sp
 632 This function is similar to \f(CW\*(C`createInternalSubset()\*(C'\fR but this \s-1DTD\s0 is considered to be external and is therefore not added to the
 633 document itself. Nevertheless it can be used for validation purposes.
 634 .IP "importNode" 4
 635 .IX Item "importNode"
 636 .Vb 1
 637 \&  $document\->importNode( $node );
 638 .Ve
 639 .Sp
 640 If a node is not part of a document, it can be imported to another document. As
 641 specified in \s-1DOM\s0 Level 2 Specification the Node will not be altered or removed
 642 from its original document (\f(CW\*(C`$node\->cloneNode(1)\*(C'\fR will get called implicitly).
 643 .Sp
 644 \&\fI\s-1NOTE:\s0\fR Don't try to use \fIimportNode()\fR to import sub-trees that contain an entity
 645 reference \- even if the entity reference is the root node of the sub-tree. This
 646 will cause serious problems to your program. This is a limitation of libxml2
 647 and not of XML::LibXML itself.
 648 .IP "adoptNode" 4
 649 .IX Item "adoptNode"
 650 .Vb 1
 651 \&  $document\->adoptNode( $node );
 652 .Ve
 653 .Sp
 654 If a node is not part of a document, it can be imported to another document. As
 655 specified in \s-1DOM\s0 Level 3 Specification the Node will not be altered but it will
 656 removed from its original document.
 657 .Sp
 658 After a document adopted a node, the node, its attributes and all its
 659 descendants belong to the new document. Because the node does not belong to the
 660 old document, it will be unlinked from its old location first.
 661 .Sp
 662 \&\fI\s-1NOTE:\s0\fR Don't try to \fIadoptNode()\fR to import sub-trees that contain entity references \-
 663 even if the entity reference is the root node of the sub-tree. This will cause
 664 serious problems to your program. This is a limitation of libxml2 and not of
 665 XML::LibXML itself.
 666 .IP "externalSubset" 4
 667 .IX Item "externalSubset"
 668 .Vb 1
 669 \&  my $dtd = $doc\->externalSubset;
 670 .Ve
 671 .Sp
 672 If a document has an external subset defined it will be returned by this
 673 function.
 674 .Sp
 675 \&\fI\s-1NOTE\s0\fR Dtd nodes are no ordinary nodes in libxml2. The support for these nodes in
 676 XML::LibXML is still limited. In particular one may not want use common node
 677 function on doctype declaration nodes!
 678 .IP "internalSubset" 4
 679 .IX Item "internalSubset"
 680 .Vb 1
 681 \&  my $dtd = $doc\->internalSubset;
 682 .Ve
 683 .Sp
 684 If a document has an internal subset defined it will be returned by this
 685 function.
 686 .Sp
 687 \&\fI\s-1NOTE\s0\fR Dtd nodes are no ordinary nodes in libxml2. The support for these nodes in
 688 XML::LibXML is still limited. In particular one may not want use common node
 689 function on doctype declaration nodes!
 690 .IP "setExternalSubset" 4
 691 .IX Item "setExternalSubset"
 692 .Vb 1
 693 \&  $doc\->setExternalSubset($dtd);
 694 .Ve
 695 .Sp
 696 \&\fI\s-1EXPERIMENTAL\s0!\fR
 697 .Sp
 698 This method sets a \s-1DTD\s0 node as an external subset of the given document.
 699 .IP "setInternalSubset" 4
 700 .IX Item "setInternalSubset"
 701 .Vb 1
 702 \&  $doc\->setInternalSubset($dtd);
 703 .Ve
 704 .Sp
 705 \&\fI\s-1EXPERIMENTAL\s0!\fR
 706 .Sp
 707 This method sets a \s-1DTD\s0 node as an internal subset of the given document.
 708 .IP "removeExternalSubset" 4
 709 .IX Item "removeExternalSubset"
 710 .Vb 1
 711 \&  my $dtd = $doc\->removeExternalSubset();
 712 .Ve
 713 .Sp
 714 \&\fI\s-1EXPERIMENTAL\s0!\fR
 715 .Sp
 716 If a document has an external subset defined it can be removed from the
 717 document by using this function. The removed dtd node will be returned.
 718 .IP "removeInternalSubset" 4
 719 .IX Item "removeInternalSubset"
 720 .Vb 1
 721 \&  my $dtd = $doc\->removeInternalSubset();
 722 .Ve
 723 .Sp
 724 \&\fI\s-1EXPERIMENTAL\s0!\fR
 725 .Sp
 726 If a document has an internal subset defined it can be removed from the
 727 document by using this function. The removed dtd node will be returned.
 728 .IP "getElementsByTagName" 4
 729 .IX Item "getElementsByTagName"
 730 .Vb 1
 731 \&  my @nodelist = $doc\->getElementsByTagName($tagname);
 732 .Ve
 733 .Sp
 734 Implements the \s-1DOM\s0 Level 2 function
 735 .Sp
 736 In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
 737 .IP "getElementsByTagNameNS" 4
 738 .IX Item "getElementsByTagNameNS"
 739 .Vb 1
 740 \&  my @nodelist = $doc\->getElementsByTagNameNS($nsURI,$tagname);
 741 .Ve
 742 .Sp
 743 Implements the \s-1DOM\s0 Level 2 function
 744 .Sp
 745 In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
 746 .IP "getElementsByLocalName" 4
 747 .IX Item "getElementsByLocalName"
 748 .Vb 1
 749 \&  my @nodelist = $doc\->getElementsByLocalName($localname);
 750 .Ve
 751 .Sp
 752 This allows the fetching of all nodes from a given document with the given
 753 Localname.
 754 .Sp
 755 In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
 756 .IP "getElementById" 4
 757 .IX Item "getElementById"
 758 .Vb 1
 759 \&  my $node = $doc\->getElementById($id);
 760 .Ve
 761 .Sp
 762 Returns the element that has an \s-1ID\s0 attribute with the given value. If no such
 763 element exists, this returns undef.
 764 .Sp
 765 Note: the \s-1ID\s0 of an element may change while manipulating the document. For
 766 documents with a \s-1DTD\s0, the information about \s-1ID\s0 attributes is only available if
 767 \&\s-1DTD\s0 loading/validation has been requested. For \s-1HTML\s0 documents parsed with the
 768 \&\s-1HTML\s0 parser \s-1ID\s0 detection is done automatically. In \s-1XML\s0 documents, all \*(L"xml:id\*(R"
 769 attributes are considered to be of type \s-1ID\s0. You can test ID-ness of an
 770 attribute node with \f(CW$attr\fR\->\fIisId()\fR.
 771 .Sp
 772 In versions 1.59 and earlier this method was called \fIgetElementsById()\fR (plural)
 773 by mistake. Starting from 1.60 this name is maintained as an alias only for
 774 backward compatibility.
 775 .IP "indexElements" 4
 776 .IX Item "indexElements"
 777 .Vb 1
 778 \&  $dom\->indexElements();
 779 .Ve
 780 .Sp
 781 This function causes libxml2 to stamp all elements in a document with their
 782 document position index which considerably speeds up XPath queries for large
 783 documents. It should only be used with static documents that won't be further
 784 changed by any \s-1DOM\s0 methods, because once a document is indexed, XPath will
 785 always prefer the index to other methods of determining the document order of
 786 nodes. XPath could therefore return improperly ordered node-lists when applied
 787 on a document that has been changed after being indexed. It is of course
 788 possible to use this method to re-index a modified document before using it
 789 with XPath again. This function is not a part of the \s-1DOM\s0 specification.
 790 .Sp
 791 This function returns number of elements indexed, \-1 if error occurred, or \-2
 792 if this feature is not available in the running libxml2.
 793 .SH "AUTHORS"
 794 .IX Header "AUTHORS"
 795 Matt Sergeant,
 796 Christian Glahn,
 797 Petr Pajas
 798 .SH "VERSION"
 799 .IX Header "VERSION"
 800 1.70
 801 .SH "COPYRIGHT"
 802 .IX Header "COPYRIGHT"
 803 2001\-2007, AxKit.com Ltd.
 804 .PP
 805 2002\-2006, Christian Glahn.
 806 .PP
 807 2006\-2009, Petr Pajas.