Document.pod

=head1 NAME

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

=head1 DESCRIPTION

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

It is the main root of the XML document structure as returned by 
XML::DOM::Parser::parse and XML::DOM::Parser::parsefile.

Since elements, text nodes, comments, processing instructions, etc.
cannot exist outside the context of a Document, the Document interface
also contains the factory methods needed to create these objects. The
Node objects created have a getOwnerDocument method which associates
them with the Document within whose context they were created.

=head2 METHODS

=over 4

=item getDocumentElement

This is a convenience method that allows direct access to
the child node that is the root Element of the document.

=item getDoctype

The Document Type Declaration (see DocumentType) associated
with this document. For HTML documents as well as XML
documents without a document type declaration this returns
undef. The DOM Level 1 does not support editing the Document
Type Declaration.

B<Not In DOM Spec>: This implementation allows editing the doctype. 
See I<XML::DOM::ignoreReadOnly> for details.

=item getImplementation

The DOMImplementation object that handles this document. A
DOM application may use objects from multiple implementations.

=item createElement (tagName)

Creates an element of the type specified. Note that the
instance returned implements the Element interface, so
attributes can be specified directly on the returned object.

DOMExceptions:

=over 4

=item * INVALID_CHARACTER_ERR

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

=back

=item createTextNode (data)

Creates a Text node given the specified string.

=item createComment (data)

Creates a Comment node given the specified string.

=item createCDATASection (data)

Creates a CDATASection node given the specified string.

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

Creates an Attr of the given name. Note that the Attr
instance can then be set on an Element using the setAttribute method.

B<Not In DOM Spec>: The DOM Spec does not allow passing the value or the 
specified property in this method. In this implementation they are optional.

Parameters:
 I<value>     The attribute's value. See Attr::setValue for details.
              If the value is not supplied, the specified property is set to 0.
 I<specified> Whether the attribute value was specified or whether the default
              value was used. If not supplied, it's assumed to be 1.

DOMExceptions:

=over 4

=item * INVALID_CHARACTER_ERR

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

=back

=item createProcessingInstruction (target, data)

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

Parameters:
 I<target>  The target part of the processing instruction.
 I<data>    The data for the node.

DOMExceptions:

=over 4

=item * INVALID_CHARACTER_ERR

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

=back

=item createDocumentFragment

Creates an empty DocumentFragment object.

=item createEntityReference (name)

Creates an EntityReference object.

=back

=head2 Additional methods not in the DOM Spec

=over 4

=item getXMLDecl and setXMLDecl (xmlDecl)

Returns the XMLDecl for this Document or undef if none was specified.
Note that XMLDecl is not part of the list of child nodes.

=item setDoctype (doctype)

Sets or replaces the DocumentType. 
B<NOTE>: Don't use appendChild or insertBefore to set the DocumentType.
Even though doctype will be part of the list of child nodes, it is handled
specially.

=item getDefaultAttrValue (elem, attr)

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

Parameters:
 I<elem>    The element tagName.
 I<attr>    The attribute name.

=item getEntity (name)

Returns the Entity with the specified name.

=item createXMLDecl (version, encoding, standalone)

Creates an XMLDecl object. All parameters may be undefined.

=item createDocumentType (name, sysId, pubId)

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

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

Creates a new Notation object. Consider using 
XML::DOM::DocumentType::addNotation!

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

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

=item createElementDecl (name, model)

Creates an ElementDecl object.

DOMExceptions:

=over 4

=item * INVALID_CHARACTER_ERR

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

=back

=item createAttlistDecl (name)

Creates an AttlistDecl object.

DOMExceptions:

=over 4

=item * INVALID_CHARACTER_ERR

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

=back

=item expandEntity (entity [, parameter])

Expands the specified entity or parameter entity (if parameter=1) and returns
its value as a string, or undef if the entity does not exist.
(The entity name should not contain the '%', '&' or ';' delimiters.)

=item check ( [$checker] )

Uses the specified L<XML::Checker> to validate the document.
If no XML::Checker is supplied, a new XML::Checker is created.
See L<XML::Checker> for details.

=item check_sax ( [$checker] )

Similar to check() except it uses the SAX interface to XML::Checker instead of 
the expat interface. This method may disappear or replace check() at some time.

=item createChecker ()

Creates an XML::Checker based on the document's DTD.
The $checker can be reused to check any elements within the document.
Create a new L<XML::Checker> whenever the DOCTYPE section of the document 
is altered!

=back