.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "XML::LibXML::DOM 3pm"
.TH XML::LibXML::DOM 3pm "2022-10-19" "perl v5.36.0" "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::DOM \- XML::LibXML DOM Implementation
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
XML::LibXML provides a lightweight interface to \fImodify\fR a node of the document tree generated by the XML::LibXML parser. This interface
follows as far as possible the \s-1DOM\s0 Level 3 specification. In addition to the
specified functions, XML::LibXML supports some functions that are more handy to
use in the perl environment.
.PP
One also has to remember, that XML::LibXML is an interface to libxml2 nodes
which actually reside on the C\-Level of XML::LibXML. This means each node is a
reference to a structure which is different from a perl hash or array. The only
way to access these structures' values is through the \s-1DOM\s0 interface provided by
XML::LibXML. This also means, that one \fIcan't\fR simply inherit an XML::LibXML node and add new member variables as if they were
hash keys.
.PP
The \s-1DOM\s0 interface of XML::LibXML does not intend to implement a full \s-1DOM\s0
interface as it is done by \s-1XML::GDOME\s0 and used for full featured application.
Moreover, it offers an simple way to build or modify documents that are created
by XML::LibXML's parser.
.PP
Another target of the XML::LibXML interface is to make the interfaces of
libxml2 available to the perl community. This includes also some workarounds to
some features where libxml2 assumes more control over the C\-Level that most
perl users don't have.
.PP
One of the most important parts of the XML::LibXML \s-1DOM\s0 interface is that the
interfaces try to follow the \s-1DOM\s0 Level 3 specification (<http://www.w3.org/TR/DOM\-Level\-3\-Core/>) rather strictly. This means the interface functions are named as the \s-1DOM\s0
specification says and not what widespread Java interfaces claim to be the
standard. Although there are several functions that have only a singular
interface that conforms to the \s-1DOM\s0 spec XML::LibXML provides an additional Java
style alias interface.
.PP
Moreover, there are some function interfaces left over from early stages of
XML::LibXML for compatibility reasons. These interfaces are for compatibility
reasons \fIonly\fR. They might disappear in one of the future versions of XML::LibXML, so a user
is requested to switch over to the official functions.
.SS "Encodings and XML::LibXML's \s-1DOM\s0 implementation"
.IX Subsection "Encodings and XML::LibXML's DOM implementation"
See the section on Encodings in the \fIXML::LibXML\fR manual page.
.SS "Namespaces and XML::LibXML's \s-1DOM\s0 implementation"
.IX Subsection "Namespaces and XML::LibXML's DOM implementation"
XML::LibXML's \s-1DOM\s0 implementation is limited by the \s-1DOM\s0 implementation of
libxml2 which treats namespaces slightly differently than required by the \s-1DOM\s0
Level 2 specification.
.PP
According to the \s-1DOM\s0 Level 2 specification, namespaces of elements and
attributes should be persistent, and nodes should be permanently bound to
namespace URIs as they get created; it should be possible to manipulate the
special attributes used for declaring \s-1XML\s0 namespaces just as other attributes
without affecting the namespaces of other nodes. In \s-1DOM\s0 Level 2, the
application is responsible for creating the special attributes consistently
and/or for correct serialization of the document.
.PP
This is both inconvenient, causes problems in serialization of \s-1DOM\s0 to \s-1XML,\s0 and
most importantly, seems almost impossible to implement over libxml2.
.PP
In libxml2, namespace \s-1URI\s0 and prefix of a node is provided by a pointer to a
namespace declaration (appearing as a special xmlns attribute in the \s-1XML\s0
document). If the prefix or namespace \s-1URI\s0 of the declaration changes, the
prefix and namespace \s-1URI\s0 of all nodes that point to it changes as well.
Moreover, in contrast to \s-1DOM,\s0 a node (element or attribute) can only be bound
to a namespace \s-1URI\s0 if there is some namespace declaration in the document to
point to.
.PP
Therefore current \s-1DOM\s0 implementation in XML::LibXML tries to treat namespace
declarations in a compromise between reason, common sense, limitations of
libxml2, and the \s-1DOM\s0 Level 2 specification.
.PP
In XML::LibXML, special attributes declaring \s-1XML\s0 namespaces are often created
automatically, usually when a namespaced node is attached to a document and no
existing declaration of the namespace and prefix is in the scope to be reused.
In this respect, XML::LibXML \s-1DOM\s0 implementation differs from the \s-1DOM\s0 Level 2
specification according to which special attributes for declaring the
appropriate \s-1XML\s0 namespaces should not be added when a node with a namespace
prefix and namespace \s-1URI\s0 is created.
.PP
Namespace declarations are also created when XML::LibXML::Document's \fBcreateElementNS()\fR or \fBcreateAttributeNS()\fR function are used. If the a
namespace is not declared on the documentElement, the namespace will be locally
declared for the newly created node. In case of Attributes this may look a bit
confusing, since these nodes cannot have namespace declarations itself. In this
case the namespace is internally applied to the attribute and later declared on
the node the attribute is appended to (if required).
.PP
The following example may explain this a bit:
.PP
.Vb 3
\&  my $doc = XML::LibXML\->createDocument;
\&  my $root = $doc\->createElementNS( "", "foo" );
\&  $doc\->setDocumentElement( $root );
\&
\&  my $attr = $doc\->createAttributeNS( "bar", "bar:foo", "test" );
\&  $root\->setAttributeNodeNS( $attr );
.Ve
.PP
This piece of code will result in the following document:
.PP
.Vb 2
\&  <?xml version="1.0"?>
\&  <foo xmlns:bar="bar" bar:foo="test"/>
.Ve
.PP
The namespace is declared on the document element during the
\&\fBsetAttributeNodeNS()\fR call.
.PP
Namespaces can be also declared explicitly by the use of XML::LibXML::Element's
\&\fBsetNamespace()\fR function. Since 1.61, they can also be manipulated with
functions \fBsetNamespaceDeclPrefix()\fR and \fBsetNamespaceDeclURI()\fR (not available in
\&\s-1DOM\s0). Changing an \s-1URI\s0 or prefix of an existing namespace declaration affects
the namespace \s-1URI\s0 and prefix of all nodes which point to it (that is the nodes
in its scope).
.PP
It is also important to repeat the specification: While working with namespaces
you should use the namespace aware functions instead of the simplified
versions. For example you should \fInever\fR use \fBsetAttribute()\fR but \fBsetAttributeNS()\fR.
.SH "AUTHORS"
.IX Header "AUTHORS"
Matt Sergeant,
Christian Glahn,
Petr Pajas
.SH "VERSION"
.IX Header "VERSION"
2.0134
.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.