1dom(n)                                                                  dom(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       dom - Create an in-memory DOM tree from XML
9

SYNOPSIS

11       package require tdom
12
13       dom method ?arg arg ...?
14_________________________________________________________________
15

DESCRIPTION

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
21       The valid methods are:
22
23       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
28
29
30                     dom parse $xml doc
31                     $doc documentElement root
32
33              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
40
41
42
43                     set document [dom parse $xml]
44                     set root     [$document documentElement]
45
46              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
54
55
56
57                     $document delete
58
59              or
60
61                     rename $document ""
62
63              The valid options are:
64
65              -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
79              -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
82              -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
88              -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
96              -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
102              -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
112              -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
133              -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
142              -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
159       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
164       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
170       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
174       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
185       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
196              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
207              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
212
213
214
215                     elementNodeCmd ?attributeName attributeValue ...? ?script?
216                     elementNodeCmd ?-attributeName attributeValue ...? ?script?
217                     elementNodeCmd name_value_list script
218
219
220              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
230              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
235              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
238
239
240
241                     textNodeCmd ?-disableOutputEscaping? data
242
243
244              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
249              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
253
254
255
256                     nodeCmd data
257
258
259              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
263
264
265
266                     piNodeCmd target data
267
268
269       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
275       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
286       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
297       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
307       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
312       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
317       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
322       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
327       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
332       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
336       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
340       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

KEYWORDS

345       XML, DOM, document, node, parsing
346
347
348
349Tcl                                                                     dom(n)
Impressum