Parses the XML information and builds up the DOM tree in memory
providing a Tcl object command to this DOM document object.
Example:
dom parse $xml doc
$doc documentElement root
parses the XML in the variable xml, creates the DOM tree in
memory, make a reference to the document object, visible in Tcl as
a document object command, and assigns this new object name to the
variable doc. When doc gets freed, the DOM tree and the associated
Tcl command object (document and all node objects) are freed
automatically.
set document [dom parse $xml]
set root [$document documentElement]
parses the XML in the variable xml, creates the DOM tree in
memory, make a reference to the document object, visible in Tcl as
a document object command, and returns this new object name, which
is then stored in document. To free the underlying
DOM tree and the associative Tcl object commands (document + nodes
+ fragment nodes) the document object command has to be explicitly
deleted by:
$document delete
or
rename $document ""
The valid options are:
- -simple
- If -simple is specified, a simple but fast
parser is used (conforms not fully to XML recommendation). That
should double parsing and DOM generation speed. The encoding of the
data is not transformed inside the parser. The simple parser does
not respect any encoding information in the XML declaration. It
skips over the internal DTD subset and ignores any information in
it. Therefor it doesn't include defaulted attribute values into the
tree, even if the according attribute declaration is in the
internal subset. It also doesn't expand internal or external entity
references other than the predefined entities and character
references.
- -html
- If -html is specified, a fast HTML parser is
used, which tries to even parse badly formed HTML into a DOM
tree.
- -keepEmpties
- If -keepEmpties is specified, text nodes,
which contain only whitespaces, will be part of the resulting DOM
tree. In default case (-keepEmpties not given)
those empty text nodes are removed at parsing time.
- -channel <channel-ID>
- If -channel <channel-ID> is specified,
the input to be parsed is read from the specified channel. The
encoding setting of the channel (via fconfigure -encoding) is
respected, ie the data read from the channel are converted to UTF-8
according to the encoding settings, befor the data is parsed.
- -baseurl <baseURI>
- If -baseurl <baseURI> is specified, the
baseURI is used as the base URI of the document. External entities
referenced in the document are resolved relative to this base URI.
This base URI is also stored within the DOM tree.
- -feedbackAfter <#bytes>
- If -feedbackAfter <#bytes> is specified,
the tcl command ::dom::domParseFeedback is evaluated after parsing
every #bytes. If you use this option, you have to create a tcl proc
named ::dom::domParseFeedback, otherwise you will get an error.
Please notice, that the calls of ::dom::domParseFeedback are not
done exactly every #bytes, but always at the first element start
after every #bytes.
- -externalentitycommand <script>
- If -externalentitycommand <script> is
specified, the specified tcl script is called to resolve any
external entities of the document. The actual evaluated command
consists of this option followed by three arguments: the base uri,
the system identifier of the entity and the public identifier of
the entity. The base uri and the public identifier may be the empty
list. The script has to return a tcl list consisting of three
elements. The first element of this list signals, how the external
entity is returned to the processor. At the moment, the two allowed
types are "string" and "channel". The second element of the list
has to be the (absolute) base URI of the external entity to be
parsed. The third element of the list are data, either the already
read data out of the external entity as string in the case of type
"string", or the name of a tcl channel, in the case of type
"channel". Note that if the script returns a tcl channel, it will
not be closed by the processor. It must be closed separately if it
is no longer required.
- -useForeignDTD <boolean>
- If <boolean> is true and the document does not have an
external subset, the parser will call the -externalentitycommand
script with empty values for the systemId and publicID arguments.
Pleace notice, that, if the document also doesn't have an internal
subset, the -startdoctypedeclcommand and -enddoctypedeclcommand
scripts, if set, are not called. The -useForeignDTD respects
- -paramentityparsing
<always|never|notstandalone>
- The -paramentityparsing option controls, if
the parser tries to resolve the external entities (including the
external DTD subset) of the document, while building the DOM tree.
-paramentityparsing requires an argument, which
must be either "always", "never", or "notstandalone". The value
"always" means, that the parser tries to resolves (recursively) all
external entities of the XML source. This is the default, in case
-paramentityparsing is omitted. The value "never"
means, that only the given XML source is parsed and no external
entity (including the external subset) will be resolved and parsed.
The value "notstandalone" means, that all external entities will be
resolved and parsed, with the execption of documents, which
explicitly states standalone="yes" in their XML declaration.
This method creates Tcl commands, which in turn create tDOM
nodes. Tcl commands created by this command are only avaliable
inside a script given to the domNode method appendFromScript. If a command created with createNodeCmd is invoked in any other context, it will
return error. The created command commandName
replaces any existing command or procedure with that name. If the
commandName includes any namespace qualifiers, it
is created in the specified namespace.
If such command is invoked inside a script given as argument to
the domNode method appendFromScript, it creates a
new node and appends this node at the end of the child list of the
invoking element node. If the option -returnNodeCmd was given, the command returns the created
node as Tcl command. If this option was omitted, the command
returns nothing. Each command creates always the same type of node.
Which type of node is created by the command is determined by the
first argument to the createNodeCmd. The syntax of
the created command depends on the type of the node it creates.
If the first argument of the method is elementNode, the created command will create an element
node. The tag name of the created node is commandName without namespace qualifiers. The syntax of the
created command is:
elementNodeCmd ?attributeName attributeValue ...? ?script?
elementNodeCmd ?-attributeName attributeValue ...? ?script?
elementNodeCmd name_value_list script
The command syntax allows three different ways to specify the
attributes of the resulting element. These could be specified with
attributeName attributeValue argument pairs, in an
"option style" way with -attriubteName
attributeValue argument pairs (the '-' character is only
syntactical sugar and will be stripped off) or as a Tcl list with
elements interpreted as attribute name and the corresponding
attribute value. The attribute name elements in the list may have a
leading '-' character, which will be stripped off.
Every elementNodeCmd accepts an optional Tcl
script as last argument. This script is evaluated as recursive appendFromScript script with the node created by the
elementNodeCmd as parent of all nodes created by
the script.
If the first argument of the method is textNode, the command will create a text node. The syntax
of the created command is:
textNodeCmd ?-disableOutputEscaping? data
If the optional flag -disableOutputEscaping is
given, the escaping of the ampersand character (&) and the left
angle bracket (<) inside the data is disabled. You should use
this flag carefully.
If the first argument of the method is commentNode, or cdataNode, the command
will create an comment node or CDATA section node. The syntax of
the created command is:
nodeCmd data
If the first argument of the method is piNode,
the command will create a processing instruction node. The syntax
of the created command is:
piNodeCmd target data