{
    "content": [
        {
            "type": "text",
            "text": "# XML::DOM::Node (perldoc)\n\n## NAME\n\nXML::DOM::Node - Super class of all nodes in XML::DOM\n\n## DESCRIPTION\n\nXML::DOM::Node is the super class of all nodes in an XML::DOM document. This means that all\nnodes that subclass XML::DOM::Node also inherit all the methods that XML::DOM::Node implements.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "XML::DOM::Node",
        "section": "",
        "mode": "perldoc",
        "summary": "XML::DOM::Node - Super class of all nodes in XML::DOM",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 230,
                "subsections": [
                    {
                        "name": "Additional methods not in the DOM Spec",
                        "lines": 112
                    }
                ]
            }
        ],
        "sections": {
            "NAME": {
                "content": "XML::DOM::Node - Super class of all nodes in XML::DOM\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "XML::DOM::Node is the super class of all nodes in an XML::DOM document. This means that all\nnodes that subclass XML::DOM::Node also inherit all the methods that XML::DOM::Node implements.\n\nGLOBAL VARIABLES\n@NodeNames\nThe variable @XML::DOM::Node::NodeNames maps the node type constants to strings. It is used\nby XML::DOM::Node::getNodeTypeName.\n\nMETHODS\ngetNodeType\nReturn an integer indicating the node type. See XML::DOM constants.\n\ngetNodeName\nReturn a property or a hardcoded string, depending on the node type. Here are the\ncorresponding functions or values:\n\nAttr                   getName\nAttDef                 getName\nAttlistDecl            getName\nCDATASection           \"#cdata-section\"\nComment                \"#comment\"\nDocument               \"#document\"\nDocumentType           getNodeName\nDocumentFragment       \"#document-fragment\"\nElement                getTagName\nElementDecl            getName\nEntityReference        getEntityName\nEntity                 getNotationName\nNotation               getName\nProcessingInstruction  getTarget\nText                   \"#text\"\nXMLDecl                \"#xml-declaration\"\n\nNot In DOM Spec: AttDef, AttlistDecl, ElementDecl and XMLDecl were added for completeness.\n\ngetNodeValue and setNodeValue (value)\nReturns a string or undef, depending on the node type. This method is provided for\ncompleteness. In other languages it saves the programmer an upcast. The value is either\navailable thru some other method defined in the subclass, or else undef is returned. Here\nare the corresponding methods: Attr::getValue, Text::getData, CDATASection::getData,\nComment::getData, ProcessingInstruction::getData.\n\ngetParentNode and setParentNode (parentNode)\nThe parent of this node. All nodes, except Document, DocumentFragment, and Attr may have a\nparent. However, if a node has just been created and not yet added to the tree, or if it has\nbeen removed from the tree, this is undef.\n\ngetChildNodes\nA NodeList that contains all children of this node. If there are no children, this is a\nNodeList containing no nodes. The content of the returned NodeList is \"live\" in the sense\nthat, for instance, changes to the children of the node object that it was created from are\nimmediately reflected in the nodes returned by the NodeList accessors; it is not a static\nsnapshot of the content of the node. This is true for every NodeList, including the ones\nreturned by the getElementsByTagName method.\n\nNOTE: this implementation does not return a \"live\" NodeList for getElementsByTagName. See\nCAVEATS.\n\nWhen this method is called in a list context, it returns a regular perl list containing the\nchild nodes. Note that this list is not \"live\". E.g.\n\n@list = $node->getChildNodes;        # returns a perl list\n$nodelist = $node->getChildNodes;    # returns a NodeList (object reference)\nfor my $kid ($node->getChildNodes)   # iterate over the children of $node\n\ngetFirstChild\nThe first child of this node. If there is no such node, this returns undef.\n\ngetLastChild\nThe last child of this node. If there is no such node, this returns undef.\n\ngetPreviousSibling\nThe node immediately preceding this node. If there is no such node, this returns undef.\n\ngetNextSibling\nThe node immediately following this node. If there is no such node, this returns undef.\n\ngetAttributes\nA NamedNodeMap containing the attributes (Attr nodes) of this node (if it is an Element) or\nundef otherwise. Note that adding/removing attributes from the returned object, also\nadds/removes attributes from the Element node that the NamedNodeMap came from.\n\ngetOwnerDocument\nThe Document object associated with this node. This is also the Document object used to\ncreate new nodes. When this node is a Document this is undef.\n\ninsertBefore (newChild, refChild)\nInserts the node newChild before the existing child node refChild. If refChild is undef,\ninsert newChild at the end of the list of children.\n\nIf newChild is a DocumentFragment object, all of its children are inserted, in the same\norder, before refChild. If the newChild is already in the tree, it is first removed.\n\nReturn Value: The node being inserted.\n\nDOMExceptions:\n\n*   HIERARCHYREQUESTERR\n\nRaised if this node is of a type that does not allow children of the type of the\nnewChild node, or if the node to insert is one of this node's ancestors.\n\n*   WRONGDOCUMENTERR\n\nRaised if newChild was created from a different document than the one that created this\nnode.\n\n*   NOMODIFICATIONALLOWEDERR\n\nRaised if this node is readonly.\n\n*   NOTFOUNDERR\n\nRaised if refChild is not a child of this node.\n\nreplaceChild (newChild, oldChild)\nReplaces the child node oldChild with newChild in the list of children, and returns the\noldChild node. If the newChild is already in the tree, it is first removed.\n\nReturn Value: The node replaced.\n\nDOMExceptions:\n\n*   HIERARCHYREQUESTERR\n\nRaised if this node is of a type that does not allow children of the type of the\nnewChild node, or it the node to put in is one of this node's ancestors.\n\n*   WRONGDOCUMENTERR\n\nRaised if newChild was created from a different document than the one that created this\nnode.\n\n*   NOMODIFICATIONALLOWEDERR\n\nRaised if this node is readonly.\n\n*   NOTFOUNDERR\n\nRaised if oldChild is not a child of this node.\n\nremoveChild (oldChild)\nRemoves the child node indicated by oldChild from the list of children, and returns it.\n\nReturn Value: The node removed.\n\nDOMExceptions:\n\n*   NOMODIFICATIONALLOWEDERR\n\nRaised if this node is readonly.\n\n*   NOTFOUNDERR\n\nRaised if oldChild is not a child of this node.\n\nappendChild (newChild)\nAdds the node newChild to the end of the list of children of this node. If the newChild is\nalready in the tree, it is first removed. If it is a DocumentFragment object, the entire\ncontents of the document fragment are moved into the child list of this node\n\nReturn Value: The node added.\n\nDOMExceptions:\n\n*   HIERARCHYREQUESTERR\n\nRaised if this node is of a type that does not allow children of the type of the\nnewChild node, or if the node to append is one of this node's ancestors.\n\n*   WRONGDOCUMENTERR\n\nRaised if newChild was created from a different document than the one that created this\nnode.\n\n*   NOMODIFICATIONALLOWEDERR\n\nRaised if this node is readonly.\n\nhasChildNodes\nThis is a convenience method to allow easy determination of whether a node has any children.\n\nReturn Value: 1 if the node has any children, 0 otherwise.\n\ncloneNode (deep)\nReturns a duplicate of this node, i.e., serves as a generic copy constructor for nodes. The\nduplicate node has no parent (parentNode returns undef.).\n\nCloning an Element copies all attributes and their values, including those generated by the\nXML processor to represent defaulted attributes, but this method does not copy any text it\ncontains unless it is a deep clone, since the text is contained in a child Text node.\nCloning any other type of node simply returns a copy of this node.\n\nParameters: *deep* If true, recursively clone the subtree under the specified node. If\nfalse, clone only the node itself (and its attributes, if it is an Element).\n\nReturn Value: The duplicate node.\n\nnormalize\nPuts all Text nodes in the full depth of the sub-tree underneath this Element into a\n\"normal\" form where only markup (e.g., tags, comments, processing instructions, CDATA\nsections, and entity references) separates Text nodes, i.e., there are no adjacent Text\nnodes. This can be used to ensure that the DOM view of a document is the same as if it were\nsaved and re-loaded, and is useful when operations (such as XPointer lookups) that depend on\na particular document tree structure are to be used.\n\nNot In DOM Spec: In the DOM Spec this method is defined in the Element and Document class\ninterfaces only, but it doesn't hurt to have it here...\n\ngetElementsByTagName (name [, recurse])\nReturns a NodeList of all descendant elements with a given tag name, in the order in which\nthey would be encountered in a preorder traversal of the Element tree.\n\nParameters: *name* The name of the tag to match on. The special value \"*\" matches all tags.\n*recurse* Whether it should return only direct child nodes (0) or any descendant that\nmatches the tag name (1). This argument is optional and defaults to 1. It is not part of the\nDOM spec.\n\nReturn Value: A list of matching Element nodes.\n\nNOTE: this implementation does not return a \"live\" NodeList for getElementsByTagName. See\nCAVEATS.\n\nWhen this method is called in a list context, it returns a regular perl list containing the\nresult nodes. E.g.\n\n@list = $node->getElementsByTagName(\"tag\");       # returns a perl list\n$nodelist = $node->getElementsByTagName(\"tag\");   # returns a NodeList (object ref.)\nfor my $elem ($node->getElementsByTagName(\"tag\")) # iterate over the result nodes\n",
                "subsections": [
                    {
                        "name": "Additional methods not in the DOM Spec",
                        "content": "getNodeTypeName\nReturn the string describing the node type. E.g. returns \"ELEMENTNODE\" if getNodeType\nreturns ELEMENTNODE. It uses @XML::DOM::Node::NodeNames.\n\ntoString\nReturns the entire subtree as a string.\n\nprintToFile (filename)\nPrints the entire subtree to the file with the specified filename.\n\nCroaks: if the file could not be opened for writing.\n\nprintToFileHandle (handle)\nPrints the entire subtree to the file handle. E.g. to print to STDOUT:\n\n$node->printToFileHandle (\\*STDOUT);\n\nprint (obj)\nPrints the entire subtree using the object's print method. E.g to print to a FileHandle\nobject:\n\n$f = new FileHandle (\"file.out\", \"w\");\n$node->print ($f);\n\ngetChildIndex (child)\nReturns the index of the child node in the list returned by getChildNodes.\n\nReturn Value: the index or -1 if the node is not found.\n\ngetChildAtIndex (index)\nReturns the child node at the specified index or undef.\n\naddText (text)\nAppends the specified string to the last child if it is a Text node, or else appends a new\nText node (with the specified text.)\n\nReturn Value: the last child if it was a Text node or else the new Text node.\n\ndispose\nRemoves all circular references in this node and its descendants so the objects can be\nclaimed for garbage collection. The objects should not be used afterwards.\n\nsetOwnerDocument (doc)\nSets the ownerDocument property of this node and all its children (and attributes etc.) to\nthe specified document. This allows the user to cut and paste document subtrees between\ndifferent XML::DOM::Documents. The node should be removed from the original document first,\nbefore calling setOwnerDocument.\n\nThis method does nothing when called on a Document node.\n\nisAncestor (parent)\nReturns 1 if parent is an ancestor of this node or if it is this node itself.\n\nexpandEntityRefs (str)\nExpands all the entity references in the string and returns the result. The entity\nreferences can be character references (e.g. \"{\" or \"&#x1fc2\"), default entity\nreferences (\""\", \">\", \"<\", \"'\" and \"&\") or entity references defined in\nEntity objects as part of the DocumentType of the owning Document. Character references are\nexpanded into UTF-8. Parameter entity references (e.g. %ent;) are not expanded.\n\ntosax ( %HANDLERS )\nE.g.\n\n$node->tosax (DocumentHandler => $myhandler,\nHandler => $handler2 );\n\n%HANDLERS may contain the following handlers:\n\n*   DocumentHandler\n\n*   DTDHandler\n\n*   EntityResolver\n\n*   Handler\n\nDefault handler when one of the above is not specified\n\nEach XML::DOM::Node generates the appropriate SAX callbacks (for the appropriate SAX\nhandler.) Different SAX handlers can be plugged in to accomplish different things, e.g.\nXML::Checker would check the node (currently only Document and Element nodes are supported),\nXML::Handler::BuildDOM would create a new DOM subtree (thereby, in essence, copying the\nNode) and in the near future, XML::Writer could print the node. All Perl SAX related work is\nstill in flux, so this interface may change a little.\n\nSee PerlSAX for the description of the SAX interface.\n\ncheck ( [$checker] )\nSee descriptions for check() in XML::DOM::Document and XML::DOM::Element.\n\nxql ( @XQLOPTIONS )\nTo use the xql method, you must first *use* XML::XQL and XML::XQL::DOM. This method is\nbasically a shortcut for:\n\n$query = new XML::XQL::Query ( @XQLOPTIONS );\nreturn $query->solve ($node);\n\nIf the first parameter in @XQLOPTIONS is the XQL expression, you can leave off the 'Expr'\nkeyword, so:\n\n$node->xql (\"doc//elem1[@attr]\", @otheroptions);\n\nis identical to:\n\n$node->xql (Expr => \"doc//elem1[@attr]\", @otheroptions);\n\nSee XML::XQL::Query for other available XQLOPTIONS. See XML::XQL and XML::XQL::Tutorial for\nmore info.\n\nisHidden ()\nWhether the node is hidden. See Hidden Nodes for details.\n"
                    }
                ]
            }
        }
    }
}