1dom(n) dom(n)
2______________________________________________________________________________
6
8 dom - Create an in-memory DOM tree from XML
9
11 package require tdom
12 dom method ?arg arg ...?
14_________________________________________________________________
15
17 This command provides the creation of complete DOM trees in memory. In
18 the usual case a string containing a XML information is parsed and con‐
19 verted into a DOM tree. method indicates a specific subcommand.
20 The valid methods are:
22 dom parse ?options? ?data?
24 Parses the XML information and builds up the DOM tree in memory
25 providing a Tcl object command to this DOM document object.
26 Example:
27 dom parse $xml doc
31 $doc documentElement root
32 parses the XML in the variable xml, creates the DOM tree in mem‐
34 ory, make a reference to the document object, visible in Tcl as
35 a document object command, and assigns this new object name to
36 the variable doc. When doc gets freed, the DOM tree and the
37 associated Tcl command object (document and all node objects)
38 are freed automatically.
39 set document [dom parse $xml]
44 set root [$document documentElement]
45 parses the XML in the variable xml, creates the DOM tree in mem‐
47 ory, make a reference to the document object, visible in Tcl as
48 a document object command, and returns this new object name,
49 which is then stored in document. To free the underlying DOM
50 tree and the associative Tcl object commands (document + nodes +
51 fragment nodes) the document object command has to be explicitly
52 deleted by:
53 $document delete
58 or
60 rename $document ""
62 The valid options are:
64 -simple
66 If -simple is specified, a simple but fast parser is used
67 (conforms not fully to XML recommendation). That should
68 double parsing and DOM generation speed. The encoding of
69 the data is not transformed inside the parser. The simple
70 parser does not respect any encoding information in the
71 XML declaration. It skips over the internal DTD subset
72 and ignores any information in it. Therefor it doesn't
73 include defaulted attribute values into the tree, even if
74 the according attribute declaration is in the internal
75 subset. It also doesn't expand internal or external
76 entity references other than the predefined entities and
77 character references.
78 -html If -html is specified, a fast HTML parser is used, which
80 tries to even parse badly formed HTML into a DOM tree.
81 -keepEmpties
83 If -keepEmpties is specified, text nodes, which contain
84 only whitespaces, will be part of the resulting DOM tree.
85 In default case (-keepEmpties not given) those empty text
86 nodes are removed at parsing time.
87 -channel <channel-ID>
89 If -channel <channel-ID> is specified, the input to be
90 parsed is read from the specified channel. The encoding
91 setting of the channel (via fconfigure -encoding) is
92 respected, ie the data read from the channel are con‐
93 verted to UTF-8 according to the encoding settings, befor
94 the data is parsed.
95 -baseurl <baseURI>
97 If -baseurl <baseURI> is specified, the baseURI is used
98 as the base URI of the document. External entities refer‐
99 enced in the document are resolved relative to this base
100 URI. This base URI is also stored within the DOM tree.
101 -feedbackAfter <#bytes>
103 If -feedbackAfter <#bytes> is specified, the tcl command
104 ::dom::domParseFeedback is evaluated after parsing every
105 #bytes. If you use this option, you have to create a tcl
106 proc named ::dom::domParseFeedback, otherwise you will
107 get an error. Please notice, that the calls of
108 ::dom::domParseFeedback are not done exactly every
109 #bytes, but always at the first element start after every
110 #bytes.
111 -externalentitycommand <script>
113 If -externalentitycommand <script> is specified, the
114 specified tcl script is called to resolve any external
115 entities of the document. The actual evaluated command
116 consists of this option followed by three arguments: the
117 base uri, the system identifier of the entity and the
118 public identifier of the entity. The base uri and the
119 public identifier may be the empty list. The script has
120 to return a tcl list consisting of three elements. The
121 first element of this list signals, how the external
122 entity is returned to the processor. At the moment, the
123 two allowed types are "string" and "channel". The second
124 element of the list has to be the (absolute) base URI of
125 the external entity to be parsed. The third element of
126 the list are data, either the already read data out of
127 the external entity as string in the case of type
128 "string", or the name of a tcl channel, in the case of
129 type "channel". Note that if the script returns a tcl
130 channel, it will not be closed by the processor. It must
131 be closed separately if it is no longer required.
132 -useForeignDTD <boolean>
134 If <boolean> is true and the document does not have an
135 external subset, the parser will call the -externalenti‐
136 tycommand script with empty values for the systemId and
137 publicID arguments. Pleace notice, that, if the document
138 also doesn't have an internal subset, the -startdoctype‐
139 declcommand and -enddoctypedeclcommand scripts, if set,
140 are not called. The -useForeignDTD respects
141 -paramentityparsing <always|never|notstandalone>
143 The -paramentityparsing option controls, if the parser
144 tries to resolve the external entities (including the
145 external DTD subset) of the document, while building the
146 DOM tree. -paramentityparsing requires an argument, which
147 must be either "always", "never", or "notstandalone". The
148 value "always" means, that the parser tries to resolves
149 (recursively) all external entities of the XML source.
150 This is the default, in case -paramentityparsing is omit‐
151 ted. The value "never" means, that only the given XML
152 source is parsed and no external entity (including the
153 external subset) will be resolved and parsed. The value
154 "notstandalone" means, that all external entities will be
155 resolved and parsed, with the execption of documents,
156 which explicitly states standalone="yes" in their XML
157 declaration.
158 dom createDocument docElemName ?objVar?
160 Creates a new DOM document object with one element node with
161 node name docElemName. The objVar controls the memory handling
162 as explained above.
163 dom createDocumentNS uri docElemName ?objVar?
165 Creates a new DOM document object with one element node with
166 node name docElemName. Uri gives the namespace of the document
167 element to create. The objVar controls the memory handling as
168 explained above.
169 dom createDocumentNode ?objVar?
171 Creates a new, 'empty' DOM document object without any element
172 node. objVar controls the memory handling as explained above.
173 dom setResultEncoding ?encodingName?
175 If encodingName is not given the current global result encoding
176 is returned. Otherwise the global result encoding is set to
177 encodingName. All character data, attribute values, etc. will
178 then be converted from UTF-8, which is delivered from the Expat
179 XML parser, to the given 8 bit encoding at XML/DOM parse time.
180 Valid values for encodingName are: utf-8, ascii, cp1250, cp1251,
181 cp1252, cp1253, cp1254, cp1255, cp1256, cp437, cp850, en,
182 iso8859-1, iso8859-2, iso8859-3, iso8859-4, iso8859-5,
183 iso8859-6, iso8859-7, iso8859-8, iso8859-9, koi8-r.
184 dom createNodeCmd ?-returnNodeCmd? (element|comment|text|cdata|pi)Node
186 commandName
187 This method creates Tcl commands, which in turn create tDOM
188 nodes. Tcl commands created by this command are only avaliable
189 inside a script given to the domNode method appendFromScript. If
190 a command created with createNodeCmd is invoked in any other
191 context, it will return error. The created command commandName
192 replaces any existing command or procedure with that name. If
193 the commandName includes any namespace qualifiers, it is created
194 in the specified namespace.
195 If such command is invoked inside a script given as argument to
197 the domNode method appendFromScript, it creates a new node and
198 appends this node at the end of the child list of the invoking
199 element node. If the option -returnNodeCmd was given, the com‐
200 mand returns the created node as Tcl command. If this option was
201 omitted, the command returns nothing. Each command creates
202 always the same type of node. Which type of node is created by
203 the command is determined by the first argument to the createN‐
204 odeCmd. The syntax of the created command depends on the type of
205 the node it creates.
206 If the first argument of the method is elementNode, the created
208 command will create an element node. The tag name of the created
209 node is commandName without namespace qualifiers. The syntax of
210 the created command is:
211 elementNodeCmd ?attributeName attributeValue ...? ?script?
216 elementNodeCmd ?-attributeName attributeValue ...? ?script?
217 elementNodeCmd name_value_list script
218 The command syntax allows three different ways to specify the
221 attributes of the resulting element. These could be specified
222 with attributeName attributeValue argument pairs, in an "option
223 style" way with -attriubteName attributeValue argument pairs
224 (the '-' character is only syntactical sugar and will be
225 stripped off) or as a Tcl list with elements interpreted as
226 attribute name and the corresponding attribute value. The
227 attribute name elements in the list may have a leading '-' char‐
228 acter, which will be stripped off.
229 Every elementNodeCmd accepts an optional Tcl script as last
231 argument. This script is evaluated as recursive appendFromScript
232 script with the node created by the elementNodeCmd as parent of
233 all nodes created by the script.
234 If the first argument of the method is textNode, the command
236 will create a text node. The syntax of the created command is:
237 textNodeCmd ?-disableOutputEscaping? data
242 If the optional flag -disableOutputEscaping is given, the escap‐
245 ing of the ampersand character (&) and the left angle bracket
246 (<) inside the data is disabled. You should use this flag care‐
247 fully.
248 If the first argument of the method is commentNode, or cdataN‐
250 ode, the command will create an comment node or CDATA section
251 node. The syntax of the created command is:
252 nodeCmd data
257 If the first argument of the method is piNode, the command will
260 create a processing instruction node. The syntax of the created
261 command is:
262 piNodeCmd target data
267 dom setStoreLineColumn ?boolean?
270 If switched on, the DOM nodes will contain line and column posi‐
271 tion information for the original XML document after parsing.
272 The default is, not to store line and column position informa‐
273 tion.
274 dom setNameCheck ?boolean?
276 If NameCheck is true, every method which expects an XML Name, a
277 full qualified name or a processing instructing target will
278 check, if the given string is valid according to his production
279 rule. For commands created with the createNodeCmd method to be
280 used in the context of appendFromScript the status of the flag
281 at creation time decides. If NameCheck is true at creation time,
282 the command will check his arguments, otherwise not. The set‐
283 NameCheck set this flag. It returns the current NameCheck flag
284 state. The default state for NameCheck is true.
285 dom setTextCheck ?boolean?
287 If TextCheck is true, every command which expects XML Chars, a
288 comment, a CDATA section value or a processing instructing value
289 will check, if the given string is valid according to his pro‐
290 duction rule. For commands created with the createNodeCmd method
291 to be used in the context of appendFromScript the status of the
292 flag at creation time decides. If TextCheck is true at creation
293 time, the command will check his arguments, otherwise not.The
294 setTextCheck method set this flag. It returns the current
295 TextCheck flag state. The default state for TextCheck is true.
296 dom setObjectCommands ?(automatic|token|command)?
298 Controls, if documents and nodes are created as tcl commands or
299 as token to be used with the domNode and domDoc commands. If the
300 mode is 'automatic', then methods used at tcl commands will cre‐
301 ate tcl commands and methods used at doc or node tokes will cre‐
302 ate tokens. If the mode is 'command' then always tcl commands
303 will be created. If the mode is 'token', then always token will
304 be created. The method returns the current mode. This method is
305 an experimental interface.
306 dom isName name
308 Returns 1, if name is a valid XML Name according to production 5
309 of the XML 1.0 recommendation. This means, that name is a valid
310 XML element or attribute name. Otherwise it returns 0.
311 dom isPIName name
313 Returns 1, if name is a valid XML processing instruction target
314 according to production 17 of the XML 1.0 recommendation. Other‐
315 wise it returns 0.
316 dom isNCName name
318 Returns 1, if name is a valid NCName according to production 4
319 of the of the Namespaces in XML recommendation. Otherwise it
320 returns 0.
321 dom isQName name
323 Returns 1, if name is a valid QName according to production 6 of
324 the of the Namespaces in XML recommendation. Otherwise it
325 returns 0.
326 dom isCharData string
328 Returns 1, if every character in string is a valid XML Char
329 according to production 2 of the XML 1.0 recommendation. Other‐
330 wise it returns 0.
331 dom isComment string
333 Returns 1, if string is a valid comment according to production
334 15 of the XML 1.0 recommendation. Otherwise it returns 0.
335 dom isCDATA string
337 Returns 1, if string is valid according to production 20 of the
338 XML 1.0 recommendation. Otherwise it returns 0.
339 dom isPIValue string
341 Returns 1, if string is valid according to production 16 of the
342 XML 1.0 recommendation. Otherwise it returns 0.
343
345 XML, DOM, document, node, parsing
346Tcl dom(n)