1 =head1 NAME

     2 

     3 XML::DOM::Document - An XML document node in XML::DOM

     4 

     5 =head1 DESCRIPTION

     6 

     7 XML::DOM::Document extends L<XML::DOM::Node>.

     8 

     9 It is the main root of the XML document structure as returned by 

    10 XML::DOM::Parser::parse and XML::DOM::Parser::parsefile.

    11 

    12 Since elements, text nodes, comments, processing instructions, etc.

    13 cannot exist outside the context of a Document, the Document interface

    14 also contains the factory methods needed to create these objects. The

    15 Node objects created have a getOwnerDocument method which associates

    16 them with the Document within whose context they were created.

    17 

    18 =head2 METHODS

    19 

    20 =over 4

    21 

    22 =item getDocumentElement

    23 

    24 This is a convenience method that allows direct access to

    25 the child node that is the root Element of the document.

    26 

    27 =item getDoctype

    28 

    29 The Document Type Declaration (see DocumentType) associated

    30 with this document. For HTML documents as well as XML

    31 documents without a document type declaration this returns

    32 undef. The DOM Level 1 does not support editing the Document

    33 Type Declaration.

    34 

    35 B<Not In DOM Spec>: This implementation allows editing the doctype. 

    36 See I<XML::DOM::ignoreReadOnly> for details.

    37 

    38 =item getImplementation

    39 

    40 The DOMImplementation object that handles this document. A

    41 DOM application may use objects from multiple implementations.

    42 

    43 =item createElement (tagName)

    44 

    45 Creates an element of the type specified. Note that the

    46 instance returned implements the Element interface, so

    47 attributes can be specified directly on the returned object.

    48 

    49 DOMExceptions:

    50 

    51 =over 4

    52 

    53 =item * INVALID_CHARACTER_ERR

    54 

    55 Raised if the tagName does not conform to the XML spec.

    56 

    57 =back

    58 

    59 =item createTextNode (data)

    60 

    61 Creates a Text node given the specified string.

    62 

    63 =item createComment (data)

    64 

    65 Creates a Comment node given the specified string.

    66 

    67 =item createCDATASection (data)

    68 

    69 Creates a CDATASection node given the specified string.

    70 

    71 =item createAttribute (name [, value [, specified ]])

    72 

    73 Creates an Attr of the given name. Note that the Attr

    74 instance can then be set on an Element using the setAttribute method.

    75 

    76 B<Not In DOM Spec>: The DOM Spec does not allow passing the value or the 

    77 specified property in this method. In this implementation they are optional.

    78 

    79 Parameters:

    80  I<value>     The attribute's value. See Attr::setValue for details.

    81               If the value is not supplied, the specified property is set to 0.

    82  I<specified> Whether the attribute value was specified or whether the default

    83               value was used. If not supplied, it's assumed to be 1.

    84 

    85 DOMExceptions:

    86 

    87 =over 4

    88 

    89 =item * INVALID_CHARACTER_ERR

    90 

    91 Raised if the name does not conform to the XML spec.

    92 

    93 =back

    94 

    95 =item createProcessingInstruction (target, data)

    96 

    97 Creates a ProcessingInstruction node given the specified name and data strings.

    98 

    99 Parameters:

   100  I<target>  The target part of the processing instruction.

   101  I<data>    The data for the node.

   102 

   103 DOMExceptions:

   104 

   105 =over 4

   106 

   107 =item * INVALID_CHARACTER_ERR

   108 

   109 Raised if the target does not conform to the XML spec.

   110 

   111 =back

   112 

   113 =item createDocumentFragment

   114 

   115 Creates an empty DocumentFragment object.

   116 

   117 =item createEntityReference (name)

   118 

   119 Creates an EntityReference object.

   120 

   121 =back

   122 

   123 =head2 Additional methods not in the DOM Spec

   124 

   125 =over 4

   126 

   127 =item getXMLDecl and setXMLDecl (xmlDecl)

   128 

   129 Returns the XMLDecl for this Document or undef if none was specified.

   130 Note that XMLDecl is not part of the list of child nodes.

   131 

   132 =item setDoctype (doctype)

   133 

   134 Sets or replaces the DocumentType. 

   135 B<NOTE>: Don't use appendChild or insertBefore to set the DocumentType.

   136 Even though doctype will be part of the list of child nodes, it is handled

   137 specially.

   138 

   139 =item getDefaultAttrValue (elem, attr)

   140 

   141 Returns the default attribute value as a string or undef, if none is available.

   142 

   143 Parameters:

   144  I<elem>    The element tagName.

   145  I<attr>    The attribute name.

   146 

   147 =item getEntity (name)

   148 

   149 Returns the Entity with the specified name.

   150 

   151 =item createXMLDecl (version, encoding, standalone)

   152 

   153 Creates an XMLDecl object. All parameters may be undefined.

   154 

   155 =item createDocumentType (name, sysId, pubId)

   156 

   157 Creates a DocumentType object. SysId and pubId may be undefined.

   158 

   159 =item createNotation (name, base, sysId, pubId)

   160 

   161 Creates a new Notation object. Consider using 

   162 XML::DOM::DocumentType::addNotation!

   163 

   164 =item createEntity (parameter, notationName, value, sysId, pubId, ndata)

   165 

   166 Creates an Entity object. Consider using XML::DOM::DocumentType::addEntity!

   167 

   168 =item createElementDecl (name, model)

   169 

   170 Creates an ElementDecl object.

   171 

   172 DOMExceptions:

   173 

   174 =over 4

   175 

   176 =item * INVALID_CHARACTER_ERR

   177 

   178 Raised if the element name (tagName) does not conform to the XML spec.

   179 

   180 =back

   181 

   182 =item createAttlistDecl (name)

   183 

   184 Creates an AttlistDecl object.

   185 

   186 DOMExceptions:

   187 

   188 =over 4

   189 

   190 =item * INVALID_CHARACTER_ERR

   191 

   192 Raised if the element name (tagName) does not conform to the XML spec.

   193 

   194 =back

   195 

   196 =item expandEntity (entity [, parameter])

   197 

   198 Expands the specified entity or parameter entity (if parameter=1) and returns

   199 its value as a string, or undef if the entity does not exist.

   200 (The entity name should not contain the '%', '&' or ';' delimiters.)

   201 

   202 =item check ( [$checker] )

   203 

   204 Uses the specified L<XML::Checker> to validate the document.

   205 If no XML::Checker is supplied, a new XML::Checker is created.

   206 See L<XML::Checker> for details.

   207 

   208 =item check_sax ( [$checker] )

   209 

   210 Similar to check() except it uses the SAX interface to XML::Checker instead of 

   211 the expat interface. This method may disappear or replace check() at some time.

   212 

   213 =item createChecker ()

   214 

   215 Creates an XML::Checker based on the document's DTD.

   216 The $checker can be reused to check any elements within the document.

   217 Create a new L<XML::Checker> whenever the DOCTYPE section of the document 

   218 is altered!

   219 

   220 =back