1XML::LibXML::Element(3)User Contributed Perl DocumentatioXnML::LibXML::Element(3)
2
6 XML::LibXML::Element - XML::LibXML Class for Element Nodes
7
9 $node = XML::LibXML::Element->new( $name );
10 $node->setAttribute( $aname, $avalue );
11 $node->setAttributeNS( $nsURI, $aname, $avalue );
12 $avalue = $node->getAttribute( $aname );
13 $avalue = $node->setAttributeNS( $nsURI, $aname );
14 $attrnode = $node->getAttributeNode( $aname );
15 $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
16 $node->removeAttribute( $aname );
17 $node->removeAttributeNS( $nsURI, $aname );
18 $boolean = $node->hasAttribute( $aname );
19 $boolean = $node->hasAttributeNS( $nsURI, $aname );
20 @nodes = $node->getChildrenByTagName($tagname);
21 @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
22 @nodes = $node->getChildrenByLocalName($localname);
23 @nodes = $node->getElementsByTagName($tagname);
24 @nodes = $node->getElementsByTagNameNS($nsURI,$localname);
25 @nodes = $node->getElementsByLocalName($localname);
26 $node->appendWellBalancedChunk( $chunk );
27 $node->appendText( $PCDATA );
28 $node->appendTextNode( $PCDATA );
29 $node->appendTextChild( $childname , $PCDATA );
30 $node->setNamespace( $nsURI , $nsPrefix, $activate );
31 $node->setNamespaceDeclURI( $nsPrefix, $newURI );
32 $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
33
35 new
36 $node = XML::LibXML::Element->new( $name );
37 This function creates a new node unbound to any DOM.
39 setAttribute
41 $node->setAttribute( $aname, $avalue );
42 This method sets or replaces the node's attribute $aname to the
44 value $avalue
45 setAttributeNS
47 $node->setAttributeNS( $nsURI, $aname, $avalue );
48 Namespace-aware version of setAttribute, where $nsURI is a names‐
50 pace URI, $aname is a qualified name, and $avalue is the value. The
51 namespace URI may be null (empty or undefined) in order to create
52 an attribute which has no namespace.
53 The current implementation differs from DOM in the following
55 aspectse
56 If an attribute with the same local name and namespace URI already
58 exists on the element, but its prefix differs from the prefix of
59 $aname, then this function is supposed to change the prefix
60 (regardless of namespace declarations and possible collisions).
61 However, the current implementation does rather the opposite. If a
62 prefix is declared for the namespace URI in the scope of the
63 attribute, then the already declared prefix is used, disregarding
64 the prefix specified in $aname. If no prefix is declared for the
65 namespace, the function tries to declare the prefix specified in
66 $aname and dies if the prefix is already taken by some other names‐
67 pace.
68 According to DOM Level 2 specification, this method can also be
70 used to create or modify special attributes used for declaring XML
71 namespaces (which belong to the namespace
72 "http://www.w3.org/2000/xmlns/" and have prefix or name "xmlns").
73 This should work since version 1.61, but again the implementation
74 differs from DOM specification in the following: if a declaration
75 of the same namespace prefix already exists on the element, then
76 changing its value via this method automatically changes the names‐
77 pace of all elements and attributes in its scope. This is because
78 in libxml2 the namespace URI of an element is not static but is
79 computed from a pointer to a namespace declaration attribute.
80 getAttribute
82 $avalue = $node->getAttribute( $aname );
83 If $node has an attribute with the name $aname, the value of this
85 attribute will get returned.
86 getAttributeNS
88 $avalue = $node->setAttributeNS( $nsURI, $aname );
89 Retrieves an attribute value by local name and namespace URI.
91 getAttributeNode
93 $attrnode = $node->getAttributeNode( $aname );
94 Retrieve an attribute node by name. If no attribute with a given
96 name exists, undef is returned.
97 getAttributeNodeNS
99 $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
100 Retrieves an attribute node by local name and namespace URI. If no
102 attribute with a given localname and namespace exists, undef is
103 returned.
104 removeAttribute
106 $node->removeAttribute( $aname );
107 The method removes the attribute $aname from the node's attribute
109 list, if the attribute can be found.
110 removeAttributeNS
112 $node->removeAttributeNS( $nsURI, $aname );
113 Namespace version of removeAttribute
115 hasAttribute
117 $boolean = $node->hasAttribute( $aname );
118 This funcion tests if the named attribute is set for the node. If
120 the attribute is specified, TRUE (1) will be returned, otherwise
121 the returnvalue is FALSE (0).
122 hasAttributeNS
124 $boolean = $node->hasAttributeNS( $nsURI, $aname );
125 namespace version of hasAttribute
127 getChildrenByTagName
129 @nodes = $node->getChildrenByTagName($tagname);
130 The function gives direct access to all child elements of the cur‐
132 rent node with a given tagname, where tagname is a qualified name,
133 that is, in case of namespace usage it may consist of a prefix and
134 local name. This function makes things a lot easier if one needs to
135 handle big datasets. A special tagname '*' can be used to match any
136 name.
137 If this function is called in SCALAR context, it returns the number
139 of elements found.
140 getChildrenByTagNameNS
142 @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
143 Namespace version of getChildrenByTagName. A special nsURI '*'
145 matches any namespace URI, in which case the function behaves just
146 like getChildrenByLocalName.
147 If this function is called in SCALAR context, it returns the number
149 of elements found.
150 getChildrenByLocalName
152 @nodes = $node->getChildrenByLocalName($localname);
153 The function gives direct access to all child elements of the cur‐
155 rent node with a given local name. It makes things a lot easier if
156 one needs to handle big datasets. A special localname '*' can be
157 used to match any local name.
158 If this function is called in SCALAR context, it returns the number
160 of elements found.
161 getElementsByTagName
163 @nodes = $node->getElementsByTagName($tagname);
164 This function is part of the spec. It fetches all descendants of a
166 node with a given tagname, where tagname is a qualified name, that
167 is, in case of namespace usage it may consist of a prefix and local
168 name. A special tagname '*' can be used to match any tag name.
169 In SCALAR context this function returns a XML::LibXML::NodeList
171 object.
172 getElementsByTagNameNS
174 @nodes = $node->getElementsByTagNameNS($nsURI,$localname);
175 Namespace version of getElementsByTagName as found in the DOM spec.
177 A special localname '*' can be used to match any local name and
178 nsURI '*' can be used to match any namespace URI.
179 In SCALAR context this function returns a XML::LibXML::NodeList
181 object.
182 getElementsByLocalName
184 @nodes = $node->getElementsByLocalName($localname);
185 This function is not found in the DOM specification. It is a mix of
187 getElementsByTagName and getElementsByTagNameNS. It will fetch all
188 tags matching the given local-name. This alows one to select tags
189 with the same local name across namespace borders.
190 In SCALAR context this function returns a XML::LibXML::NodeList
192 object.
193 appendWellBalancedChunk
195 $node->appendWellBalancedChunk( $chunk );
196 Sometimes it is nessecary to append a string coded XML Tree to a
198 node. appendWellBalancedChunk will do the trick for you. But this
199 is only done if the String is well-balanced.
200 Note that appendWellBalancedChunk() is only left for compatibility
202 reasons. Implicitly it uses
203 my $fragment = $parser->parse_xml_chunk( $chunk );
205 $node->appendChild( $fragment );
206 This form is more explicit and makes it easier to control the flow
208 of a script.
209 appendText
211 $node->appendText( $PCDATA );
212 alias for appendTextNode().
214 appendTextNode
216 $node->appendTextNode( $PCDATA );
217 This wrapper function lets you add a string directly to an element
219 node.
220 appendTextChild
222 $node->appendTextChild( $childname , $PCDATA );
223 Somewhat similar with appendTextNode: It lets you set an Element,
225 that contains only a text node directly by specifying the name and
226 the text content.
227 setNamespace
229 $node->setNamespace( $nsURI , $nsPrefix, $activate );
230 setNamespace() allows one to apply a namespace to an element. The
232 function takes three parameters: 1. the namespace URI, which is
233 required and the two optional values prefix, which is the namespace
234 prefix, as it should be used in child elements or attributes as
235 well as the additional activate parameter. If prefix is not given,
236 undefined or empty, this function tries to create a declaration of
237 the default namespace.
238 The activate parameter is most useful: If this parameter is set to
240 FALSE (0), a new namespace declaration is simply added to the ele‐
241 ment while the element's namespace itself is not altered. Neverthe‐
242 less, activate is set to TRUE (1) on default. In this case the
243 namespace is used as the node's effective namespace. This means
244 the namespace prefix is added to the node name and if there was a
245 namespace already active for the node, it will be replaced (but its
246 declaration is not removed from the document). A new namespace dec‐
247 laration is only created if necessary (that is, if the element is
248 already in the scope of a namespace declaration associating the
249 prefix with the namespace URI, then this declaration is reused).
250 The following example may clarify this:
252 my $e1 = $doc->createElement("bar");
254 $e1->setNamespace("http://foobar.org", "foo")
255 results
257 <foo:bar xmlns:foo="http://foobar.org"/>
259 while
261 my $e2 = $doc->createElement("bar");
263 $e2->setNamespace("http://foobar.org", "foo",0)
264 results only
266 <bar xmlns:foo="http://foobar.org"/>
268 By using $activate == 0 it is possible to create multiple namepace
270 declarations on a single element.
271 The function fails if it is required to create a declaration asso‐
273 ciating the prefix with the namespace URI but the element already
274 carries a declaration with the same prefix but different namespace
275 URI.
276 setNamespaceDeclURI
278 $node->setNamespaceDeclURI( $nsPrefix, $newURI );
279 EXPERIMENTAL IN 1.61 !
281 This function manipulates directly with an existing namespace dec‐
283 laration on an element. It takes two parameters: the prefix by
284 which it looks up the namespace declaration and a new namespace URI
285 which replaces its previous value.
286 It returns 1 if the namespace declaration was found and changed, 0
288 otherwise.
289 All elements and attributes (even those previously unbound from the
291 document) for which the namespace declaration determines their
292 namespace belong to the new namespace after the change.
293 If the new URI is undef or empty, the nodes have no namespace and
295 no prefix after the change. Namespace declarations once nulled in
296 this way do not further appear in the serialized output (but do
297 remain in the document for internal integrity of libxml2 data
298 structures).
299 This function is NOT part of any DOM API.
301 setNamespaceDeclPrefix
303 $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
304 EXPERIMENTAL IN 1.61 !
306 This function manipulates directly with an existing namespace dec‐
308 laration on an element. It takes two parameters: the old prefix by
309 which it looks up the namespace declaration and a new prefix which
310 is to replace the old one.
311 The function dies with an error if the element is in the scope of
313 another declaration whose prefix equals to the new prefix, or if
314 the change should result in a declaration with a non-empty prefix
315 but empty namespace URI. Otherwise, it returns 1 if the namespace
316 declaration was found and changed and 0 if not found.
317 All elements and attributes (even those previously unbound from the
319 document) for which the namespace declaration determines their
320 namespace change their prefix to the new value.
321 If the new prefix is undef or empty, the namespace declaration
323 becomes a declaration of a default namespace. The corresponding
324 nodes drop their namespace prefix (but remain in the, now default,
325 namespace). In this case the function fails, if the containig ele‐
326 ment is in the scope of another default namespace declaration.
327 This function is NOT part of any DOM API.
329
331 Matt Sergeant, Christian Glahn, Petr Pajas,
332
334 1.62
335
337 2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas,
338 All rights reserved.
339perl v5.8.8 2006-11-17 XML::LibXML::Element(3)