|
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 |