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