.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XML::LibXML::Document 3"
.TH XML::LibXML::Document 3 "2016-07-24" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::LibXML::Document \- XML::LibXML DOM Document Class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use XML::LibXML;
\&  # Only methods specific to Document nodes are listed here,
\&  # see the XML::LibXML::Node manpage for other methods
\&
\&  $dom = XML::LibXML::Document\->new( $version, $encoding );
\&  $dom = XML::LibXML::Document\->createDocument( $version, $encoding );
\&  $strURI = $doc\->URI();
\&  $doc\->setURI($strURI);
\&  $strEncoding = $doc\->encoding();
\&  $strEncoding = $doc\->actualEncoding();
\&  $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 [, $xpath_context ]);
\&  $ec14nstr = $doc\->toStringEC14N($comment_flag, $xpath [, $xpath_context ], $inclusive_prefix_list);
\&  $str = $doc\->serialize($format);
\&  $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, $nodename );
\&  $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\->createCDATASection( $cdata_content );
\&  my $pi = $doc\->createProcessingInstruction( $target, $data );
\&  my $entref = $doc\->createEntityReference($refname);
\&  $dtd = $document\->createInternalSubset( $rootnode, $public, $system);
\&  $dtd = $document\->createExternalSubset( $rootnode_name, $publicId, $systemId);
\&  $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\->getElementsByTagNameNS($nsURI,$tagname);
\&  my @nodelist = $doc\->getElementsByLocalName($localname);
\&  my $node = $doc\->getElementById($id);
\&  $dom\->indexElements();
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1DOM\s0 Document
Class provides functions that conform to the \s-1DOM\s0 Core naming style.
.PP
It inherits all functions from XML::LibXML::Node as specified in the \s-1DOM\s0 specification. This enables access to the nodes besides
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.
.PP
While generally nodes are bound to a document in the \s-1DOM\s0 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 text node with an \s-1ISO\s0 encoded string is created (e.g.
with \f(CW$CLASS\fR\->\fInew()\fR), the \f(CW\*(C`toString\*(C'\fR function may not return the expected result.
.PP
To prevent such problems, it is recommended to pass all data to XML::LibXML
methods as character strings (i.e. \s-1UTF\-8\s0 encoded, with the \s-1UTF8\s0 flag on).
.SH "METHODS"
.IX Header "METHODS"
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.
.IP "new" 4
.IX Item "new"
.Vb 1
\&  $dom = XML::LibXML::Document\->new( $version, $encoding );
.Ve
.Sp
alias for \fIcreateDocument()\fR
.IP "createDocument" 4
.IX Item "createDocument"
.Vb 1
\&  $dom = XML::LibXML::Document\->createDocument( $version, $encoding );
.Ve
.Sp
The constructor for the document class. As Parameter it takes the version
string and (optionally) the encoding string. Simply calling \fIcreateDocument\fR() will create the document:
.Sp
.Vb 1
\&  <?xml version="your version" encoding="your encoding"?>
.Ve
.Sp
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
implied.
.Sp
The call of \fIcreateDocument\fR() without any parameter will result the following code:
.Sp
.Vb 1
\&  <?xml version="1.0"?>
.Ve
.Sp
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.
.Sp
.Vb 1
\&  my $document = XML::LibXML\->createDocument( "1.0", "UTF\-8" );
.Ve
.Sp
is therefore a shortcut for
.Sp
.Vb 1
\&  my $document = XML::LibXML::Document\->createDocument( "1.0", "UTF\-8" );
.Ve
.IP "\s-1URI\s0" 4
.IX Item "URI"
.Vb 1
\&  $strURI = $doc\->URI();
.Ve
.Sp
Returns the \s-1URI \s0(or filename) of the original document. For documents obtained
by parsing a string of a \s-1FH\s0 without using the \s-1URI\s0 parsing argument of the
corresponding \f(CW\*(C`parse_*\*(C'\fR function, the result is a generated string unknown-XYZ where \s-1XYZ\s0 is some
number; for documents created with the constructor \f(CW\*(C`new\*(C'\fR, the \s-1URI\s0 is undefined.
.Sp
The value can be modified by calling \f(CW\*(C`setURI\*(C'\fR method on the document node.
.IP "setURI" 4
.IX Item "setURI"
.Vb 1
\&  $doc\->setURI($strURI);
.Ve
.Sp
Sets the \s-1URI\s0 of the document reported by the method \s-1URI \s0(see also the \s-1URI\s0
argument to the various \f(CW\*(C`parse_*\*(C'\fR functions).
.IP "encoding" 4
.IX Item "encoding"
.Vb 1
\&  $strEncoding = $doc\->encoding();
.Ve
.Sp
returns the encoding string of the document.
.Sp
.Vb 2
\&  my $doc = XML::LibXML\->createDocument( "1.0", "ISO\-8859\-15" );
\&  print $doc\->encoding; # prints ISO\-8859\-15
.Ve
.IP "actualEncoding" 4
.IX Item "actualEncoding"
.Vb 1
\&  $strEncoding = $doc\->actualEncoding();
.Ve
.Sp
returns the encoding in which the \s-1XML\s0 will be returned by \f(CW$doc\fR\->\fItoString()\fR.
This is usually the original encoding of the document as declared in the \s-1XML\s0
declaration and returned by \f(CW$doc\fR\->encoding. If the original encoding is not
known (e.g. if created in memory or parsed from a \s-1XML\s0 without a declared
encoding), '\s-1UTF\-8\s0' is returned.
.Sp
.Vb 2
\&  my $doc = XML::LibXML\->createDocument( "1.0", "ISO\-8859\-15" );
\&  print $doc\->encoding; # prints ISO\-8859\-15
.Ve
.IP "setEncoding" 4
.IX Item "setEncoding"
.Vb 1
\&  $doc\->setEncoding($new_encoding);
.Ve
.Sp
This method allows one to change the declaration of encoding in the \s-1XML\s0
declaration of the document. The value also affects the encoding in which the
document is serialized to \s-1XML\s0 by \f(CW$doc\fR\->\fItoString()\fR. Use \fIsetEncoding()\fR to remove
the encoding declaration.
.IP "version" 4
.IX Item "version"
.Vb 1
\&  $strVersion = $doc\->version();
.Ve
.Sp
returns the version string of the document
.Sp
\&\fI\fIgetVersion()\fI\fR is an alternative form of this function.
.IP "standalone" 4
.IX Item "standalone"
.Vb 1
\&  $doc\->standalone
.Ve
.Sp
This function returns the Numerical value of a documents \s-1XML\s0 declarations
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).
.IP "setStandalone" 4
.IX Item "setStandalone"
.Vb 1
\&  $doc\->setStandalone($numvalue);
.Ve
.Sp
Through this method it is possible to alter the value of a documents standalone
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.
.IP "compression" 4
.IX Item "compression"
.Vb 1
\&  my $compression = $doc\->compression;
.Ve
.Sp
libxml2 allows reading of documents directly from gzipped 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 \fI\-1\fR.
.IP "setCompression" 4
.IX Item "setCompression"
.Vb 1
\&  $doc\->setCompression($ziplevel);
.Ve
.Sp
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 \fI\-1\fR (default).
.Sp
Note that this feature will \fIonly\fR work if libxml2 is compiled with zlib support and \fItoFile()\fR is used for output.
.IP "toString" 4
.IX Item "toString"
.Vb 1
\&  $docstring = $dom\->toString($format);
.Ve
.Sp
\&\fItoString\fR is a \s-1DOM\s0 serializing function, so the \s-1DOM\s0 Tree is serialized into an \s-1XML\s0
string, ready for output.
.Sp
\&\s-1IMPORTANT:\s0 unlike toString for other nodes, on document nodes this function
returns the \s-1XML\s0 as a byte string in the original encoding of the document (see
the \fIactualEncoding()\fR method)! This means you can simply do:
.Sp
.Vb 2
\&  open my $out_fh, \*(Aq>\*(Aq, $file;
\&  print {$out_fh} $doc\->toString;
.Ve
.Sp
regardless of the actual encoding of the document. See the section on encodings
in XML::LibXML for more details.
.Sp
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
have three different values if it is used:
.Sp
If \f(CW$format\fR is 0, than the document is dumped as it was originally parsed
.Sp
If \f(CW$format\fR is 1, libxml2 will add ignorable white spaces, so the nodes content
is easier to read. Existing text nodes will not be altered
.Sp
If \f(CW$format\fR is 2 (or higher), libxml2 will act as \f(CW$format\fR == 1 but it add a
leading and a trailing line break to each text node.
.Sp
libxml2 uses a hard-coded indentation of 2 space characters per indentation
level. This value can not be altered on run-time.
.IP "toStringC14N" 4
.IX Item "toStringC14N"
.Vb 1
\&  $c14nstr = $doc\->toStringC14N($comment_flag, $xpath [, $xpath_context ]);
.Ve
.Sp
See the documentation in XML::LibXML::Node.
.IP "toStringEC14N" 4
.IX Item "toStringEC14N"
.Vb 1
\&  $ec14nstr = $doc\->toStringEC14N($comment_flag, $xpath [, $xpath_context ], $inclusive_prefix_list);
.Ve
.Sp
See the documentation in XML::LibXML::Node.
.IP "serialize" 4
.IX Item "serialize"
.Vb 1
\&  $str = $doc\->serialize($format);
.Ve
.Sp
An alias for \fItoString()\fR. This function was name added to be more consistent
with libxml2.
.IP "serialize_c14n" 4
.IX Item "serialize_c14n"
An alias for \fItoStringC14N()\fR.
.IP "serialize_exc_c14n" 4
.IX Item "serialize_exc_c14n"
An alias for \fItoStringEC14N()\fR.
.IP "toFile" 4
.IX Item "toFile"
.Vb 1
\&  $state = $doc\->toFile($filename, $format);
.Ve
.Sp
This function is similar to \fItoString()\fR, but it writes the document directly
into a filesystem. This function is very useful, if one needs to store large
documents.
.Sp
The format parameter has the same behaviour as in \fItoString()\fR.
.IP "toFH" 4
.IX Item "toFH"
.Vb 1
\&  $state = $doc\->toFH($fh, $format);
.Ve
.Sp
This function is similar to \fItoString()\fR, but it writes the document directly to
a filehandle or a stream. A byte stream in the document encoding is passed to
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.
.Sp
The format parameter has the same behaviour as in \fItoString()\fR.
.IP "toStringHTML" 4
.IX Item "toStringHTML"
.Vb 1
\&  $str = $document\->toStringHTML();
.Ve
.Sp
\&\fItoStringHTML\fR serialize the tree to a byte string in the document encoding as \s-1HTML.\s0 With this
method indenting is automatic and managed by libxml2 internally.
.IP "serialize_html" 4
.IX Item "serialize_html"
.Vb 1
\&  $str = $document\->serialize_html();
.Ve
.Sp
An alias for \fItoStringHTML()\fR.
.IP "is_valid" 4
.IX Item "is_valid"
.Vb 1
\&  $bool = $dom\->is_valid();
.Ve
.Sp
Returns either \s-1TRUE\s0 or \s-1FALSE\s0 depending on whether the \s-1DOM\s0 Tree is a valid
Document or not.
.Sp
You may also pass in a XML::LibXML::Dtd object, to validate against an external \s-1DTD:\s0
.Sp
.Vb 3
\&  if (!$dom\->is_valid($dtd)) {
\&       warn("document is not valid!");
\&   }
.Ve
.IP "validate" 4
.IX Item "validate"
.Vb 1
\&  $dom\->validate();
.Ve
.Sp
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.
.Sp
Again, you may pass in a \s-1DTD\s0 object
.IP "documentElement" 4
.IX Item "documentElement"
.Vb 1
\&  $root = $dom\->documentElement();
.Ve
.Sp
Returns the root element of the Document. A document can have just one root
element to contain the documents data.
.Sp
Optionally one can use \fIgetDocumentElement\fR.
.IP "setDocumentElement" 4
.IX Item "setDocumentElement"
.Vb 1
\&  $dom\->setDocumentElement( $root );
.Ve
.Sp
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, but does not
support a document fragment as \f(CW$root\fR.
.IP "createElement" 4
.IX Item "createElement"
.Vb 1
\&  $element = $dom\->createElement( $nodename );
.Ve
.Sp
This function creates a new Element Node bound to the \s-1DOM\s0 with the name \f(CW$nodename\fR.
.IP "createElementNS" 4
.IX Item "createElementNS"
.Vb 1
\&  $element = $dom\->createElementNS( $namespaceURI, $nodename );
.Ve
.Sp
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.
.IP "createTextNode" 4
.IX Item "createTextNode"
.Vb 1
\&  $text = $dom\->createTextNode( $content_text );
.Ve
.Sp
As an equivalent of \fIcreateElement\fR, but it creates a \fIText Node\fR bound to the \s-1DOM.\s0
.IP "createComment" 4
.IX Item "createComment"
.Vb 1
\&  $comment = $dom\->createComment( $comment_text );
.Ve
.Sp
As an equivalent of \fIcreateElement\fR, but it creates a \fIComment Node\fR bound to the \s-1DOM.\s0
.IP "createAttribute" 4
.IX Item "createAttribute"
.Vb 1
\&  $attrnode = $doc\->createAttribute($name [,$value]);
.Ve
.Sp
Creates a new Attribute node.
.IP "createAttributeNS" 4
.IX Item "createAttributeNS"
.Vb 1
\&  $attrnode = $doc\->createAttributeNS( namespaceURI, $name [,$value] );
.Ve
.Sp
Creates an Attribute bound to a namespace.
.IP "createDocumentFragment" 4
.IX Item "createDocumentFragment"
.Vb 1
\&  $fragment = $doc\->createDocumentFragment();
.Ve
.Sp
This function creates a DocumentFragment.
.IP "createCDATASection" 4
.IX Item "createCDATASection"
.Vb 1
\&  $cdata = $dom\->createCDATASection( $cdata_content );
.Ve
.Sp
Similar to createTextNode and createComment, this function creates a
CDataSection bound to the current \s-1DOM.\s0
.IP "createProcessingInstruction" 4
.IX Item "createProcessingInstruction"
.Vb 1
\&  my $pi = $doc\->createProcessingInstruction( $target, $data );
.Ve
.Sp
create a processing instruction node.
.Sp
Since this method is quite long one may use its short form \fI\fIcreatePI()\fI\fR.
.IP "createEntityReference" 4
.IX Item "createEntityReference"
.Vb 1
\&  my $entref = $doc\->createEntityReference($refname);
.Ve
.Sp
If a document has a \s-1DTD\s0 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.
.Sp
An entity reference is unique to a document and cannot be passed to other
documents as other nodes can be passed.
.Sp
\&\fI\s-1NOTE:\s0\fR 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
.Sp
.Vb 3
\&  my $string = "&foo;";
\&   $some_element\->appendText( $string );
\&   print $some_element\->textContent; # prints "&amp;foo;"
.Ve
.IP "createInternalSubset" 4
.IX Item "createInternalSubset"
.Vb 1
\&  $dtd = $document\->createInternalSubset( $rootnode, $public, $system);
.Ve
.Sp
This function creates and adds an internal subset to the given document.
Because the function automatically adds the \s-1DTD\s0 to the document there is no
need to add the created node explicitly to the document.
.Sp
.Vb 2
\&  my $document = XML::LibXML::Document\->new();
\&   my $dtd      = $document\->createInternalSubset( "foo", undef, "foo.dtd" );
.Ve
.Sp
will result in the following \s-1XML\s0 document:
.Sp
.Vb 2
\&  <?xml version="1.0"?>
\&   <!DOCTYPE foo SYSTEM "foo.dtd">
.Ve
.Sp
By setting the public parameter it is possible to set \s-1PUBLIC\s0 DTDs to a given
document. So
.Sp
.Vb 2
\&  my $document = XML::LibXML::Document\->new();
\&  my $dtd      = $document\->createInternalSubset( "foo", "\-//FOO//DTD FOO 0.1//EN", undef );
.Ve
.Sp
will cause the following declaration to be created on the document:
.Sp
.Vb 2
\&  <?xml version="1.0"?>
\&  <!DOCTYPE foo PUBLIC "\-//FOO//DTD FOO 0.1//EN">
.Ve
.IP "createExternalSubset" 4
.IX Item "createExternalSubset"
.Vb 1
\&  $dtd = $document\->createExternalSubset( $rootnode_name, $publicId, $systemId);
.Ve
.Sp
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
document itself. Nevertheless it can be used for validation purposes.
.IP "importNode" 4
.IX Item "importNode"
.Vb 1
\&  $document\->importNode( $node );
.Ve
.Sp
If a node is not part of a document, it can be imported to another document. As
specified in \s-1DOM\s0 Level 2 Specification the Node will not be altered or removed
from its original document (\f(CW\*(C`$node\->cloneNode(1)\*(C'\fR will get called implicitly).
.Sp
\&\fI\s-1NOTE:\s0\fR Don't try to use \fIimportNode()\fR to import sub-trees that contain an entity
reference \- even if the entity reference is the root node of the sub-tree. This
will cause serious problems to your program. This is a limitation of libxml2
and not of XML::LibXML itself.
.IP "adoptNode" 4
.IX Item "adoptNode"
.Vb 1
\&  $document\->adoptNode( $node );
.Ve
.Sp
If a node is not part of a document, it can be imported to another document. As
specified in \s-1DOM\s0 Level 3 Specification the Node will not be altered but it will
removed from its original document.
.Sp
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.
.Sp
\&\fI\s-1NOTE:\s0\fR Don't try to \fIadoptNode()\fR to import sub-trees that contain entity references \-
even if the entity reference is the root node of the sub-tree. This will cause
serious problems to your program. This is a limitation of libxml2 and not of
XML::LibXML itself.
.IP "externalSubset" 4
.IX Item "externalSubset"
.Vb 1
\&  my $dtd = $doc\->externalSubset;
.Ve
.Sp
If a document has an external subset defined it will be returned by this
function.
.Sp
\&\fI\s-1NOTE\s0\fR 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!
.IP "internalSubset" 4
.IX Item "internalSubset"
.Vb 1
\&  my $dtd = $doc\->internalSubset;
.Ve
.Sp
If a document has an internal subset defined it will be returned by this
function.
.Sp
\&\fI\s-1NOTE\s0\fR 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!
.IP "setExternalSubset" 4
.IX Item "setExternalSubset"
.Vb 1
\&  $doc\->setExternalSubset($dtd);
.Ve
.Sp
\&\fI\s-1EXPERIMENTAL\s0!\fR
.Sp
This method sets a \s-1DTD\s0 node as an external subset of the given document.
.IP "setInternalSubset" 4
.IX Item "setInternalSubset"
.Vb 1
\&  $doc\->setInternalSubset($dtd);
.Ve
.Sp
\&\fI\s-1EXPERIMENTAL\s0!\fR
.Sp
This method sets a \s-1DTD\s0 node as an internal subset of the given document.
.IP "removeExternalSubset" 4
.IX Item "removeExternalSubset"
.Vb 1
\&  my $dtd = $doc\->removeExternalSubset();
.Ve
.Sp
\&\fI\s-1EXPERIMENTAL\s0!\fR
.Sp
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.
.IP "removeInternalSubset" 4
.IX Item "removeInternalSubset"
.Vb 1
\&  my $dtd = $doc\->removeInternalSubset();
.Ve
.Sp
\&\fI\s-1EXPERIMENTAL\s0!\fR
.Sp
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.
.IP "getElementsByTagName" 4
.IX Item "getElementsByTagName"
.Vb 1
\&  my @nodelist = $doc\->getElementsByTagName($tagname);
.Ve
.Sp
Implements the \s-1DOM\s0 Level 2 function
.Sp
In \s-1SCALAR\s0 context this function returns an XML::LibXML::NodeList object.
.IP "getElementsByTagNameNS" 4
.IX Item "getElementsByTagNameNS"
.Vb 1
\&  my @nodelist = $doc\->getElementsByTagNameNS($nsURI,$tagname);
.Ve
.Sp
Implements the \s-1DOM\s0 Level 2 function
.Sp
In \s-1SCALAR\s0 context this function returns an XML::LibXML::NodeList object.
.IP "getElementsByLocalName" 4
.IX Item "getElementsByLocalName"
.Vb 1
\&  my @nodelist = $doc\->getElementsByLocalName($localname);
.Ve
.Sp
This allows the fetching of all nodes from a given document with the given
Localname.
.Sp
In \s-1SCALAR\s0 context this function returns an XML::LibXML::NodeList object.
.IP "getElementById" 4
.IX Item "getElementById"
.Vb 1
\&  my $node = $doc\->getElementById($id);
.Ve
.Sp
Returns the element that has an \s-1ID\s0 attribute with the given value. If no such
element exists, this returns undef.
.Sp
Note: the \s-1ID\s0 of an element may change while manipulating the document. For
documents with a \s-1DTD,\s0 the information about \s-1ID\s0 attributes is only available if
\&\s-1DTD\s0 loading/validation has been requested. For \s-1HTML\s0 documents parsed with the
\&\s-1HTML\s0 parser \s-1ID\s0 detection is done automatically. In \s-1XML\s0 documents, all \*(L"xml:id\*(R"
attributes are considered to be of type \s-1ID.\s0 You can test ID-ness of an
attribute node with \f(CW$attr\fR\->\fIisId()\fR.
.Sp
In versions 1.59 and earlier this method was called \fIgetElementsById()\fR (plural)
by mistake. Starting from 1.60 this name is maintained as an alias only for
backward compatibility.
.IP "indexElements" 4
.IX Item "indexElements"
.Vb 1
\&  $dom\->indexElements();
.Ve
.Sp
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 \s-1DOM\s0 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 \s-1DOM\s0 specification.
.Sp
This function returns number of elements indexed, \-1 if error occurred, or \-2
if this feature is not available in the running libxml2.
.SH "AUTHORS"
.IX Header "AUTHORS"
Matt Sergeant,
Christian Glahn,
Petr Pajas
.SH "VERSION"
.IX Header "VERSION"
2.0128
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
2001\-2007, AxKit.com Ltd.
.PP
2002\-2006, Christian Glahn.
.PP
2006\-2009, Petr Pajas.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.