diff options
Diffstat (limited to 'chromium/third_party/cygwin/lib/perl5/vendor_perl/5.10/i686-cygwin/XML/LibXML/Node.pod')
| -rw-r--r-- | chromium/third_party/cygwin/lib/perl5/vendor_perl/5.10/i686-cygwin/XML/LibXML/Node.pod | 661 |
1 files changed, 661 insertions, 0 deletions
diff --git a/chromium/third_party/cygwin/lib/perl5/vendor_perl/5.10/i686-cygwin/XML/LibXML/Node.pod b/chromium/third_party/cygwin/lib/perl5/vendor_perl/5.10/i686-cygwin/XML/LibXML/Node.pod new file mode 100644 index 00000000000..6da553ec6b3 --- /dev/null +++ b/chromium/third_party/cygwin/lib/perl5/vendor_perl/5.10/i686-cygwin/XML/LibXML/Node.pod @@ -0,0 +1,661 @@ +=head1 NAME + +XML::LibXML::Node - Abstract Base Class of XML::LibXML Nodes + +=head1 SYNOPSIS + + + + use XML::LibXML; + + $name = $node->nodeName; + $node->setNodeName( $newName ); + $bool = $node->isSameNode( $other_node ); + $bool = $node->isEqual( $other_node ); + $content = $node->nodeValue; + $content = $node->textContent; + $type = $node->nodeType; + $node->unbindNode(); + $childnode = $node->removeChild( $childnode ); + $oldnode = $node->replaceChild( $newNode, $oldNode ); + $node->replaceNode($newNode); + $childnode = $node->appendChild( $childnode ); + $childnode = $node->addChild( $chilnode ); + $node = $parent->addNewChild( $nsURI, $name ); + $node->addSibling($newNode); + $newnode =$node->cloneNode( $deep ); + $parentnode = $node->parentNode; + $nextnode = $node->nextSibling(); + $prevnode = $node->previousSibling(); + $boolean = $node->hasChildNodes(); + $childnode = $node->firstChild; + $childnode = $node->lastChild; + $documentnode = $node->ownerDocument; + $node = $node->getOwner; + $node->setOwnerDocument( $doc ); + $node->insertBefore( $newNode, $refNode ); + $node->insertAfter( $newNode, $refNode ); + @nodes = $node->findnodes( $xpath_expression ); + $result = $node->find( $xpath ); + print $node->findvalue( $xpath ); + @childnodes = $node->childNodes; + $xmlstring = $node->toString($format,$docencoding); + $c14nstring = $node->toStringC14N($with_comments, $xpath_expression); + $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list); + $str = $doc->serialize($format); + $c14nstr = $doc->serialize_c14n($comment_flag,$xpath); + $ec14nstr = $doc->serialize_ec14n($comment_flag,$xpath,$inclusive_prefix_list); + $localname = $node->localname; + $nameprefix = $node->prefix; + $uri = $node->namespaceURI(); + $boolean = $node->hasAttributes(); + @attributelist = $node->attributes(); + $URI = $node->lookupNamespaceURI( $prefix ); + $prefix = $node->lookupNamespacePrefix( $URI ); + $node->normalize; + @nslist = $node->getNamespaces; + $node->removeChildNodes(); + $node->nodePath(); + $lineno = $node->line_number(); + +=head1 DESCRIPTION + +XML::LibXML::Node defines functions that are common to all Node Types. A +LibXML::Node should never be created standalone, but as an instance of a high +level class such as LibXML::Element or LibXML::Text. The class itself should +provide only common functionality. In XML::LibXML each node is part either of a +document or a document-fragment. Because of this there is no node without a +parent. This may causes confusion with "unbound" nodes. + + +=head1 METHODS + +Many functions listed here are extensively documented in the L<<<<<< DOM Level 3 specification|http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>. Please refer to the specification for extensive documentation. + +=over 4 + +=item B<nodeName> + + $name = $node->nodeName; + +Returns the node's name. This function is aware of namespaces and returns the +full name of the current node (C<<<<<< prefix:localname >>>>>>). + +Since 1.62 this function also returns the correct DOM names for node types with +constant names, namely: #text, #cdata-section, #comment, #document, +#document-fragment. + + +=item B<setNodeName> + + $node->setNodeName( $newName ); + +In very limited situations, it is useful to change a nodes name. In the DOM +specification this should throw an error. This Function is aware of namespaces. + + +=item B<isSameNode> + + $bool = $node->isSameNode( $other_node ); + +returns TRUE (1) if the given nodes refer to the same node structure, otherwise +FALSE (0) is returned. + + +=item B<isEqual> + + $bool = $node->isEqual( $other_node ); + +deprecated version of isSameNode(). + +I<<<<<< NOTE >>>>>> isEqual will change behaviour to follow the DOM specification + + +=item B<nodeValue> + + $content = $node->nodeValue; + +If the node has any content (such as stored in a C<<<<<< text node >>>>>>) it can get requested through this function. + +I<<<<<< NOTE: >>>>>> Element Nodes have no content per definition. To get the text value of an +Element use textContent() instead! + + +=item B<textContent> + + $content = $node->textContent; + +this function returns the content of all text nodes in the descendants of the +given node as specified in DOM. + + +=item B<nodeType> + + $type = $node->nodeType; + +Return a numeric value representing the node type of this node. The module +XML::LibXML by default exports constants for the node types (see the EXPORT +section in the L<<<<<< Perl Binding for libxml2|Perl Binding for libxml2 >>>>>> manual page). + + +=item B<unbindNode> + + $node->unbindNode(); + +Unbinds the Node from its siblings and Parent, but not from the Document it +belongs to. If the node is not inserted into the DOM afterwards it will be lost +after the program terminated. From a low level view, the unbound node is +stripped from the context it is and inserted into a (hidden) document-fragment. + + +=item B<removeChild> + + $childnode = $node->removeChild( $childnode ); + +This will unbind the Child Node from its parent C<<<<<< $node >>>>>>. The function returns the unbound node. If C<<<<<< oldNode >>>>>> is not a child of the given Node the function will fail. + + +=item B<replaceChild> + + $oldnode = $node->replaceChild( $newNode, $oldNode ); + +Replaces the C<<<<<< $oldNode >>>>>> with the C<<<<<< $newNode >>>>>>. The C<<<<<< $oldNode >>>>>> will be unbound from the Node. This function differs from the DOM L2 +specification, in the case, if the new node is not part of the document, the +node will be imported first. + + +=item B<replaceNode> + + $node->replaceNode($newNode); + +This function is very similar to replaceChild(), but it replaces the node +itself rather than a childnode. This is useful if a node found by any XPath +function, should be replaced. + + +=item B<appendChild> + + $childnode = $node->appendChild( $childnode ); + +The function will add the C<<<<<< $childnode >>>>>> to the end of C<<<<<< $node >>>>>>'s children. The function should fail, if the new childnode is already a child +of C<<<<<< $node >>>>>>. This function differs from the DOM L2 specification, in the case, if the new +node is not part of the document, the node will be imported first. + + +=item B<addChild> + + $childnode = $node->addChild( $chilnode ); + +As an alternative to appendChild() one can use the addChild() function. This +function is a bit faster, because it avoids all DOM conformity checks. +Therefore this function is quite useful if one builds XML documents in memory +where the order and ownership (C<<<<<< ownerDocument >>>>>>) is assured. + +addChild() uses libxml2's own xmlAddChild() function. Thus it has to be used +with extra care: If a text node is added to a node and the node itself or its +last childnode is as well a text node, the node to add will be merged with the +one already available. The current node will be removed from memory after this +action. Because perl is not aware of this action, the perl instance is still +available. XML::LibXML will catch the loss of a node and refuse to run any +function called on that node. + + + + my $t1 = $doc->createTextNode( "foo" ); + my $t2 = $doc->createTextNode( "bar" ); + $t1->addChild( $t2 ); # is OK + my $val = $t2->nodeValue(); # will fail, script dies + +Also addChild() will not check if the added node belongs to the same document +as the node it will be added to. This could lead to inconsistent documents and +in more worse cases even to memory violations, if one does not keep track of +this issue. + +Although this sounds like a lot of trouble, addChild() is useful if a document +is built from a stream, such as happens sometimes in SAX handlers or filters. + +If you are not sure about the source of your nodes, you better stay with +appendChild(), because this function is more user friendly in the sense of +being more error tolerant. + + +=item B<addNewChild> + + $node = $parent->addNewChild( $nsURI, $name ); + +Similar to C<<<<<< addChild() >>>>>>, this function uses low level libxml2 functionality to provide faster +interface for DOM building. I<<<<<< addNewChild() >>>>>> uses C<<<<<< xmlNewChild() >>>>>> to create a new node on a given parent element. + +addNewChild() has two parameters $nsURI and $name, where $nsURI is an +(optional) namespace URI. $name is the fully qualified element name; +addNewChild() will determine the correct prefix if necessary. + +The function returns the newly created node. + +This function is very useful for DOM building, where a created node can be +directly associated with its parent. I<<<<<< NOTE >>>>>> this function is not part of the DOM specification and its use will limit your +code to XML::LibXML. + + +=item B<addSibling> + + $node->addSibling($newNode); + +addSibling() allows adding an additional node to the end of a nodelist, defined +by the given node. + + +=item B<cloneNode> + + $newnode =$node->cloneNode( $deep ); + +I<<<<<< cloneNode >>>>>> creates a copy of C<<<<<< $node >>>>>>. When $deep is set to 1 (true) the function will copy all childnodes as well. +If $deep is 0 only the current node will be copied. Note that in case of +element, attributes are copied even if $deep is 0. + +Note that the behavior of this function for $deep=0 has changed in 1.62 in +order to be consistent with the DOM spec (in older versions attributes and +namespace information was not copied for elements). + + +=item B<parentNode> + + $parentnode = $node->parentNode; + +Returns simply the Parent Node of the current node. + + +=item B<nextSibling> + + $nextnode = $node->nextSibling(); + +Returns the next sibling if any . + + +=item B<previousSibling> + + $prevnode = $node->previousSibling(); + +Analogous to I<<<<<< getNextSibling >>>>>> the function returns the previous sibling if any. + + +=item B<hasChildNodes> + + $boolean = $node->hasChildNodes(); + +If the current node has Childnodes this function returns TRUE (1), otherwise it +returns FALSE (0, not undef). + + +=item B<firstChild> + + $childnode = $node->firstChild; + +If a node has childnodes this function will return the first node in the +childlist. + + +=item B<lastChild> + + $childnode = $node->lastChild; + +If the C<<<<<< $node >>>>>> has childnodes this function returns the last child node. + + +=item B<ownerDocument> + + $documentnode = $node->ownerDocument; + +Through this function it is always possible to access the document the current +node is bound to. + + +=item B<getOwner> + + $node = $node->getOwner; + +This function returns the node the current node is associated with. In most +cases this will be a document node or a document fragment node. + + +=item B<setOwnerDocument> + + $node->setOwnerDocument( $doc ); + +This function binds a node to another DOM. This method unbinds the node first, +if it is already bound to another document. + +This function is the opposite calling of L<<<<<< XML::LibXML DOM Document Class|XML::LibXML DOM Document Class >>>>>>'s adoptNode() function. Because of this it has the same limitations with +Entity References as adoptNode(). + + +=item B<insertBefore> + + $node->insertBefore( $newNode, $refNode ); + +The method inserts C<<<<<< $newNode >>>>>> before C<<<<<< $refNode >>>>>>. If C<<<<<< $refNode >>>>>> is undefined, the newNode will be set as the new last child of the parent node. +This function differs from the DOM L2 specification, in the case, if the new +node is not part of the document, the node will be imported first, +automatically. + +$refNode has to be passed to the function even if it is undefined: + + + + $node->insertBefore( $newNode, undef ); # the same as $node->appendChild( $newNode ); + $node->insertBefore( $newNode ); # wrong + +Note, that the reference node has to be a direct child of the node the function +is called on. Also, $newChild is not allowed to be an ancestor of the new +parent node. + + +=item B<insertAfter> + + $node->insertAfter( $newNode, $refNode ); + +The method inserts C<<<<<< $newNode >>>>>> after C<<<<<< $refNode >>>>>>. If C<<<<<< $refNode >>>>>> is undefined, the newNode will be set as the new last child of the parent node. + +Note, that $refNode has to be passed explicitly even if it is undef. + + +=item B<findnodes> + + @nodes = $node->findnodes( $xpath_expression ); + +I<<<<<< findnodes >>>>>> evaluates the xpath expression (XPath 1.0) on the current node and returns the +resulting node set as an array. In scalar context returns a L<<<<<< XML::LibXML::NodeList|XML::LibXML::NodeList >>>>>> object. + +I<<<<<< NOTE ON NAMESPACES AND XPATH >>>>>>: + +A common mistake about XPath is to assume that node tests consisting of an +element name with no prefix match elements in the default namespace. This +assumption is wrong - by XPath specification, such node tests can only match +elements that are in no (i.e. null) namespace. + +So, for example, one cannot match the root element of an XHTML document with C<<<<<< $node->find('/html') >>>>>> since C<<<<<< '/html' >>>>>> would only match if the root element C<<<<<< <html> >>>>>> had no namespace, but all XHTML elements belong to the namespace +http://www.w3.org/1999/xhtml. (Note that C<<<<<< xmlns="..." >>>>>> namespace declarations can also be specified in a DTD, which makes the +situation even worse, since the XML document looks as if there was no default +namespace). + +There are several possible ways to deal with namespaces in XPath: + + +=over 4 + +=item * + +The recommended way is to use the L<<<<<< XPath Evaluation|XPath Evaluation >>>>>> module to define an explicit context for XPath evaluation, in which a document +independent prefix-to-namespace mapping can be defined. For example: + + + + my $xpc = XML::LibXML::XPathContext->new; + $xpc->registerNs('x', 'http://www.w3.org/1999/xhtml'); + $xpc->find('/x:html',$node); + + + +=item * + +Another possibility is to use prefixes declared in the queried document (if +known). If the document declares a prefix for the namespace in question (and +the context node is in the scope of the declaration), C<<<<<< XML::LibXML >>>>>> allows you to use the prefix in the XPath expression, e.g.: + + + + $node->find('/x:html'); + + + +=back + +See also XML::LibXML::XPathContext->findnodes. + + +=item B<find> + + $result = $node->find( $xpath ); + +I<<<<<< find >>>>>> evaluates the XPath 1.0 expression using the current node as the context of the +expression, and returns the result depending on what type of result the XPath +expression had. For example, the XPath "1 * 3 + 52" results in a L<<<<<< XML::LibXML::Number|XML::LibXML::Number >>>>>> object being returned. Other expressions might return a L<<<<<< XML::LibXML::Boolean|XML::LibXML::Boolean >>>>>> object, or a L<<<<<< XML::LibXML::Literal|XML::LibXML::Literal >>>>>> object (a string). Each of those objects uses Perl's overload feature to "do +the right thing" in different contexts. + +See also L<<<<<< XPath Evaluation|XPath Evaluation >>>>>>->find. + + +=item B<findvalue> + + print $node->findvalue( $xpath ); + +I<<<<<< findvalue >>>>>> is exactly equivalent to: + + + + $node->find( $xpath )->to_literal; + +That is, it returns the literal value of the results. This enables you to +ensure that you get a string back from your search, allowing certain shortcuts. +This could be used as the equivalent of XSLT's <xsl:value-of +select="some_xpath"/>. + +See also L<<<<<< XPath Evaluation|XPath Evaluation >>>>>>->findvalue. + + +=item B<childNodes> + + @childnodes = $node->childNodes; + +I<<<<<< getChildnodes >>>>>> implements a more intuitive interface to the childnodes of the current node. It +enables you to pass all children directly to a C<<<<<< map >>>>>> or C<<<<<< grep >>>>>>. If this function is called in scalar context, a L<<<<<< XML::LibXML::NodeList|XML::LibXML::NodeList >>>>>> object will be returned. + + +=item B<toString> + + $xmlstring = $node->toString($format,$docencoding); + +This method is similar to the method C<<<<<< toString >>>>>> of a L<<<<<< XML::LibXML DOM Document Class|XML::LibXML DOM Document Class >>>>>> but for a single node. It returns a string consisting of XML serialization of +the given node and all its descendants. Unlike C<<<<<< XML::LibXML::Document::toString >>>>>>, in this case the resulting string is by default a character string (UTF-8 +encoded with UTF8 flag on). An optional flag $format controls indentation, as +in C<<<<<< XML::LibXML::Document::toString >>>>>>. If the second optional $docencoding flag is true, the result will be a byte +string in the document encoding (see C<<<<<< XML::LibXML::Document::actualEncoding >>>>>>). + + +=item B<toStringC14N> + + $c14nstring = $node->toStringC14N($with_comments, $xpath_expression); + +The function is similar to toString(). Instead of simply serializing the +document tree, it transforms it as it is specified in the XML-C14N +Specification (see L<<<<<< http://www.w3.org/TR/xml-c14n|http://www.w3.org/TR/xml-c14n >>>>>>). Such transformation is known as canonization. + +If $with_comments is 0 or not defined, the result-document will not contain any +comments that exist in the original document. To include comments into the +canonized document, $with_comments has to be set to 1. + +The parameter $xpath_expression defines the nodeset of nodes that should be +visible in the resulting document. This can be used to filter out some nodes. +One has to note, that only the nodes that are part of the nodeset, will be +included into the result-document. Their child-nodes will not exist in the +resulting document, unless they are part of the nodeset defined by the xpath +expression. + +If $xpath_expression is omitted or empty, toStringC14N() will include all nodes +in the given sub-tree. + + +=item B<toStringEC14N> + + $ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list); + +The function is similar to toStringC14N() but follows the XML-EXC-C14N +Specification (see L<<<<<< http://www.w3.org/TR/xml-exc-c14n|http://www.w3.org/TR/xml-exc-c14n >>>>>>) for exclusive canonization of XML. + +The first two arguments are as above. If $inclusive_prefix_list is used, it +should be an ARRAY reference listing namespace prefixes that are to be handled +in the manner described by the Canonical XML Recommendation (i.e. preserved in +the output even if the namespace is not used). C.f. the spec for details. + + +=item B<serialize> + + $str = $doc->serialize($format); + +An alias for toString(). This function was name added to be more consistent +with libxml2. + + +=item B<serialize_c14n> + + $c14nstr = $doc->serialize_c14n($comment_flag,$xpath); + +An alias for toStringC14N(). + + +=item B<serialize_exc_c14n> + + $ec14nstr = $doc->serialize_ec14n($comment_flag,$xpath,$inclusive_prefix_list); + +An alias for toStringEC14N(). + + +=item B<localname> + + $localname = $node->localname; + +Returns the local name of a tag. This is the part behind the colon. + + +=item B<prefix> + + $nameprefix = $node->prefix; + +Returns the prefix of a tag. This is the part before the colon. + + +=item B<namespaceURI> + + $uri = $node->namespaceURI(); + +returns the URI of the current namespace. + + +=item B<hasAttributes> + + $boolean = $node->hasAttributes(); + +returns 1 (TRUE) if the current node has any attributes set, otherwise 0 +(FALSE) is returned. + + +=item B<attributes> + + @attributelist = $node->attributes(); + +This function returns all attributes and namespace declarations assigned to the +given node. + +Because XML::LibXML does not implement namespace declarations and attributes +the same way, it is required to test what kind of node is handled while +accessing the functions result. + +If this function is called in array context the attribute nodes are returned as +an array. In scalar context the function will return a L<<<<<< XML::LibXML::NamedNodeMap|XML::LibXML::NamedNodeMap >>>>>> object. + + +=item B<lookupNamespaceURI> + + $URI = $node->lookupNamespaceURI( $prefix ); + +Find a namespace URI by its prefix starting at the current node. + + +=item B<lookupNamespacePrefix> + + $prefix = $node->lookupNamespacePrefix( $URI ); + +Find a namespace prefix by its URI starting at the current node. + +I<<<<<< NOTE >>>>>> Only the namespace URIs are meant to be unique. The prefix is only document +related. Also the document might have more than a single prefix defined for a +namespace. + + +=item B<normalize> + + $node->normalize; + +This function normalizes adjacent text nodes. This function is not as strict as +libxml2's xmlTextMerge() function, since it will not free a node that is still +referenced by the perl layer. + + +=item B<getNamespaces> + + @nslist = $node->getNamespaces; + +If a node has any namespaces defined, this function will return these +namespaces. Note, that this will not return all namespaces that are in scope, +but only the ones declared explicitly for that node. + +Although getNamespaces is available for all nodes, it only makes sense if used +with element nodes. + + +=item B<removeChildNodes> + + $node->removeChildNodes(); + +This function is not specified for any DOM level: It removes all childnodes +from a node in a single step. Other than the libxml2 function itself +(xmlFreeNodeList), this function will not immediately remove the nodes from the +memory. This saves one from getting memory violations, if there are nodes still +referred to from the Perl level. + + +=item B<nodePath> + + $node->nodePath(); + +This function is not specified for any DOM level: It returns a canonical +structure based XPath for a given node. + + +=item B<line_number> + + $lineno = $node->line_number(); + +This function returns the line number where the tag was found during parsing. +If a node is added to the document the line number is 0. Problems may occur, if +a node from one document is passed to another one. + +IMPORTANT: Due to limitations in the libxml2 library line numbers greater than +65535 will be returned as 65535. Please see L<<<<<< http://bugzilla.gnome.org/show_bug.cgi?id=325533|http://bugzilla.gnome.org/show_bug.cgi?id=325533 >>>>>> for more details. + +Note: line_number() is special to XML::LibXML and not part of the DOM +specification. + +If the line_numbers flag of the parser was not activated before parsing, +line_number() will always return 0. + + + +=back + +=head1 AUTHORS + +Matt Sergeant, +Christian Glahn, +Petr Pajas + + +=head1 VERSION + +1.66 + +=head1 COPYRIGHT + +2001-2007, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006-2008 Petr Pajas, All rights reserved. + +=cut |