summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl.straw/lib/XML/LibXML/Element.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl.straw/lib/XML/LibXML/Element.pod')
-rwxr-xr-xMaster/tlpkg/tlperl.straw/lib/XML/LibXML/Element.pod384
1 files changed, 384 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl.straw/lib/XML/LibXML/Element.pod b/Master/tlpkg/tlperl.straw/lib/XML/LibXML/Element.pod
new file mode 100755
index 00000000000..b938c25d78c
--- /dev/null
+++ b/Master/tlpkg/tlperl.straw/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