local-lib5/man/man3/XML::LibXML::Element.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::Element 3"
 127 .TH XML::LibXML::Element 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::Element \- XML::LibXML Class for Element Nodes
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 3
 137 \&  use XML::LibXML;
 138 \&  # Only methods specific to Element nodes are listed here,
 139 \&  # see XML::LibXML::Node manpage for other methods
 140 \&
 141 \&  $node = XML::LibXML::Element\->new( $name );
 142 \&  $node\->setAttribute( $aname, $avalue );
 143 \&  $node\->setAttributeNS( $nsURI, $aname, $avalue );
 144 \&  $avalue = $node\->getAttribute( $aname );
 145 \&  $avalue = $node\->setAttributeNS( $nsURI, $aname );
 146 \&  $attrnode = $node\->getAttributeNode( $aname );
 147 \&  $attrnode = $node\->getAttributeNodeNS( $namespaceURI, $aname );
 148 \&  $node\->removeAttribute( $aname );
 149 \&  $node\->removeAttributeNS( $nsURI, $aname );
 150 \&  $boolean = $node\->hasAttribute( $aname );
 151 \&  $boolean = $node\->hasAttributeNS( $nsURI, $aname );
 152 \&  @nodes = $node\->getChildrenByTagName($tagname);
 153 \&  @nodes = $node\->getChildrenByTagNameNS($nsURI,$tagname);
 154 \&  @nodes = $node\->getChildrenByLocalName($localname);
 155 \&  @nodes = $node\->getElementsByTagName($tagname);
 156 \&  @nodes = $node\->getElementsByTagNameNS($nsURI,$localname);
 157 \&  @nodes = $node\->getElementsByLocalName($localname);
 158 \&  $node\->appendWellBalancedChunk( $chunk );
 159 \&  $node\->appendText( $PCDATA );
 160 \&  $node\->appendTextNode( $PCDATA );
 161 \&  $node\->appendTextChild( $childname , $PCDATA );
 162 \&  $node\->setNamespace( $nsURI , $nsPrefix, $activate );
 163 \&  $node\->setNamespaceDeclURI( $nsPrefix, $newURI );
 164 \&  $node\->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
 165 .Ve
 166 .SH "METHODS"
 167 .IX Header "METHODS"
 168 The class inherits from XML::LibXML::Node. The documentation for Inherited methods is not listed here.
 169 .PP
 170 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.
 171 .IP "new" 4
 172 .IX Item "new"
 173 .Vb 1
 174 \&  $node = XML::LibXML::Element\->new( $name );
 175 .Ve
 176 .Sp
 177 This function creates a new node unbound to any \s-1DOM\s0.
 178 .IP "setAttribute" 4
 179 .IX Item "setAttribute"
 180 .Vb 1
 181 \&  $node\->setAttribute( $aname, $avalue );
 182 .Ve
 183 .Sp
 184 This method sets or replaces the node's attribute \f(CW$aname\fR to the value \f(CW$avalue\fR
 185 .IP "setAttributeNS" 4
 186 .IX Item "setAttributeNS"
 187 .Vb 1
 188 \&  $node\->setAttributeNS( $nsURI, $aname, $avalue );
 189 .Ve
 190 .Sp
 191 Namespace-aware version of \f(CW\*(C`setAttribute\*(C'\fR, where \f(CW$nsURI\fR is a namespace \s-1URI\s0, \f(CW$aname\fR is a qualified name, and \f(CW$avalue\fR is the value. The namespace \s-1URI\s0 may be null (empty or undefined) in order to
 192 create an attribute which has no namespace.
 193 .Sp
 194 The current implementation differs from \s-1DOM\s0 in the following aspects
 195 .Sp
 196 If an attribute with the same local name and namespace \s-1URI\s0 already exists on
 197 the element, but its prefix differs from the prefix of \f(CW$aname\fR, then this function is supposed to change the prefix (regardless of namespace
 198 declarations and possible collisions). However, the current implementation does
 199 rather the opposite. If a prefix is declared for the namespace \s-1URI\s0 in the scope
 200 of the attribute, then the already declared prefix is used, disregarding the
 201 prefix specified in \f(CW$aname\fR. If no prefix is declared for the namespace, the function tries to declare the
 202 prefix specified in \f(CW$aname\fR and dies if the prefix is already taken by some other namespace.
 203 .Sp
 204 According to \s-1DOM\s0 Level 2 specification, this method can also be used to create
 205 or modify special attributes used for declaring \s-1XML\s0 namespaces (which belong to
 206 the namespace \*(L"http://www.w3.org/2000/xmlns/\*(R" and have prefix or name \*(L"xmlns\*(R").
 207 This should work since version 1.61, but again the implementation differs from
 208 \&\s-1DOM\s0 specification in the following: if a declaration of the same namespace
 209 prefix already exists on the element, then changing its value via this method
 210 automatically changes the namespace of all elements and attributes in its
 211 scope. This is because in libxml2 the namespace \s-1URI\s0 of an element is not static
 212 but is computed from a pointer to a namespace declaration attribute.
 213 .IP "getAttribute" 4
 214 .IX Item "getAttribute"
 215 .Vb 1
 216 \&  $avalue = $node\->getAttribute( $aname );
 217 .Ve
 218 .Sp
 219 If \f(CW$node\fR has an attribute with the name \f(CW$aname\fR, the value of this attribute will get returned.
 220 .IP "getAttributeNS" 4
 221 .IX Item "getAttributeNS"
 222 .Vb 1
 223 \&  $avalue = $node\->setAttributeNS( $nsURI, $aname );
 224 .Ve
 225 .Sp
 226 Retrieves an attribute value by local name and namespace \s-1URI\s0.
 227 .IP "getAttributeNode" 4
 228 .IX Item "getAttributeNode"
 229 .Vb 1
 230 \&  $attrnode = $node\->getAttributeNode( $aname );
 231 .Ve
 232 .Sp
 233 Retrieve an attribute node by name. If no attribute with a given name exists, \f(CW\*(C`undef\*(C'\fR is returned.
 234 .IP "getAttributeNodeNS" 4
 235 .IX Item "getAttributeNodeNS"
 236 .Vb 1
 237 \&  $attrnode = $node\->getAttributeNodeNS( $namespaceURI, $aname );
 238 .Ve
 239 .Sp
 240 Retrieves an attribute node by local name and namespace \s-1URI\s0. If no attribute
 241 with a given localname and namespace exists, \f(CW\*(C`undef\*(C'\fR is returned.
 242 .IP "removeAttribute" 4
 243 .IX Item "removeAttribute"
 244 .Vb 1
 245 \&  $node\->removeAttribute( $aname );
 246 .Ve
 247 .Sp
 248 The method removes the attribute \f(CW$aname\fR from the node's attribute list, if the attribute can be found.
 249 .IP "removeAttributeNS" 4
 250 .IX Item "removeAttributeNS"
 251 .Vb 1
 252 \&  $node\->removeAttributeNS( $nsURI, $aname );
 253 .Ve
 254 .Sp
 255 Namespace version of \f(CW\*(C`removeAttribute\*(C'\fR
 256 .IP "hasAttribute" 4
 257 .IX Item "hasAttribute"
 258 .Vb 1
 259 \&  $boolean = $node\->hasAttribute( $aname );
 260 .Ve
 261 .Sp
 262 This function tests if the named attribute is set for the node. If the
 263 attribute is specified, \s-1TRUE\s0 (1) will be returned, otherwise the return value
 264 is \s-1FALSE\s0 (0).
 265 .IP "hasAttributeNS" 4
 266 .IX Item "hasAttributeNS"
 267 .Vb 1
 268 \&  $boolean = $node\->hasAttributeNS( $nsURI, $aname );
 269 .Ve
 270 .Sp
 271 namespace version of \f(CW\*(C`hasAttribute\*(C'\fR
 272 .IP "getChildrenByTagName" 4
 273 .IX Item "getChildrenByTagName"
 274 .Vb 1
 275 \&  @nodes = $node\->getChildrenByTagName($tagname);
 276 .Ve
 277 .Sp
 278 The function gives direct access to all child elements of the current node with
 279 a given tagname, where tagname is a qualified name, that is, in case of
 280 namespace usage it may consist of a prefix and local name. This function makes
 281 things a lot easier if one needs to handle big data sets. A special tagname '*'
 282 can be used to match any name.
 283 .Sp
 284 If this function is called in \s-1SCALAR\s0 context, it returns the number of elements
 285 found.
 286 .IP "getChildrenByTagNameNS" 4
 287 .IX Item "getChildrenByTagNameNS"
 288 .Vb 1
 289 \&  @nodes = $node\->getChildrenByTagNameNS($nsURI,$tagname);
 290 .Ve
 291 .Sp
 292 Namespace version of \f(CW\*(C`getChildrenByTagName\*(C'\fR. A special nsURI '*' matches any namespace \s-1URI\s0, in which case the function
 293 behaves just like \f(CW\*(C`getChildrenByLocalName\*(C'\fR.
 294 .Sp
 295 If this function is called in \s-1SCALAR\s0 context, it returns the number of elements
 296 found.
 297 .IP "getChildrenByLocalName" 4
 298 .IX Item "getChildrenByLocalName"
 299 .Vb 1
 300 \&  @nodes = $node\->getChildrenByLocalName($localname);
 301 .Ve
 302 .Sp
 303 The function gives direct access to all child elements of the current node with
 304 a given local name. It makes things a lot easier if one needs to handle big
 305 data sets. A special \f(CW\*(C`localname\*(C'\fR '*' can be used to match any local name.
 306 .Sp
 307 If this function is called in \s-1SCALAR\s0 context, it returns the number of elements
 308 found.
 309 .IP "getElementsByTagName" 4
 310 .IX Item "getElementsByTagName"
 311 .Vb 1
 312 \&  @nodes = $node\->getElementsByTagName($tagname);
 313 .Ve
 314 .Sp
 315 This function is part of the spec. It fetches all descendants of a node with a
 316 given tagname, where \f(CW\*(C`tagname\*(C'\fR is a qualified name, that is, in case of namespace usage it may consist of a
 317 prefix and local name. A special \f(CW\*(C`tagname\*(C'\fR '*' can be used to match any tag name.
 318 .Sp
 319 In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
 320 .IP "getElementsByTagNameNS" 4
 321 .IX Item "getElementsByTagNameNS"
 322 .Vb 1
 323 \&  @nodes = $node\->getElementsByTagNameNS($nsURI,$localname);
 324 .Ve
 325 .Sp
 326 Namespace version of \f(CW\*(C`getElementsByTagName\*(C'\fR as found in the \s-1DOM\s0 spec. A special \f(CW\*(C`localname\*(C'\fR '*' can be used to match any local name and \f(CW\*(C`nsURI\*(C'\fR '*' can be used to match any namespace \s-1URI\s0.
 327 .Sp
 328 In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
 329 .IP "getElementsByLocalName" 4
 330 .IX Item "getElementsByLocalName"
 331 .Vb 1
 332 \&  @nodes = $node\->getElementsByLocalName($localname);
 333 .Ve
 334 .Sp
 335 This function is not found in the \s-1DOM\s0 specification. It is a mix of
 336 getElementsByTagName and getElementsByTagNameNS. It will fetch all tags
 337 matching the given local-name. This allows one to select tags with the same
 338 local name across namespace borders.
 339 .Sp
 340 In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
 341 .IP "appendWellBalancedChunk" 4
 342 .IX Item "appendWellBalancedChunk"
 343 .Vb 1
 344 \&  $node\->appendWellBalancedChunk( $chunk );
 345 .Ve
 346 .Sp
 347 Sometimes it is necessary to append a string coded \s-1XML\s0 Tree to a node. \fIappendWellBalancedChunk\fR will do the trick for you. But this is only done if the String is \f(CW\*(C`well\-balanced\*(C'\fR.
 348 .Sp
 349 \&\fINote that \fIappendWellBalancedChunk()\fI is only left for compatibility reasons\fR. Implicitly it uses
 350 .Sp
 351 .Vb 2
 352 \&  my $fragment = $parser\->parse_xml_chunk( $chunk );
 353 \&   $node\->appendChild( $fragment );
 354 .Ve
 355 .Sp
 356 This form is more explicit and makes it easier to control the flow of a script.
 357 .IP "appendText" 4
 358 .IX Item "appendText"
 359 .Vb 1
 360 \&  $node\->appendText( $PCDATA );
 361 .Ve
 362 .Sp
 363 alias for \fIappendTextNode()\fR.
 364 .IP "appendTextNode" 4
 365 .IX Item "appendTextNode"
 366 .Vb 1
 367 \&  $node\->appendTextNode( $PCDATA );
 368 .Ve
 369 .Sp
 370 This wrapper function lets you add a string directly to an element node.
 371 .IP "appendTextChild" 4
 372 .IX Item "appendTextChild"
 373 .Vb 1
 374 \&  $node\->appendTextChild( $childname , $PCDATA );
 375 .Ve
 376 .Sp
 377 Somewhat similar with \f(CW\*(C`appendTextNode\*(C'\fR: It lets you set an Element, that contains only a \f(CW\*(C`text node\*(C'\fR directly by specifying the name and the text content.
 378 .IP "setNamespace" 4
 379 .IX Item "setNamespace"
 380 .Vb 1
 381 \&  $node\->setNamespace( $nsURI , $nsPrefix, $activate );
 382 .Ve
 383 .Sp
 384 \&\fIsetNamespace()\fR allows one to apply a namespace to an element. The function
 385 takes three parameters: 1. the namespace \s-1URI\s0, which is required and the two
 386 optional values prefix, which is the namespace prefix, as it should be used in
 387 child elements or attributes as well as the additional activate parameter. If
 388 prefix is not given, undefined or empty, this function tries to create a
 389 declaration of the default namespace.
 390 .Sp
 391 The activate parameter is most useful: If this parameter is set to \s-1FALSE\s0 (0), a
 392 new namespace declaration is simply added to the element while the element's
 393 namespace itself is not altered. Nevertheless, activate is set to \s-1TRUE\s0 (1) on
 394 default. In this case the namespace is used as the node's effective namespace.
 395 This means the namespace prefix is added to the node name and if there was a
 396 namespace already active for the node, it will be replaced (but its declaration
 397 is not removed from the document). A new namespace declaration is only created
 398 if necessary (that is, if the element is already in the scope of a namespace
 399 declaration associating the prefix with the namespace \s-1URI\s0, then this
 400 declaration is reused).
 401 .Sp
 402 The following example may clarify this:
 403 .Sp
 404 .Vb 2
 405 \&  my $e1 = $doc\->createElement("bar");
 406 \&   $e1\->setNamespace("http://foobar.org", "foo")
 407 .Ve
 408 .Sp
 409 results
 410 .Sp
 411 .Vb 1
 412 \&  <foo:bar xmlns:foo="http://foobar.org"/>
 413 .Ve
 414 .Sp
 415 while
 416 .Sp
 417 .Vb 2
 418 \&  my $e2 = $doc\->createElement("bar");
 419 \&   $e2\->setNamespace("http://foobar.org", "foo",0)
 420 .Ve
 421 .Sp
 422 results only
 423 .Sp
 424 .Vb 1
 425 \&  <bar xmlns:foo="http://foobar.org"/>
 426 .Ve
 427 .Sp
 428 By using \f(CW$activate\fR == 0 it is possible to create multiple namespace
 429 declarations on a single element.
 430 .Sp
 431 The function fails if it is required to create a declaration associating the
 432 prefix with the namespace \s-1URI\s0 but the element already carries a declaration
 433 with the same prefix but different namespace \s-1URI\s0.
 434 .IP "setNamespaceDeclURI" 4
 435 .IX Item "setNamespaceDeclURI"
 436 .Vb 1
 437 \&  $node\->setNamespaceDeclURI( $nsPrefix, $newURI );
 438 .Ve
 439 .Sp
 440 \&\s-1EXPERIMENTAL\s0 \s-1IN\s0 1.61 !
 441 .Sp
 442 This function manipulates directly with an existing namespace declaration on an
 443 element. It takes two parameters: the prefix by which it looks up the namespace
 444 declaration and a new namespace \s-1URI\s0 which replaces its previous value.
 445 .Sp
 446 It returns 1 if the namespace declaration was found and changed, 0 otherwise.
 447 .Sp
 448 All elements and attributes (even those previously unbound from the document)
 449 for which the namespace declaration determines their namespace belong to the
 450 new namespace after the change.
 451 .Sp
 452 If the new \s-1URI\s0 is undef or empty, the nodes have no namespace and no prefix
 453 after the change. Namespace declarations once nulled in this way do not further
 454 appear in the serialized output (but do remain in the document for internal
 455 integrity of libxml2 data structures).
 456 .Sp
 457 This function is \s-1NOT\s0 part of any \s-1DOM\s0 \s-1API\s0.
 458 .IP "setNamespaceDeclPrefix" 4
 459 .IX Item "setNamespaceDeclPrefix"
 460 .Vb 1
 461 \&  $node\->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
 462 .Ve
 463 .Sp
 464 \&\s-1EXPERIMENTAL\s0 \s-1IN\s0 1.61 !
 465 .Sp
 466 This function manipulates directly with an existing namespace declaration on an
 467 element. It takes two parameters: the old prefix by which it looks up the
 468 namespace declaration and a new prefix which is to replace the old one.
 469 .Sp
 470 The function dies with an error if the element is in the scope of another
 471 declaration whose prefix equals to the new prefix, or if the change should
 472 result in a declaration with a non-empty prefix but empty namespace \s-1URI\s0.
 473 Otherwise, it returns 1 if the namespace declaration was found and changed and
 474 0 if not found.
 475 .Sp
 476 All elements and attributes (even those previously unbound from the document)
 477 for which the namespace declaration determines their namespace change their
 478 prefix to the new value.
 479 .Sp
 480 If the new prefix is undef or empty, the namespace declaration becomes a
 481 declaration of a default namespace. The corresponding nodes drop their
 482 namespace prefix (but remain in the, now default, namespace). In this case the
 483 function fails, if the containing element is in the scope of another default
 484 namespace declaration.
 485 .Sp
 486 This function is \s-1NOT\s0 part of any \s-1DOM\s0 \s-1API\s0.
 487 .SH "AUTHORS"
 488 .IX Header "AUTHORS"
 489 Matt Sergeant,
 490 Christian Glahn,
 491 Petr Pajas
 492 .SH "VERSION"
 493 .IX Header "VERSION"
 494 1.70
 495 .SH "COPYRIGHT"
 496 .IX Header "COPYRIGHT"
 497 2001\-2007, AxKit.com Ltd.
 498 .PP
 499 2002\-2006, Christian Glahn.
 500 .PP
 501 2006\-2009, Petr Pajas.