1XML::LibXML::Element(3)User Contributed Perl DocumentatioXnML::LibXML::Element(3)
2
3
4

NAME

6       XML::LibXML::Element - XML::LibXML Class for Element Nodes
7

SYNOPSIS

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
13         $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

METHODS

39       The class inherits from XML::LibXML::Node. The documentation for
40       Inherited methods is not listed here.
41
42       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
46       new
47             $node = XML::LibXML::Element->new( $name );
48
49           This function creates a new node unbound to any DOM.
50
51       setAttribute
52             $node->setAttribute( $aname, $avalue );
53
54           This method sets or replaces the node's attribute $aname to the
55           value $avalue
56
57       setAttributeNS
58             $node->setAttributeNS( $nsURI, $aname, $avalue );
59
60           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
65           The current implementation differs from DOM in the following
66           aspects
67
68           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
80           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
93       getAttribute
94             $avalue = $node->getAttribute( $aname );
95
96           If $node has an attribute with the name $aname, the value of this
97           attribute will get returned.
98
99       getAttributeNS
100             $avalue = $node->getAttributeNS( $nsURI, $aname );
101
102           Retrieves an attribute value by local name and namespace URI.
103
104       getAttributeNode
105             $attrnode = $node->getAttributeNode( $aname );
106
107           Retrieve an attribute node by name. If no attribute with a given
108           name exists, "undef" is returned.
109
110       getAttributeNodeNS
111             $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
112
113           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
117       removeAttribute
118             $node->removeAttribute( $aname );
119
120           The method removes the attribute $aname from the node's attribute
121           list, if the attribute can be found.
122
123       removeAttributeNS
124             $node->removeAttributeNS( $nsURI, $aname );
125
126           Namespace version of "removeAttribute"
127
128       hasAttribute
129             $boolean = $node->hasAttribute( $aname );
130
131           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
135       hasAttributeNS
136             $boolean = $node->hasAttributeNS( $nsURI, $aname );
137
138           namespace version of "hasAttribute"
139
140       getChildrenByTagName
141             @nodes = $node->getChildrenByTagName($tagname);
142
143           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
150           If this function is called in SCALAR context, it returns the number
151           of elements found.
152
153       getChildrenByTagNameNS
154             @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
155
156           Namespace version of "getChildrenByTagName". A special nsURI '*'
157           matches any namespace URI, in which case the function behaves just
158           like "getChildrenByLocalName".
159
160           If this function is called in SCALAR context, it returns the number
161           of elements found.
162
163       getChildrenByLocalName
164             @nodes = $node->getChildrenByLocalName($localname);
165
166           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
171           If this function is called in SCALAR context, it returns the number
172           of elements found.
173
174       getElementsByTagName
175             @nodes = $node->getElementsByTagName($tagname);
176
177           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
183           In SCALAR context this function returns an XML::LibXML::NodeList
184           object.
185
186       getElementsByTagNameNS
187             @nodes = $node->getElementsByTagNameNS($nsURI,$localname);
188
189           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
193           In SCALAR context this function returns an XML::LibXML::NodeList
194           object.
195
196       getElementsByLocalName
197             @nodes = $node->getElementsByLocalName($localname);
198
199           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
204           In SCALAR context this function returns an XML::LibXML::NodeList
205           object.
206
207       appendWellBalancedChunk
208             $node->appendWellBalancedChunk( $chunk );
209
210           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
214           Note that appendWellBalancedChunk() is only left for compatibility
215           reasons. Implicitly it uses
216
217             my $fragment = $parser->parse_balanced_chunk( $chunk );
218              $node->appendChild( $fragment );
219
220           This form is more explicit and makes it easier to control the flow
221           of a script.
222
223       appendText
224             $node->appendText( $PCDATA );
225
226           alias for appendTextNode().
227
228       appendTextNode
229             $node->appendTextNode( $PCDATA );
230
231           This wrapper function lets you add a string directly to an element
232           node.
233
234       appendTextChild
235             $node->appendTextChild( $childname , $PCDATA );
236
237           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
241       setNamespace
242             $node->setNamespace( $nsURI , $nsPrefix, $activate );
243
244           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
252           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
265           The following example may clarify this:
266
267             my $e1 = $doc->createElement("bar");
268              $e1->setNamespace("http://foobar.org", "foo")
269
270           results
271
272             <foo:bar xmlns:foo="http://foobar.org"/>
273
274           while
275
276             my $e2 = $doc->createElement("bar");
277              $e2->setNamespace("http://foobar.org", "foo",0)
278
279           results only
280
281             <bar xmlns:foo="http://foobar.org"/>
282
283           By using $activate == 0 it is possible to create multiple namespace
284           declarations on a single element.
285
286           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
291       setNamespaceDeclURI
292             $node->setNamespaceDeclURI( $nsPrefix, $newURI );
293
294           EXPERIMENTAL IN 1.61 !
295
296           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
301           It returns 1 if the namespace declaration was found and changed, 0
302           otherwise.
303
304           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
308           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
314           This function is NOT part of any DOM API.
315
316       setNamespaceDeclPrefix
317             $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
318
319           EXPERIMENTAL IN 1.61 !
320
321           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
326           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
332           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
336           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
342           This function is NOT part of any DOM API.
343

OVERLOADING

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
351       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

AUTHORS

356       Matt Sergeant, Christian Glahn, Petr Pajas
357

VERSION

359       2.0209
360
362       2001-2007, AxKit.com Ltd.
363
364       2002-2006, Christian Glahn.
365
366       2006-2009, Petr Pajas.
367

LICENSE

369       This program is free software; you can redistribute it and/or modify it
370       under the same terms as Perl itself.
371
372
373
374perl v5.38.0                      2023-07-21           XML::LibXML::Element(3)
Impressum