{
    "content": [
        {
            "type": "text",
            "text": "# XML::LibXML::DOM (perldoc)\n\n## NAME\n\nXML::LibXML::DOM - XML::LibXML DOM Implementation\n\n## DESCRIPTION\n\nXML::LibXML provides a lightweight interface to *modify* a node of the document tree generated\nby the XML::LibXML parser. This interface follows as far as possible the DOM Level 3\nspecification. In addition to the specified functions, XML::LibXML supports some functions that\nare more handy to use in the perl environment.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION** (4 subsections)\n- **AUTHORS**\n- **VERSION**\n- **COPYRIGHT**\n- **LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "XML::LibXML::DOM",
        "section": "",
        "mode": "perldoc",
        "summary": "XML::LibXML::DOM - XML::LibXML DOM Implementation",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 31,
                "subsections": [
                    {
                        "name": "Encodings and XML::LibXML's DOM implementation",
                        "lines": 2
                    },
                    {
                        "name": "Namespaces and XML::LibXML's DOM implementation",
                        "lines": 31
                    },
                    {
                        "name": "createAttributeNS",
                        "lines": 23
                    },
                    {
                        "name": "setNamespaceDeclURI",
                        "lines": 7
                    }
                ]
            },
            {
                "name": "AUTHORS",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "VERSION",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "LICENSE",
                "lines": 3,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "XML::LibXML::DOM - XML::LibXML DOM Implementation\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "XML::LibXML provides a lightweight interface to *modify* a node of the document tree generated\nby the XML::LibXML parser. This interface follows as far as possible the DOM Level 3\nspecification. In addition to the specified functions, XML::LibXML supports some functions that\nare more handy to use in the perl environment.\n\nOne also has to remember, that XML::LibXML is an interface to libxml2 nodes which actually\nreside on the C-Level of XML::LibXML. This means each node is a reference to a structure which\nis different from a perl hash or array. The only way to access these structures' values is\nthrough the DOM interface provided by XML::LibXML. This also means, that one *can't* simply\ninherit an XML::LibXML node and add new member variables as if they were hash keys.\n\nThe DOM interface of XML::LibXML does not intend to implement a full DOM interface as it is done\nby XML::GDOME and used for full featured application. Moreover, it offers an simple way to build\nor modify documents that are created by XML::LibXML's parser.\n\nAnother target of the XML::LibXML interface is to make the interfaces of libxml2 available to\nthe perl community. This includes also some workarounds to some features where libxml2 assumes\nmore control over the C-Level that most perl users don't have.\n\nOne of the most important parts of the XML::LibXML DOM interface is that the interfaces try to\nfollow the DOM Level 3 specification (<http://www.w3.org/TR/DOM-Level-3-Core/>) rather strictly.\nThis means the interface functions are named as the DOM specification says and not what\nwidespread Java interfaces claim to be the standard. Although there are several functions that\nhave only a singular interface that conforms to the DOM spec XML::LibXML provides an additional\nJava style alias interface.\n\nMoreover, there are some function interfaces left over from early stages of XML::LibXML for\ncompatibility reasons. These interfaces are for compatibility reasons *only*. They might\ndisappear in one of the future versions of XML::LibXML, so a user is requested to switch over to\nthe official functions.\n",
                "subsections": [
                    {
                        "name": "Encodings and XML::LibXML's DOM implementation",
                        "content": "See the section on Encodings in the *XML::LibXML* manual page.\n"
                    },
                    {
                        "name": "Namespaces and XML::LibXML's DOM implementation",
                        "content": "XML::LibXML's DOM implementation is limited by the DOM implementation of libxml2 which treats\nnamespaces slightly differently than required by the DOM Level 2 specification.\n\nAccording to the DOM Level 2 specification, namespaces of elements and attributes should be\npersistent, and nodes should be permanently bound to namespace URIs as they get created; it\nshould be possible to manipulate the special attributes used for declaring XML namespaces just\nas other attributes without affecting the namespaces of other nodes. In DOM Level 2, the\napplication is responsible for creating the special attributes consistently and/or for correct\nserialization of the document.\n\nThis is both inconvenient, causes problems in serialization of DOM to XML, and most importantly,\nseems almost impossible to implement over libxml2.\n\nIn libxml2, namespace URI and prefix of a node is provided by a pointer to a namespace\ndeclaration (appearing as a special xmlns attribute in the XML document). If the prefix or\nnamespace URI of the declaration changes, the prefix and namespace URI of all nodes that point\nto it changes as well. Moreover, in contrast to DOM, a node (element or attribute) can only be\nbound to a namespace URI if there is some namespace declaration in the document to point to.\n\nTherefore current DOM implementation in XML::LibXML tries to treat namespace declarations in a\ncompromise between reason, common sense, limitations of libxml2, and the DOM Level 2\nspecification.\n\nIn XML::LibXML, special attributes declaring XML namespaces are often created automatically,\nusually when a namespaced node is attached to a document and no existing declaration of the\nnamespace and prefix is in the scope to be reused. In this respect, XML::LibXML DOM\nimplementation differs from the DOM Level 2 specification according to which special attributes\nfor declaring the appropriate XML namespaces should not be added when a node with a namespace\nprefix and namespace URI is created.\n\nNamespace declarations are also created when XML::LibXML::Document's createElementNS() or"
                    },
                    {
                        "name": "createAttributeNS",
                        "content": "documentElement, the namespace will be locally declared for the newly created node. In case of\nAttributes this may look a bit confusing, since these nodes cannot have namespace declarations\nitself. In this case the namespace is internally applied to the attribute and later declared on\nthe node the attribute is appended to (if required).\n\nThe following example may explain this a bit:\n\nmy $doc = XML::LibXML->createDocument;\nmy $root = $doc->createElementNS( \"\", \"foo\" );\n$doc->setDocumentElement( $root );\n\nmy $attr = $doc->createAttributeNS( \"bar\", \"bar:foo\", \"test\" );\n$root->setAttributeNodeNS( $attr );\n\nThis piece of code will result in the following document:\n\n<?xml version=\"1.0\"?>\n<foo xmlns:bar=\"bar\" bar:foo=\"test\"/>\n\nThe namespace is declared on the document element during the setAttributeNodeNS() call.\n\nNamespaces can be also declared explicitly by the use of XML::LibXML::Element's setNamespace()\nfunction. Since 1.61, they can also be manipulated with functions setNamespaceDeclPrefix() and"
                    },
                    {
                        "name": "setNamespaceDeclURI",
                        "content": "declaration affects the namespace URI and prefix of all nodes which point to it (that is the\nnodes in its scope).\n\nIt is also important to repeat the specification: While working with namespaces you should use\nthe namespace aware functions instead of the simplified versions. For example you should *never*\nuse setAttribute() but setAttributeNS().\n"
                    }
                ]
            },
            "AUTHORS": {
                "content": "Matt Sergeant, Christian Glahn, Petr Pajas\n",
                "subsections": []
            },
            "VERSION": {
                "content": "2.0134\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "2001-2007, AxKit.com Ltd.\n\n2002-2006, Christian Glahn.\n\n2006-2009, Petr Pajas.\n",
                "subsections": []
            },
            "LICENSE": {
                "content": "This program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
                "subsections": []
            }
        }
    }
}