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 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->setAttributeNS( $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/
44 <http://www.w3.org/TR/DOM-Level-3-Core/>). Please refer to the
45 specification for extensive documentation.
46 new
48 $node = XML::LibXML::Element->new( $name );
49 This function creates a new node unbound to any DOM.
51 setAttribute
53 $node->setAttribute( $aname, $avalue );
54 This method sets or replaces the node's attribute $aname to the
56 value $avalue
57 setAttributeNS
59 $node->setAttributeNS( $nsURI, $aname, $avalue );
60 Namespace-aware version of "setAttribute", where $nsURI is a
62 namespace URI, $aname is a qualified name, and $avalue is the
63 value. The namespace URI may be null (empty or undefined) in order
64 to create an attribute which has no namespace.
65 The current implementation differs from DOM in the following
67 aspects
68 If an attribute with the same local name and namespace URI already
70 exists on the element, but its prefix differs from the prefix of
71 $aname, then this function is supposed to change the prefix
72 (regardless of namespace declarations and possible collisions).
73 However, the current implementation does rather the opposite. If a
74 prefix is declared for the namespace URI in the scope of the
75 attribute, then the already declared prefix is used, disregarding
76 the prefix specified in $aname. If no prefix is declared for the
77 namespace, the function tries to declare the prefix specified in
78 $aname and dies if the prefix is already taken by some other
79 namespace.
80 According to DOM Level 2 specification, this method can also be
82 used to create or modify special attributes used for declaring XML
83 namespaces (which belong to the namespace
84 "http://www.w3.org/2000/xmlns/" and have prefix or name "xmlns").
85 This should work since version 1.61, but again the implementation
86 differs from DOM specification in the following: if a declaration
87 of the same namespace prefix already exists on the element, then
88 changing its value via this method automatically changes the
89 namespace of all elements and attributes in its scope. This is
90 because in libxml2 the namespace URI of an element is not static
91 but is computed from a pointer to a namespace declaration
92 attribute.
93 getAttribute
95 $avalue = $node->getAttribute( $aname );
96 If $node has an attribute with the name $aname, the value of this
98 attribute will get returned.
99 getAttributeNS
101 $avalue = $node->setAttributeNS( $nsURI, $aname );
102 Retrieves an attribute value by local name and namespace URI.
104 getAttributeNode
106 $attrnode = $node->getAttributeNode( $aname );
107 Retrieve an attribute node by name. If no attribute with a given
109 name exists, "undef" is returned.
110 getAttributeNodeNS
112 $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
113 Retrieves an attribute node by local name and namespace URI. If no
115 attribute with a given localname and namespace exists, "undef" is
116 returned.
117 removeAttribute
119 $node->removeAttribute( $aname );
120 The method removes the attribute $aname from the node's attribute
122 list, if the attribute can be found.
123 removeAttributeNS
125 $node->removeAttributeNS( $nsURI, $aname );
126 Namespace version of "removeAttribute"
128 hasAttribute
130 $boolean = $node->hasAttribute( $aname );
131 This function tests if the named attribute is set for the node. If
133 the attribute is specified, TRUE (1) will be returned, otherwise
134 the return value is FALSE (0).
135 hasAttributeNS
137 $boolean = $node->hasAttributeNS( $nsURI, $aname );
138 namespace version of "hasAttribute"
140 getChildrenByTagName
142 @nodes = $node->getChildrenByTagName($tagname);
143 The function gives direct access to all child elements of the
145 current node with a given tagname, where tagname is a qualified
146 name, that is, in case of namespace usage it may consist of a
147 prefix and local name. This function makes things a lot easier if
148 one needs to handle big data sets. A special tagname '*' can be
149 used to match any name.
150 If this function is called in SCALAR context, it returns the number
152 of elements found.
153 getChildrenByTagNameNS
155 @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
156 Namespace version of "getChildrenByTagName". A special nsURI '*'
158 matches any namespace URI, in which case the function behaves just
159 like "getChildrenByLocalName".
160 If this function is called in SCALAR context, it returns the number
162 of elements found.
163 getChildrenByLocalName
165 @nodes = $node->getChildrenByLocalName($localname);
166 The function gives direct access to all child elements of the
168 current node with a given local name. It makes things a lot easier
169 if one needs to handle big data sets. A special "localname" '*' can
170 be used to match any local name.
171 If this function is called in SCALAR context, it returns the number
173 of elements found.
174 getElementsByTagName
176 @nodes = $node->getElementsByTagName($tagname);
177 This function is part of the spec. It fetches all descendants of a
179 node with a given tagname, where "tagname" is a qualified name,
180 that is, in case of namespace usage it may consist of a prefix and
181 local name. A special "tagname" '*' can be used to match any tag
182 name.
183 In SCALAR context this function returns a XML::LibXML::NodeList
185 object.
186 getElementsByTagNameNS
188 @nodes = $node->getElementsByTagNameNS($nsURI,$localname);
189 Namespace version of "getElementsByTagName" as found in the DOM
191 spec. A special "localname" '*' can be used to match any local name
192 and "nsURI" '*' can be used to match any namespace URI.
193 In SCALAR context this function returns a XML::LibXML::NodeList
195 object.
196 getElementsByLocalName
198 @nodes = $node->getElementsByLocalName($localname);
199 This function is not found in the DOM specification. It is a mix of
201 getElementsByTagName and getElementsByTagNameNS. It will fetch all
202 tags matching the given local-name. This allows one to select tags
203 with the same local name across namespace borders.
204 In SCALAR context this function returns a XML::LibXML::NodeList
206 object.
207 appendWellBalancedChunk
209 $node->appendWellBalancedChunk( $chunk );
210 Sometimes it is necessary to append a string coded XML Tree to a
212 node. appendWellBalancedChunk will do the trick for you. But this
213 is only done if the String is "well-balanced".
214 Note that appendWellBalancedChunk() is only left for compatibility
216 reasons. Implicitly it uses
217 my $fragment = $parser->parse_xml_chunk( $chunk );
219 $node->appendChild( $fragment );
220 This form is more explicit and makes it easier to control the flow
222 of a script.
223 appendText
225 $node->appendText( $PCDATA );
226 alias for appendTextNode().
228 appendTextNode
230 $node->appendTextNode( $PCDATA );
231 This wrapper function lets you add a string directly to an element
233 node.
234 appendTextChild
236 $node->appendTextChild( $childname , $PCDATA );
237 Somewhat similar with "appendTextNode": It lets you set an Element,
239 that contains only a "text node" directly by specifying the name
240 and the text content.
241 setNamespace
243 $node->setNamespace( $nsURI , $nsPrefix, $activate );
244 setNamespace() allows one to apply a namespace to an element. The
246 function takes three parameters: 1. the namespace URI, which is
247 required and the two optional values prefix, which is the namespace
248 prefix, as it should be used in child elements or attributes as
249 well as the additional activate parameter. If prefix is not given,
250 undefined or empty, this function tries to create a declaration of
251 the default namespace.
252 The activate parameter is most useful: If this parameter is set to
254 FALSE (0), a new namespace declaration is simply added to the
255 element while the element's namespace itself is not altered.
256 Nevertheless, activate is set to TRUE (1) on default. In this case
257 the namespace is used as the node's effective namespace. This
258 means the namespace prefix is added to the node name and if there
259 was a namespace already active for the node, it will be replaced
260 (but its declaration is not removed from the document). A new
261 namespace declaration is only created if necessary (that is, if the
262 element is already in the scope of a namespace declaration
263 associating the prefix with the namespace URI, then this
264 declaration is reused).
265 The following example may clarify this:
267 my $e1 = $doc->createElement("bar");
269 $e1->setNamespace("http://foobar.org", "foo")
270 results
272 <foo:bar xmlns:foo="http://foobar.org"/>
274 while
276 my $e2 = $doc->createElement("bar");
278 $e2->setNamespace("http://foobar.org", "foo",0)
279 results only
281 <bar xmlns:foo="http://foobar.org"/>
283 By using $activate == 0 it is possible to create multiple namespace
285 declarations on a single element.
286 The function fails if it is required to create a declaration
288 associating the prefix with the namespace URI but the element
289 already carries a declaration with the same prefix but different
290 namespace URI.
291 setNamespaceDeclURI
293 $node->setNamespaceDeclURI( $nsPrefix, $newURI );
294 EXPERIMENTAL IN 1.61 !
296 This function manipulates directly with an existing namespace
298 declaration on an element. It takes two parameters: the prefix by
299 which it looks up the namespace declaration and a new namespace URI
300 which replaces its previous value.
301 It returns 1 if the namespace declaration was found and changed, 0
303 otherwise.
304 All elements and attributes (even those previously unbound from the
306 document) for which the namespace declaration determines their
307 namespace belong to the new namespace after the change.
308 If the new URI is undef or empty, the nodes have no namespace and
310 no prefix after the change. Namespace declarations once nulled in
311 this way do not further appear in the serialized output (but do
312 remain in the document for internal integrity of libxml2 data
313 structures).
314 This function is NOT part of any DOM API.
316 setNamespaceDeclPrefix
318 $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
319 EXPERIMENTAL IN 1.61 !
321 This function manipulates directly with an existing namespace
323 declaration on an element. It takes two parameters: the old prefix
324 by which it looks up the namespace declaration and a new prefix
325 which is to replace the old one.
326 The function dies with an error if the element is in the scope of
328 another declaration whose prefix equals to the new prefix, or if
329 the change should result in a declaration with a non-empty prefix
330 but empty namespace URI. Otherwise, it returns 1 if the namespace
331 declaration was found and changed and 0 if not found.
332 All elements and attributes (even those previously unbound from the
334 document) for which the namespace declaration determines their
335 namespace change their prefix to the new value.
336 If the new prefix is undef or empty, the namespace declaration
338 becomes a declaration of a default namespace. The corresponding
339 nodes drop their namespace prefix (but remain in the, now default,
340 namespace). In this case the function fails, if the containing
341 element is in the scope of another default namespace declaration.
342 This function is NOT part of any DOM API.
344
346 Matt Sergeant, Christian Glahn, Petr Pajas
347
349 1.70
350
352 2001-2007, AxKit.com Ltd.
353 2002-2006, Christian Glahn.
355 2006-2009, Petr Pajas.
357perl v5.12.0 2009-10-07 XML::LibXML::Element(3)