1XML::LibXML::Element(3)User Contributed Perl DocumentatioXnML::LibXML::Element(3)
2
6 XML::LibXML::Element - XML::LibXML Class for Element Nodes
7
9 use XML::LibXML;
10 # Only methods specific to Element nodes are listed here,
11 # see the XML::LibXML::Node manpage for other methods
12 $node = XML::LibXML::Element->new( $name );
14 $node->setAttribute( $aname, $avalue );
15 $node->setAttributeNS( $nsURI, $aname, $avalue );
16 $avalue = $node->getAttribute( $aname );
17 $avalue = $node->getAttributeNS( $nsURI, $aname );
18 $attrnode = $node->getAttributeNode( $aname );
19 $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
20 $node->removeAttribute( $aname );
21 $node->removeAttributeNS( $nsURI, $aname );
22 $boolean = $node->hasAttribute( $aname );
23 $boolean = $node->hasAttributeNS( $nsURI, $aname );
24 @nodes = $node->getChildrenByTagName($tagname);
25 @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
26 @nodes = $node->getChildrenByLocalName($localname);
27 @nodes = $node->getElementsByTagName($tagname);
28 @nodes = $node->getElementsByTagNameNS($nsURI,$localname);
29 @nodes = $node->getElementsByLocalName($localname);
30 $node->appendWellBalancedChunk( $chunk );
31 $node->appendText( $PCDATA );
32 $node->appendTextNode( $PCDATA );
33 $node->appendTextChild( $childname , $PCDATA );
34 $node->setNamespace( $nsURI , $nsPrefix, $activate );
35 $node->setNamespaceDeclURI( $nsPrefix, $newURI );
36 $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
37
39 The class inherits from XML::LibXML::Node. The documentation for
40 Inherited methods is not listed here.
41 Many functions listed here are extensively documented in the DOM Level
43 3 specification (<http://www.w3.org/TR/DOM-Level-3-Core/>). Please
44 refer to the specification for extensive documentation.
45 new
47 $node = XML::LibXML::Element->new( $name );
48 This function creates a new node unbound to any DOM.
50 setAttribute
52 $node->setAttribute( $aname, $avalue );
53 This method sets or replaces the node's attribute $aname to the
55 value $avalue
56 setAttributeNS
58 $node->setAttributeNS( $nsURI, $aname, $avalue );
59 Namespace-aware version of "setAttribute", where $nsURI is a
61 namespace URI, $aname is a qualified name, and $avalue is the
62 value. The namespace URI may be null (empty or undefined) in order
63 to create an attribute which has no namespace.
64 The current implementation differs from DOM in the following
66 aspects
67 If an attribute with the same local name and namespace URI already
69 exists on the element, but its prefix differs from the prefix of
70 $aname, then this function is supposed to change the prefix
71 (regardless of namespace declarations and possible collisions).
72 However, the current implementation does rather the opposite. If a
73 prefix is declared for the namespace URI in the scope of the
74 attribute, then the already declared prefix is used, disregarding
75 the prefix specified in $aname. If no prefix is declared for the
76 namespace, the function tries to declare the prefix specified in
77 $aname and dies if the prefix is already taken by some other
78 namespace.
79 According to DOM Level 2 specification, this method can also be
81 used to create or modify special attributes used for declaring XML
82 namespaces (which belong to the namespace
83 "http://www.w3.org/2000/xmlns/" and have prefix or name "xmlns").
84 This should work since version 1.61, but again the implementation
85 differs from DOM specification in the following: if a declaration
86 of the same namespace prefix already exists on the element, then
87 changing its value via this method automatically changes the
88 namespace of all elements and attributes in its scope. This is
89 because in libxml2 the namespace URI of an element is not static
90 but is computed from a pointer to a namespace declaration
91 attribute.
92 getAttribute
94 $avalue = $node->getAttribute( $aname );
95 If $node has an attribute with the name $aname, the value of this
97 attribute will get returned.
98 getAttributeNS
100 $avalue = $node->getAttributeNS( $nsURI, $aname );
101 Retrieves an attribute value by local name and namespace URI.
103 getAttributeNode
105 $attrnode = $node->getAttributeNode( $aname );
106 Retrieve an attribute node by name. If no attribute with a given
108 name exists, "undef" is returned.
109 getAttributeNodeNS
111 $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
112 Retrieves an attribute node by local name and namespace URI. If no
114 attribute with a given localname and namespace exists, "undef" is
115 returned.
116 removeAttribute
118 $node->removeAttribute( $aname );
119 The method removes the attribute $aname from the node's attribute
121 list, if the attribute can be found.
122 removeAttributeNS
124 $node->removeAttributeNS( $nsURI, $aname );
125 Namespace version of "removeAttribute"
127 hasAttribute
129 $boolean = $node->hasAttribute( $aname );
130 This function tests if the named attribute is set for the node. If
132 the attribute is specified, TRUE (1) will be returned, otherwise
133 the return value is FALSE (0).
134 hasAttributeNS
136 $boolean = $node->hasAttributeNS( $nsURI, $aname );
137 namespace version of "hasAttribute"
139 getChildrenByTagName
141 @nodes = $node->getChildrenByTagName($tagname);
142 The function gives direct access to all child elements of the
144 current node with a given tagname, where tagname is a qualified
145 name, that is, in case of namespace usage it may consist of a
146 prefix and local name. This function makes things a lot easier if
147 one needs to handle big data sets. A special tagname '*' can be
148 used to match any name.
149 If this function is called in SCALAR context, it returns the number
151 of elements found.
152 getChildrenByTagNameNS
154 @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
155 Namespace version of "getChildrenByTagName". A special nsURI '*'
157 matches any namespace URI, in which case the function behaves just
158 like "getChildrenByLocalName".
159 If this function is called in SCALAR context, it returns the number
161 of elements found.
162 getChildrenByLocalName
164 @nodes = $node->getChildrenByLocalName($localname);
165 The function gives direct access to all child elements of the
167 current node with a given local name. It makes things a lot easier
168 if one needs to handle big data sets. A special "localname" '*' can
169 be used to match any local name.
170 If this function is called in SCALAR context, it returns the number
172 of elements found.
173 getElementsByTagName
175 @nodes = $node->getElementsByTagName($tagname);
176 This function is part of the spec. It fetches all descendants of a
178 node with a given tagname, where "tagname" is a qualified name,
179 that is, in case of namespace usage it may consist of a prefix and
180 local name. A special "tagname" '*' can be used to match any tag
181 name.
182 In SCALAR context this function returns an XML::LibXML::NodeList
184 object.
185 getElementsByTagNameNS
187 @nodes = $node->getElementsByTagNameNS($nsURI,$localname);
188 Namespace version of "getElementsByTagName" as found in the DOM
190 spec. A special "localname" '*' can be used to match any local name
191 and "nsURI" '*' can be used to match any namespace URI.
192 In SCALAR context this function returns an XML::LibXML::NodeList
194 object.
195 getElementsByLocalName
197 @nodes = $node->getElementsByLocalName($localname);
198 This function is not found in the DOM specification. It is a mix of
200 getElementsByTagName and getElementsByTagNameNS. It will fetch all
201 tags matching the given local-name. This allows one to select tags
202 with the same local name across namespace borders.
203 In SCALAR context this function returns an XML::LibXML::NodeList
205 object.
206 appendWellBalancedChunk
208 $node->appendWellBalancedChunk( $chunk );
209 Sometimes it is necessary to append a string coded XML Tree to a
211 node. appendWellBalancedChunk will do the trick for you. But this
212 is only done if the String is "well-balanced".
213 Note that appendWellBalancedChunk() is only left for compatibility
215 reasons. Implicitly it uses
216 my $fragment = $parser->parse_balanced_chunk( $chunk );
218 $node->appendChild( $fragment );
219 This form is more explicit and makes it easier to control the flow
221 of a script.
222 appendText
224 $node->appendText( $PCDATA );
225 alias for appendTextNode().
227 appendTextNode
229 $node->appendTextNode( $PCDATA );
230 This wrapper function lets you add a string directly to an element
232 node.
233 appendTextChild
235 $node->appendTextChild( $childname , $PCDATA );
236 Somewhat similar with "appendTextNode": It lets you set an Element,
238 that contains only a "text node" directly by specifying the name
239 and the text content.
240 setNamespace
242 $node->setNamespace( $nsURI , $nsPrefix, $activate );
243 setNamespace() allows one to apply a namespace to an element. The
245 function takes three parameters: 1. the namespace URI, which is
246 required and the two optional values prefix, which is the namespace
247 prefix, as it should be used in child elements or attributes as
248 well as the additional activate parameter. If prefix is not given,
249 undefined or empty, this function tries to create a declaration of
250 the default namespace.
251 The activate parameter is most useful: If this parameter is set to
253 FALSE (0), a new namespace declaration is simply added to the
254 element while the element's namespace itself is not altered.
255 Nevertheless, activate is set to TRUE (1) on default. In this case
256 the namespace is used as the node's effective namespace. This
257 means the namespace prefix is added to the node name and if there
258 was a namespace already active for the node, it will be replaced
259 (but its declaration is not removed from the document). A new
260 namespace declaration is only created if necessary (that is, if the
261 element is already in the scope of a namespace declaration
262 associating the prefix with the namespace URI, then this
263 declaration is reused).
264 The following example may clarify this:
266 my $e1 = $doc->createElement("bar");
268 $e1->setNamespace("http://foobar.org", "foo")
269 results
271 <foo:bar xmlns:foo="http://foobar.org"/>
273 while
275 my $e2 = $doc->createElement("bar");
277 $e2->setNamespace("http://foobar.org", "foo",0)
278 results only
280 <bar xmlns:foo="http://foobar.org"/>
282 By using $activate == 0 it is possible to create multiple namespace
284 declarations on a single element.
285 The function fails if it is required to create a declaration
287 associating the prefix with the namespace URI but the element
288 already carries a declaration with the same prefix but different
289 namespace URI.
290 setNamespaceDeclURI
292 $node->setNamespaceDeclURI( $nsPrefix, $newURI );
293 EXPERIMENTAL IN 1.61 !
295 This function manipulates directly with an existing namespace
297 declaration on an element. It takes two parameters: the prefix by
298 which it looks up the namespace declaration and a new namespace URI
299 which replaces its previous value.
300 It returns 1 if the namespace declaration was found and changed, 0
302 otherwise.
303 All elements and attributes (even those previously unbound from the
305 document) for which the namespace declaration determines their
306 namespace belong to the new namespace after the change.
307 If the new URI is undef or empty, the nodes have no namespace and
309 no prefix after the change. Namespace declarations once nulled in
310 this way do not further appear in the serialized output (but do
311 remain in the document for internal integrity of libxml2 data
312 structures).
313 This function is NOT part of any DOM API.
315 setNamespaceDeclPrefix
317 $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
318 EXPERIMENTAL IN 1.61 !
320 This function manipulates directly with an existing namespace
322 declaration on an element. It takes two parameters: the old prefix
323 by which it looks up the namespace declaration and a new prefix
324 which is to replace the old one.
325 The function dies with an error if the element is in the scope of
327 another declaration whose prefix equals to the new prefix, or if
328 the change should result in a declaration with a non-empty prefix
329 but empty namespace URI. Otherwise, it returns 1 if the namespace
330 declaration was found and changed and 0 if not found.
331 All elements and attributes (even those previously unbound from the
333 document) for which the namespace declaration determines their
334 namespace change their prefix to the new value.
335 If the new prefix is undef or empty, the namespace declaration
337 becomes a declaration of a default namespace. The corresponding
338 nodes drop their namespace prefix (but remain in the, now default,
339 namespace). In this case the function fails, if the containing
340 element is in the scope of another default namespace declaration.
341 This function is NOT part of any DOM API.
343
345 XML::LibXML::Element overloads hash dereferencing to provide access to
346 the element's attributes. For non-namespaced attributes, the attribute
347 name is the hash key, and the attribute value is the hash value. For
348 namespaced attributes, the hash key is qualified with the namespace
349 URI, using Clark notation.
350 Perl's "tied hash" feature is used, which means that the hash gives you
352 read-write access to the element's attributes. For more information,
353 see XML::LibXML::AttributeHash
354
356 Matt Sergeant, Christian Glahn, Petr Pajas
357
359 2.0209
360
362 2001-2007, AxKit.com Ltd.
363 2002-2006, Christian Glahn.
365 2006-2009, Petr Pajas.
367
369 This program is free software; you can redistribute it and/or modify it
370 under the same terms as Perl itself.
371perl v5.38.0 2023-07-21 XML::LibXML::Element(3)