diff -r 7c11c3d8d025 -r 60be34e1b006 deprecated/buildtools/buildsystemtools/lib/XML/DOM/Document.pod --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/deprecated/buildtools/buildsystemtools/lib/XML/DOM/Document.pod Wed Oct 27 16:03:51 2010 +0800 @@ -0,0 +1,220 @@ +=head1 NAME + +XML::DOM::Document - An XML document node in XML::DOM + +=head1 DESCRIPTION + +XML::DOM::Document extends L. + +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: This implementation allows editing the doctype. +See I 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: The DOM Spec does not allow passing the value or the +specified property in this method. In this implementation they are optional. + +Parameters: + I The attribute's value. See Attr::setValue for details. + If the value is not supplied, the specified property is set to 0. + I 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 The target part of the processing instruction. + I 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: 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 The element tagName. + I 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 to validate the document. +If no XML::Checker is supplied, a new XML::Checker is created. +See L 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 whenever the DOCTYPE section of the document +is altered! + +=back