diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/XML/LibXML/Element.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl/lib/XML/LibXML/Element.pod | 384 |
1 files changed, 384 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/XML/LibXML/Element.pod b/Master/tlpkg/tlperl/lib/XML/LibXML/Element.pod new file mode 100755 index 00000000000..b938c25d78c --- /dev/null +++ b/Master/tlpkg/tlperl/lib/XML/LibXML/Element.pod @@ -0,0 +1,384 @@ +=head1 NAME + +XML::LibXML::Element - XML::LibXML Class for Element Nodes + +=head1 SYNOPSIS + + + + use XML::LibXML; + # Only methods specific to Element nodes are listed here, + # see XML::LibXML::Node manpage for other methods + + $node = XML::LibXML::Element->new( $name ); + $node->setAttribute( $aname, $avalue ); + $node->setAttributeNS( $nsURI, $aname, $avalue ); + $avalue = $node->getAttribute( $aname ); + $avalue = $node->setAttributeNS( $nsURI, $aname ); + $attrnode = $node->getAttributeNode( $aname ); + $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname ); + $node->removeAttribute( $aname ); + $node->removeAttributeNS( $nsURI, $aname ); + $boolean = $node->hasAttribute( $aname ); + $boolean = $node->hasAttributeNS( $nsURI, $aname ); + @nodes = $node->getChildrenByTagName($tagname); + @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname); + @nodes = $node->getChildrenByLocalName($localname); + @nodes = $node->getElementsByTagName($tagname); + @nodes = $node->getElementsByTagNameNS($nsURI,$localname); + @nodes = $node->getElementsByLocalName($localname); + $node->appendWellBalancedChunk( $chunk ); + $node->appendText( $PCDATA ); + $node->appendTextNode( $PCDATA ); + $node->appendTextChild( $childname , $PCDATA ); + $node->setNamespace( $nsURI , $nsPrefix, $activate ); + $node->setNamespaceDeclURI( $nsPrefix, $newURI ); + $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix ); + +=head1 METHODS + +The class inherits from L<<<<<< XML::LibXML::Node >>>>>>. The documentation for Inherited methods is not listed here. + +Many functions listed here are extensively documented in the DOM Level 3 specification (L<<<<<< http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>). Please refer to the specification for extensive documentation. + +=over 4 + +=item new + + $node = XML::LibXML::Element->new( $name ); + +This function creates a new node unbound to any DOM. + + +=item setAttribute + + $node->setAttribute( $aname, $avalue ); + +This method sets or replaces the node's attribute C<<<<<< $aname >>>>>> to the value C<<<<<< $avalue >>>>>> + + +=item setAttributeNS + + $node->setAttributeNS( $nsURI, $aname, $avalue ); + +Namespace-aware version of C<<<<<< setAttribute >>>>>>, where C<<<<<< $nsURI >>>>>> is a namespace URI, C<<<<<< $aname >>>>>> is a qualified name, and C<<<<<< $avalue >>>>>> is the value. The namespace URI may be null (empty or undefined) in order to +create an attribute which has no namespace. + +The current implementation differs from DOM in the following aspects + +If an attribute with the same local name and namespace URI already exists on +the element, but its prefix differs from the prefix of C<<<<<< $aname >>>>>>, then this function is supposed to change the prefix (regardless of namespace +declarations and possible collisions). However, the current implementation does +rather the opposite. If a prefix is declared for the namespace URI in the scope +of the attribute, then the already declared prefix is used, disregarding the +prefix specified in C<<<<<< $aname >>>>>>. If no prefix is declared for the namespace, the function tries to declare the +prefix specified in C<<<<<< $aname >>>>>> and dies if the prefix is already taken by some other namespace. + +According to DOM Level 2 specification, this method can also be used to create +or modify special attributes used for declaring XML namespaces (which belong to +the namespace "http://www.w3.org/2000/xmlns/" and have prefix or name "xmlns"). +This should work since version 1.61, but again the implementation differs from +DOM specification in the following: if a declaration of the same namespace +prefix already exists on the element, then changing its value via this method +automatically changes the namespace of all elements and attributes in its +scope. This is because in libxml2 the namespace URI of an element is not static +but is computed from a pointer to a namespace declaration attribute. + + +=item getAttribute + + $avalue = $node->getAttribute( $aname ); + +If C<<<<<< $node >>>>>> has an attribute with the name C<<<<<< $aname >>>>>>, the value of this attribute will get returned. + + +=item getAttributeNS + + $avalue = $node->setAttributeNS( $nsURI, $aname ); + +Retrieves an attribute value by local name and namespace URI. + + +=item getAttributeNode + + $attrnode = $node->getAttributeNode( $aname ); + +Retrieve an attribute node by name. If no attribute with a given name exists, C<<<<<< undef >>>>>> is returned. + + +=item getAttributeNodeNS + + $attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname ); + +Retrieves an attribute node by local name and namespace URI. If no attribute +with a given localname and namespace exists, C<<<<<< undef >>>>>> is returned. + + +=item removeAttribute + + $node->removeAttribute( $aname ); + +The method removes the attribute C<<<<<< $aname >>>>>> from the node's attribute list, if the attribute can be found. + + +=item removeAttributeNS + + $node->removeAttributeNS( $nsURI, $aname ); + +Namespace version of C<<<<<< removeAttribute >>>>>> + + +=item hasAttribute + + $boolean = $node->hasAttribute( $aname ); + +This function tests if the named attribute is set for the node. If the +attribute is specified, TRUE (1) will be returned, otherwise the return value +is FALSE (0). + + +=item hasAttributeNS + + $boolean = $node->hasAttributeNS( $nsURI, $aname ); + +namespace version of C<<<<<< hasAttribute >>>>>> + + +=item getChildrenByTagName + + @nodes = $node->getChildrenByTagName($tagname); + +The function gives direct access to all child elements of the current node with +a given tagname, where tagname is a qualified name, that is, in case of +namespace usage it may consist of a prefix and local name. This function makes +things a lot easier if one needs to handle big data sets. A special tagname '*' +can be used to match any name. + +If this function is called in SCALAR context, it returns the number of elements +found. + + +=item getChildrenByTagNameNS + + @nodes = $node->getChildrenByTagNameNS($nsURI,$tagname); + +Namespace version of C<<<<<< getChildrenByTagName >>>>>>. A special nsURI '*' matches any namespace URI, in which case the function +behaves just like C<<<<<< getChildrenByLocalName >>>>>>. + +If this function is called in SCALAR context, it returns the number of elements +found. + + +=item getChildrenByLocalName + + @nodes = $node->getChildrenByLocalName($localname); + +The function gives direct access to all child elements of the current node with +a given local name. It makes things a lot easier if one needs to handle big +data sets. A special C<<<<<< localname >>>>>> '*' can be used to match any local name. + +If this function is called in SCALAR context, it returns the number of elements +found. + + +=item getElementsByTagName + + @nodes = $node->getElementsByTagName($tagname); + +This function is part of the spec. It fetches all descendants of a node with a +given tagname, where C<<<<<< tagname >>>>>> is a qualified name, that is, in case of namespace usage it may consist of a +prefix and local name. A special C<<<<<< tagname >>>>>> '*' can be used to match any tag name. + +In SCALAR context this function returns a L<<<<<< XML::LibXML::NodeList >>>>>> object. + + +=item getElementsByTagNameNS + + @nodes = $node->getElementsByTagNameNS($nsURI,$localname); + +Namespace version of C<<<<<< getElementsByTagName >>>>>> as found in the DOM spec. A special C<<<<<< localname >>>>>> '*' can be used to match any local name and C<<<<<< nsURI >>>>>> '*' can be used to match any namespace URI. + +In SCALAR context this function returns a L<<<<<< XML::LibXML::NodeList >>>>>> object. + + +=item getElementsByLocalName + + @nodes = $node->getElementsByLocalName($localname); + +This function is not found in the DOM specification. It is a mix of +getElementsByTagName and getElementsByTagNameNS. It will fetch all tags +matching the given local-name. This allows one to select tags with the same +local name across namespace borders. + +In SCALAR context this function returns a L<<<<<< XML::LibXML::NodeList >>>>>> object. + + +=item appendWellBalancedChunk + + $node->appendWellBalancedChunk( $chunk ); + +Sometimes it is necessary to append a string coded XML Tree to a node. I<<<<<< appendWellBalancedChunk >>>>>> will do the trick for you. But this is only done if the String is C<<<<<< well-balanced >>>>>>. + +I<<<<<< Note that appendWellBalancedChunk() is only left for compatibility reasons >>>>>>. Implicitly it uses + + + + my $fragment = $parser->parse_xml_chunk( $chunk ); + $node->appendChild( $fragment ); + +This form is more explicit and makes it easier to control the flow of a script. + + +=item appendText + + $node->appendText( $PCDATA ); + +alias for appendTextNode(). + + +=item appendTextNode + + $node->appendTextNode( $PCDATA ); + +This wrapper function lets you add a string directly to an element node. + + +=item appendTextChild + + $node->appendTextChild( $childname , $PCDATA ); + +Somewhat similar with C<<<<<< appendTextNode >>>>>>: It lets you set an Element, that contains only a C<<<<<< text node >>>>>> directly by specifying the name and the text content. + + +=item setNamespace + + $node->setNamespace( $nsURI , $nsPrefix, $activate ); + +setNamespace() allows one to apply a namespace to an element. The function +takes three parameters: 1. the namespace URI, which is required and the two +optional values prefix, which is the namespace prefix, as it should be used in +child elements or attributes as well as the additional activate parameter. If +prefix is not given, undefined or empty, this function tries to create a +declaration of the default namespace. + +The activate parameter is most useful: If this parameter is set to FALSE (0), a +new namespace declaration is simply added to the element while the element's +namespace itself is not altered. Nevertheless, activate is set to TRUE (1) on +default. In this case the namespace is used as the node's effective namespace. +This means the namespace prefix is added to the node name and if there was a +namespace already active for the node, it will be replaced (but its declaration +is not removed from the document). A new namespace declaration is only created +if necessary (that is, if the element is already in the scope of a namespace +declaration associating the prefix with the namespace URI, then this +declaration is reused). + +The following example may clarify this: + + + + my $e1 = $doc->createElement("bar"); + $e1->setNamespace("http://foobar.org", "foo") + +results + + + + <foo:bar xmlns:foo="http://foobar.org"/> + +while + + + + my $e2 = $doc->createElement("bar"); + $e2->setNamespace("http://foobar.org", "foo",0) + +results only + + + + <bar xmlns:foo="http://foobar.org"/> + +By using $activate == 0 it is possible to create multiple namespace +declarations on a single element. + +The function fails if it is required to create a declaration associating the +prefix with the namespace URI but the element already carries a declaration +with the same prefix but different namespace URI. + + +=item setNamespaceDeclURI + + $node->setNamespaceDeclURI( $nsPrefix, $newURI ); + +EXPERIMENTAL IN 1.61 ! + +This function manipulates directly with an existing namespace declaration on an +element. It takes two parameters: the prefix by which it looks up the namespace +declaration and a new namespace URI which replaces its previous value. + +It returns 1 if the namespace declaration was found and changed, 0 otherwise. + +All elements and attributes (even those previously unbound from the document) +for which the namespace declaration determines their namespace belong to the +new namespace after the change. + +If the new URI is undef or empty, the nodes have no namespace and no prefix +after the change. Namespace declarations once nulled in this way do not further +appear in the serialized output (but do remain in the document for internal +integrity of libxml2 data structures). + +This function is NOT part of any DOM API. + + +=item setNamespaceDeclPrefix + + $node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix ); + +EXPERIMENTAL IN 1.61 ! + +This function manipulates directly with an existing namespace declaration on an +element. It takes two parameters: the old prefix by which it looks up the +namespace declaration and a new prefix which is to replace the old one. + +The function dies with an error if the element is in the scope of another +declaration whose prefix equals to the new prefix, or if the change should +result in a declaration with a non-empty prefix but empty namespace URI. +Otherwise, it returns 1 if the namespace declaration was found and changed and +0 if not found. + +All elements and attributes (even those previously unbound from the document) +for which the namespace declaration determines their namespace change their +prefix to the new value. + +If the new prefix is undef or empty, the namespace declaration becomes a +declaration of a default namespace. The corresponding nodes drop their +namespace prefix (but remain in the, now default, namespace). In this case the +function fails, if the containing element is in the scope of another default +namespace declaration. + +This function is NOT part of any DOM API. + + + +=back + +=head1 AUTHORS + +Matt Sergeant, +Christian Glahn, +Petr Pajas + + +=head1 VERSION + +1.70 + +=head1 COPYRIGHT + +2001-2007, AxKit.com Ltd. + +2002-2006, Christian Glahn. + +2006-2009, Petr Pajas. + +=cut |