{ "content": [ { "type": "text", "text": "# XML::DOM (perldoc)\n\n## NAME\n\nXML::DOM - A perl module for building DOM Level 1 compliant document structures\n\n## SYNOPSIS\n\nuse XML::DOM;\nmy $parser = new XML::DOM::Parser;\nmy $doc = $parser->parsefile (\"file.xml\");\n# print all HREF attributes of all CODEBASE elements\nmy $nodes = $doc->getElementsByTagName (\"CODEBASE\");\nmy $n = $nodes->getLength;\nfor (my $i = 0; $i < $n; $i++)\n{\nmy $node = $nodes->item ($i);\nmy $href = $node->getAttributeNode (\"HREF\");\nprint $href->getValue . \"\\n\";\n}\n# Print doc file\n$doc->printToFile (\"out.xml\");\n# Print to string\nprint $doc->toString;\n# Avoid memory leaks - cleanup circular references for garbage collection\n$doc->dispose;\n\n## DESCRIPTION\n\nThis module extends the XML::Parser module by Clark Cooper. The XML::Parser module is built on\ntop of XML::Parser::Expat, which is a lower level interface to James Clark's expat library.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (1 subsections)\n- **IMPLEMENTATION DETAILS**\n- **SEE ALSO**\n- **CAVEATS**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "XML::DOM", "section": "", "mode": "perldoc", "summary": "XML::DOM - A perl module for building DOM Level 1 compliant document structures", "synopsis": "use XML::DOM;\nmy $parser = new XML::DOM::Parser;\nmy $doc = $parser->parsefile (\"file.xml\");\n# print all HREF attributes of all CODEBASE elements\nmy $nodes = $doc->getElementsByTagName (\"CODEBASE\");\nmy $n = $nodes->getLength;\nfor (my $i = 0; $i < $n; $i++)\n{\nmy $node = $nodes->item ($i);\nmy $href = $node->getAttributeNode (\"HREF\");\nprint $href->getValue . \"\\n\";\n}\n# Print doc file\n$doc->printToFile (\"out.xml\");\n# Print to string\nprint $doc->toString;\n# Avoid memory leaks - cleanup circular references for garbage collection\n$doc->dispose;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 25, "subsections": [] }, { "name": "DESCRIPTION", "lines": 132, "subsections": [ { "name": "Global Variables", "lines": 82 } ] }, { "name": "IMPLEMENTATION DETAILS", "lines": 66, "subsections": [] }, { "name": "SEE ALSO", "lines": 18, "subsections": [] }, { "name": "CAVEATS", "lines": 5, "subsections": [] }, { "name": "AUTHOR", "lines": 9, "subsections": [] } ], "sections": { "NAME": { "content": "XML::DOM - A perl module for building DOM Level 1 compliant document structures\n", "subsections": [] }, "SYNOPSIS": { "content": "use XML::DOM;\n\nmy $parser = new XML::DOM::Parser;\nmy $doc = $parser->parsefile (\"file.xml\");\n\n# print all HREF attributes of all CODEBASE elements\nmy $nodes = $doc->getElementsByTagName (\"CODEBASE\");\nmy $n = $nodes->getLength;\n\nfor (my $i = 0; $i < $n; $i++)\n{\nmy $node = $nodes->item ($i);\nmy $href = $node->getAttributeNode (\"HREF\");\nprint $href->getValue . \"\\n\";\n}\n\n# Print doc file\n$doc->printToFile (\"out.xml\");\n\n# Print to string\nprint $doc->toString;\n\n# Avoid memory leaks - cleanup circular references for garbage collection\n$doc->dispose;\n", "subsections": [] }, "DESCRIPTION": { "content": "This module extends the XML::Parser module by Clark Cooper. The XML::Parser module is built on\ntop of XML::Parser::Expat, which is a lower level interface to James Clark's expat library.\n\nXML::DOM::Parser is derived from XML::Parser. It parses XML strings or files and builds a data\nstructure that conforms to the API of the Document Object Model as described at\nhttp://www.w3.org/TR/REC-DOM-Level-1. See the XML::Parser manpage for other available features\nof the XML::DOM::Parser class. Note that the 'Style' property should not be used (it is set\ninternally.)\n\nThe XML::Parser *NoExpand* option is more or less supported, in that it will generate\nEntityReference objects whenever an entity reference is encountered in character data. I'm not\nsure how useful this is. Any comments are welcome.\n\nAs described in the synopsis, when you create an XML::DOM::Parser object, the parse and\nparsefile methods create an *XML::DOM::Document* object from the specified input. This Document\nobject can then be examined, modified and written back out to a file or converted to a string.\n\nWhen using XML::DOM with XML::Parser version 2.19 and up, setting the XML::DOM::Parser option\n*KeepCDATA* to 1 will store CDATASections in CDATASection nodes, instead of converting them to\nText nodes. Subsequent CDATASection nodes will be merged into one. Let me know if this is a\nproblem.\n\nWhen using XML::Parser 2.27 and above, you can suppress expansion of parameter entity references\n(e.g. %pent;) in the DTD, by setting *ParseParamEnt* to 1 and *ExpandParamEnt* to 0. See Hidden\nNodes for details.\n\nA Document has a tree structure consisting of *Node* objects. A Node may contain other nodes,\ndepending on its type. A Document may have Element, Text, Comment, and CDATASection nodes.\nElement nodes may have Attr, Element, Text, Comment, and CDATASection nodes. The other nodes may\nnot have any child nodes.\n\nThis module adds several node types that are not part of the DOM spec (yet.) These are:\nElementDecl (for declarations), AttlistDecl (for declarations),\nXMLDecl (for declarations) and AttDef (for attribute definitions in an AttlistDecl.)\n\nXML::DOM Classes\nThe XML::DOM module stores XML documents in a tree structure with a root node of type\nXML::DOM::Document. Different nodes in tree represent different parts of the XML file. The DOM\nLevel 1 Specification defines the following node types:\n\n* XML::DOM::Node - Super class of all node types\n\n* XML::DOM::Document - The root of the XML document\n\n* XML::DOM::DocumentType - Describes the document structure: \n\n* XML::DOM::Element - An XML element: ... \n\n* XML::DOM::Attr - An XML element attribute: name=\"value\"\n\n* XML::DOM::CharacterData - Super class of Text, Comment and CDATASection\n\n* XML::DOM::Text - Text in an XML element\n\n* XML::DOM::CDATASection - Escaped block of text: \n\n* XML::DOM::Comment - An XML comment: \n\n* XML::DOM::EntityReference - Refers to an ENTITY: &ent; or %ent;\n\n* XML::DOM::Entity - An ENTITY definition: \n\n* XML::DOM::ProcessingInstruction - \n\n* XML::DOM::DocumentFragment - Lightweight node for cut & paste\n\n* XML::DOM::Notation - An NOTATION definition: \n\nIn addition, the XML::DOM module contains the following nodes that are not part of the DOM Level\n1 Specification:\n\n* XML::DOM::ElementDecl - Defines an element: \n\n* XML::DOM::AttlistDecl - Defines one or more attributes in an \n\n* XML::DOM::AttDef - Defines one attribute in an \n\n* XML::DOM::XMLDecl - An XML declaration: \n\nOther classes that are part of the DOM Level 1 Spec:\n\n* XML::DOM::Implementation - Provides information about this implementation. Currently it\ndoesn't do much.\n\n* XML::DOM::NodeList - Used internally to store a node's child nodes. Also returned by\ngetElementsByTagName.\n\n* XML::DOM::NamedNodeMap - Used internally to store an element's attributes.\n\nOther classes that are not part of the DOM Level 1 Spec:\n\n* XML::DOM::Parser - An non-validating XML parser that creates XML::DOM::Documents\n\n* XML::DOM::ValParser - A validating XML parser that creates XML::DOM::Documents. It uses\nXML::Checker to check against the DocumentType (DTD)\n\n* XML::Handler::BuildDOM - A PerlSAX handler that creates XML::DOM::Documents.\n\nXML::DOM package\nConstant definitions\nThe following predefined constants indicate which type of node it is.\n\nUNKNOWNNODE (0) The node type is unknown (not part of DOM)\n\nELEMENTNODE (1) The node is an Element.\nATTRIBUTENODE (2) The node is an Attr.\nTEXTNODE (3) The node is a Text node.\nCDATASECTIONNODE (4) The node is a CDATASection.\nENTITYREFERENCENODE (5) The node is an EntityReference.\nENTITYNODE (6) The node is an Entity.\nPROCESSINGINSTRUCTIONNODE (7) The node is a ProcessingInstruction.\nCOMMENTNODE (8) The node is a Comment.\nDOCUMENTNODE (9) The node is a Document.\nDOCUMENTTYPENODE (10) The node is a DocumentType.\nDOCUMENTFRAGMENTNODE (11) The node is a DocumentFragment.\nNOTATIONNODE (12) The node is a Notation.\n\nELEMENTDECLNODE (13) The node is an ElementDecl (not part of DOM)\nATTDEFNODE (14) The node is an AttDef (not part of DOM)\nXMLDECLNODE (15) The node is an XMLDecl (not part of DOM)\nATTLISTDECLNODE (16) The node is an AttlistDecl (not part of DOM)\n\nUsage:\n\nif ($node->getNodeType == ELEMENTNODE)\n{\nprint \"It's an Element\";\n}\n\nNot In DOM Spec: The DOM Spec does not mention UNKNOWNNODE and, quite frankly, you should never\nencounter it. The last 4 node types were added to support the 4 added node classes.\n", "subsections": [ { "name": "Global Variables", "content": "$VERSION\nThe variable $XML::DOM::VERSION contains the version number of this implementation, e.g.\n\"1.43\".\n\nMETHODS\nThese methods are not part of the DOM Level 1 Specification.\n\ngetIgnoreReadOnly and ignoreReadOnly (readOnly)\nThe DOM Level 1 Spec does not allow you to edit certain sections of the document, e.g. the\nDocumentType, so by default this implementation throws DOMExceptions (i.e.\nNOMODIFICATIONALLOWEDERR) when you try to edit a readonly node. These readonly checks can\nbe disabled by (temporarily) setting the global IgnoreReadOnly flag.\n\nThe ignoreReadOnly method sets the global IgnoreReadOnly flag and returns its previous\nvalue. The getIgnoreReadOnly method simply returns its current value.\n\nmy $oldIgnore = XML::DOM::ignoreReadOnly (1);\neval {\n... do whatever you want, catching any other exceptions ...\n};\nXML::DOM::ignoreReadOnly ($oldIgnore); # restore previous value\n\nAnother way to do it, using a local variable:\n\n{ # start new scope\nlocal $XML::DOM::IgnoreReadOnly = 1;\n... do whatever you want, don't worry about exceptions ...\n} # end of scope ($IgnoreReadOnly is set back to its previous value)\n\nisValidName (name)\nWhether the specified name is a valid \"Name\" as specified in the XML spec. Characters with\nUnicode values > 127 are now also supported.\n\ngetAllowReservedNames and allowReservedNames (boolean)\nThe first method returns whether reserved names are allowed. The second takes a boolean\nargument and sets whether reserved names are allowed. The initial value is 1 (i.e. allow\nreserved names.)\n\nThe XML spec states that \"Names\" starting with (X|x)(M|m)(L|l) are reserved for future use.\n(Amusingly enough, the XML version of the XML spec (REC-xml-19980210.xml) breaks that very\nrule by defining an ENTITY with the name 'xmlpio'.) A \"Name\" in this context means the Name\ntoken as found in the BNF rules in the XML spec.\n\nXML::DOM only checks for errors when you modify the DOM tree, not when the DOM tree is built\nby the XML::DOM::Parser.\n\nsetTagCompression (funcref)\nThere are 3 possible styles for printing empty Element tags:\n\nStyle 0\n or \n\nXML::DOM uses this style by default for all Elements.\n\nStyle 1\n or \n\nStyle 2\n or \n\nThis style is sometimes desired when using XHTML. (Note the extra space before the slash\n\"/\") See Appendix C for more details.\n\nBy default XML::DOM compresses all empty Element tags (style 0.) You can control which style\nis used for a particular Element by calling XML::DOM::setTagCompression with a reference to\na function that takes 2 arguments. The first is the tag name of the Element, the second is\nthe XML::DOM::Element that is being printed. The function should return 0, 1 or 2 to\nindicate which style should be used to print the empty tag. E.g.\n\nXML::DOM::setTagCompression (\\&mytagcompression);\n\nsub mytagcompression\n{\nmy ($tag, $elem) = @;\n\n# Print empty br, hr and img tags like this:
\nreturn 2 if $tag =~ /^(br|hr|img)$/;\n\n# Print other empty tags like this: \nreturn 1;\n}\n" } ] }, "IMPLEMENTATION DETAILS": { "content": "* Perl Mappings\n\nThe value undef was used when the DOM Spec said null.\n\nThe DOM Spec says: Applications must encode DOMString using UTF-16 (defined in Appendix C.3\nof [UNICODE] and Amendment 1 of [ISO-10646]). In this implementation we use plain old Perl\nstrings encoded in UTF-8 instead of UTF-16.\n\n* Text and CDATASection nodes\n\nThe Expat parser expands EntityReferences and CDataSection sections to raw strings and does\nnot indicate where it was found. This implementation does therefore convert both to Text\nnodes at parse time. CDATASection and EntityReference nodes that are added to an existing\nDocument (by the user) will be preserved.\n\nAlso, subsequent Text nodes are always merged at parse time. Text nodes that are added later\ncan be merged with the normalize method. Consider using the addText method when adding Text\nnodes.\n\n* Printing and toString\n\nWhen printing (and converting an XML Document to a string) the strings have to encoded\ndifferently depending on where they occur. E.g. in a CDATASection all substrings are allowed\nexcept for \"]]>\". In regular text, certain characters are not allowed, e.g. \">\" has to be\nconverted to \">\". These routines should be verified by someone who knows the details.\n\n* Quotes\n\nCertain sections in XML are quoted, like attribute values in an Element. XML::Parser strips\nthese quotes and the print methods in this implementation always uses double quotes, so when\nparsing and printing a document, single quotes may be converted to double quotes. The\ndefault value of an attribute definition (AttDef) in an AttlistDecl, however, will maintain\nits quotes.\n\n* AttlistDecl\n\nAttribute declarations for a certain Element are always merged into a single AttlistDecl\nobject.\n\n* Comments\n\nComments in the DOCTYPE section are not kept in the right place. They will become child\nnodes of the Document.\n\n* Hidden Nodes\n\nPrevious versions of XML::DOM would expand parameter entity references (like %pent;), so\nwhen printing the DTD, it would print the contents of the external entity, instead of the\nparameter entity reference. With this release (1.27), you can prevent this by setting the\nXML::DOM::Parser options ParseParamEnt => 1 and ExpandParamEnt => 0.\n\nWhen it is parsing the contents of the external entities, it *DOES* still add the nodes to\nthe DocumentType, but it marks these nodes by setting the 'Hidden' property. In addition, it\nadds an EntityReference node to the DocumentType node.\n\nWhen printing the DocumentType node (or when using toexpat() or tosax()), the 'Hidden'\nnodes are suppressed, so you will see the parameter entity reference instead of the contents\nof the external entities. See test case t/domextent.t for an example.\n\nThe reason for adding the 'Hidden' nodes to the DocumentType node, is that the nodes may\ncontain definitions that are referenced further in the document. (Simply not\nadding the nodes to the DocumentType could cause such entity references to be expanded\nincorrectly.)\n\nNote that you need XML::Parser 2.27 or higher for this to work correctly.\n", "subsections": [] }, "SEE ALSO": { "content": "XML::DOM::XPath\n\nThe Japanese version of this document by Takanori Kawai (Hippo2000) at\n\n\nThe DOM Level 1 specification at \n\nThe XML spec (Extensible Markup Language 1.0) at \n\nThe XML::Parser and XML::Parser::Expat manual pages.\n\nXML::LibXML also provides a DOM Parser, and is significantly faster than XML::DOM, and is under\nactive development. It requires that you download the Gnome libxml library.\n\nXML::GDOME will provide the DOM Level 2 Core API, and should be as fast as XML::LibXML, but more\nrobust, since it uses the memory management functions of libgdome. For more details see\n\n", "subsections": [] }, "CAVEATS": { "content": "The method getElementsByTagName() does not return a \"live\" NodeList. Whether this is an actual\ncaveat is debatable, but a few people on the www-dom mailing list seemed to think so. I haven't\ndecided yet. It's a pain to implement, it slows things down and the benefits seem marginal. Let\nme know what you think.\n", "subsections": [] }, "AUTHOR": { "content": "Enno Derksen is the original author.\n\nSend patches to T.J. Mather at .\n\nPaid support is available from directly from the maintainers of this package. Please see\n for more details.\n\nThanks to Clark Cooper for his help with the initial version.\n", "subsections": [] } } } }