home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-perl-addon-1.4.9-installer.exe / Document.pod < prev    next >
Encoding:
Text File  |  2002-06-15  |  5.7 KB  |  221 lines
  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
  221.