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, 0 insertions, 661 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 deleted file mode 100644 index 6da553ec6b3..00000000000 --- a/chromium/third_party/cygwin/lib/perl5/vendor_perl/5.10/i686-cygwin/XML/LibXML/Node.pod +++ /dev/null @@ -1,661 +0,0 @@ -=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 |