local-lib5/man/man3/XML::LibXML::DOM.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::DOM 3"
 127 .TH XML::LibXML::DOM 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::DOM \- XML::LibXML DOM Implementation
 134 .SH "DESCRIPTION"
 135 .IX Header "DESCRIPTION"
 136 XML::LibXML provides an light-wight interface to \fImodify\fR a node of the document tree generated by the XML::LibXML parser. This interface
 137 follows as far as possible the \s-1DOM\s0 Level 3 specification. Additionally to the
 138 specified functions the XML::LibXML supports some functions that are more handy
 139 to use in the perl environment.
 140 .PP
 141 One also has to remember, that XML::LibXML is an interface to libxml2 nodes
 142 which actually reside on the C\-Level of XML::LibXML. This means each node is a
 143 reference to a structure different than a perl hash or array. The only way to
 144 access these structure's values is through the \s-1DOM\s0 interface provided by
 145 XML::LibXML. This also means, that one \fIcan't\fR simply inherit a XML::LibXML node and add new member variables as they were
 146 hash keys.
 147 .PP
 148 The \s-1DOM\s0 interface of XML::LibXML does not intend to implement a full \s-1DOM\s0
 149 interface as it is done by \s-1XML::GDOME\s0 and used for full featured application.
 150 Moreover, it offers an simple way to build or modify documents that are created
 151 by XML::LibXML's parser.
 152 .PP
 153 Another target of the XML::LibXML interface is to make the interfaces of
 154 libxml2 available to the perl community. This includes also some workarounds to
 155 some features where libxml2 assumes more control over the C\-Level that most
 156 perl users don't have.
 157 .PP
 158 One of the most important parts of the XML::LibXML \s-1DOM\s0 interface is, that the
 159 interfaces try do 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
 160 specification says and not what widespread Java interfaces claim to be
 161 standard. Although there are several functions that have only a singular
 162 interface that conforms to the \s-1DOM\s0 spec XML::LibXML provides an additional Java
 163 style alias interface.
 164 .PP
 165 Also there are some function interfaces left over from early stages of
 166 XML::LibXML for compatibility reasons. These interfaces are for compatibility
 167 reasons \fIonly\fR. They might disappear in one of the future versions of XML::LibXML, so a user
 168 is requested to switch over to the official functions.
 169 .SS "Encodings and XML::LibXML's \s-1DOM\s0 implementation"
 170 .IX Subsection "Encodings and XML::LibXML's DOM implementation"
 171 See the section on Encodings in the \fIXML::LibXML\fR manual page.
 172 .SS "Namespaces and XML::LibXML's \s-1DOM\s0 implementation"
 173 .IX Subsection "Namespaces and XML::LibXML's DOM implementation"
 174 XML::LibXML's \s-1DOM\s0 implementation is limited by the \s-1DOM\s0 implementation of
 175 libxml2 which treats namespaces slightly differently than required by the \s-1DOM\s0
 176 Level 2 specification.
 177 .PP
 178 According to the \s-1DOM\s0 Level 2 specification, namespaces of elements and
 179 attributes should be persistent, and nodes should be permanently bound to
 180 namespace URIs as they get created; it should be possible to manipulate the
 181 special attributes used for declaring \s-1XML\s0 namespaces just as other attributes
 182 without affecting the namespaces of other nodes. In \s-1DOM\s0 Level 2, the
 183 application is responsible for creating the special attributes consistently
 184 and/or for correct serialization of the document.
 185 .PP
 186 This is both inconvenient, causes problems in serialization of \s-1DOM\s0 to \s-1XML\s0, and
 187 most importantly, seems almost impossible to implement over libxml2.
 188 .PP
 189 In libxml2, namespace \s-1URI\s0 and prefix of a node is provided by a pointer to a
 190 namespace declaration (appearing as a special xmlns attribute in the \s-1XML\s0
 191 document). If the prefix or namespace \s-1URI\s0 of the declaration changes, the
 192 prefix and namespace \s-1URI\s0 of all nodes that point to it changes as well.
 193 Moreover, in contrast to \s-1DOM\s0, a node (element or attribute) can only be bound
 194 to a namespace \s-1URI\s0 if there is some namespace declaration in the document to
 195 point to.
 196 .PP
 197 Therefore current \s-1DOM\s0 implementation in XML::LibXML tries to treat namespace
 198 declarations in a compromise between reason, common sense, limitations of
 199 libxml2, and the \s-1DOM\s0 Level 2 specification.
 200 .PP
 201 In XML::LibXML, special attributes declaring \s-1XML\s0 namespaces are often created
 202 automatically, usually when a namespaced node is attached to a document and no
 203 existing declaration of the namespace and prefix is in the scope to be reused.
 204 In this respect, XML::LibXML \s-1DOM\s0 implementation differs from the \s-1DOM\s0 Level 2
 205 specification according to which special attributes for declaring the
 206 apropriate \s-1XML\s0 namespaces should not be added when a node with a namespace
 207 prefix and namespace \s-1URI\s0 is created.
 208 .PP
 209 Namespace declarations are also created when XML::LibXML::Document's \fIcreateElementNS()\fR or \fIcreateAttributeNS()\fR function are used. If the a
 210 namespace is not declared on the documentElement, the namespace will be locally
 211 declared for the newly created node. In case of Attributes this may look a bit
 212 confusing, since these nodes cannot have namespace declarations itself. In this
 213 case the namespace is internally applied to the attribute and later declared on
 214 the node the attribute is appended to (if required).
 215 .PP
 216 The following example may explain this a bit:
 217 .PP
 218 .Vb 3
 219 \&  my $doc = XML::LibXML\->createDocument;
 220 \&  my $root = $doc\->createElementNS( "", "foo" );
 221 \&  $doc\->setDocumentElement( $root );
 222 \&
 223 \&  my $attr = $doc\->createAttributeNS( "bar", "bar:foo", "test" );
 224 \&  $root\->setAttributeNodeNS( $attr );
 225 .Ve
 226 .PP
 227 This piece of code will result in the following document:
 228 .PP
 229 .Vb 2
 230 \&  <?xml version="1.0"?>
 231 \&  <foo xmlns:bar="bar" bar:foo="test"/>
 232 .Ve
 233 .PP
 234 The namespace is declared on the document element during the
 235 \&\fIsetAttributeNodeNS()\fR call.
 236 .PP
 237 Namespaces can be also declared explicitly by the use of XML::LibXML:Element's
 238 \&\fIsetNamespace()\fR function. Since 1.61, they can also be manipulated with
 239 functions \fIsetNamespaceDeclPrefix()\fR and \fIsetNamespaceDeclURI()\fR (not available in
 240 \&\s-1DOM\s0). Changing an \s-1URI\s0 or prefix of an existing namespace declaration affects
 241 the namespace \s-1URI\s0 and prefix of all nodes which point to it (that is the nodes
 242 in its scope).
 243 .PP
 244 It is also important to repeat the specification: While working with namespaces
 245 you should use the namespace aware functions instead of the simplified
 246 versions. For example you should \fInever\fR use \fIsetAttribute()\fR but \fIsetAttributeNS()\fR.
 247 .SH "AUTHORS"
 248 .IX Header "AUTHORS"
 249 Matt Sergeant,
 250 Christian Glahn,
 251 Petr Pajas
 252 .SH "VERSION"
 253 .IX Header "VERSION"
 254 1.70
 255 .SH "COPYRIGHT"
 256 .IX Header "COPYRIGHT"
 257 2001\-2007, AxKit.com Ltd.
 258 .PP
 259 2002\-2006, Christian Glahn.
 260 .PP
 261 2006\-2009, Petr Pajas.