TclDOM(n) TclDOM(n)
__________________________________________________________________________________________________________________________________________________
NAME
::dom::DOMImplementation - Tcl language binding for the W3C Document Object Model
SYNOPSIS
package require dom
dom2.5
::dom::dom::tcl::dom::libxml2
::dom::DOMImplementation method ? args ... ?
::dom::create element
::dom::parse xml ? option value ... ?
::dom::serialize token ? option value ... ?
::dom::document method token ? args ... ?
::dom::node method token ? args ... ?
::dom::element method token ? args ... ?
::dom::event method token ? args ... ?
::dom::selectNode token xpath ? option value ... ?
_________________________________________________________________
DESCRIPTION
TclDOM is a Tcl language binding for the (DOM). DOM provides a view of a XML (or HTML) document as a tree structure. Currently, TclDOM
only supports XML documents.
The package implements most of the DOM Level 1 interfaces and also some Level 2 and Level 3 interfaces. There are also a number of non-
standard commands and methods provided for the convenience of application developers (these are documented).
The DOM specification should be read in conjunction with this reference manual, as it explains the meaning and purpose of the various
interfaces. This manual is not a tutorial on how to use the DOM.
TclDOM also provides several implementations of the API, with a layered architecture. A generic layer provides a stable API to the appli-
cation, and specific implementations may register themselves. Currently, three implementations exists: a pure-Tcl implementation, a C
implementation (based on TclDOMPro) and another C implementation based on the Gnome libxml2 & gdome2 libraries.
PACKAGES AND NAMESPACES
The TclDOM generic layer defines the package and also a Tcl namespace using that name. The generic layer also uses the package name .
Implementations define their own package name and Tcl namespace within the generic layer:
Tcl implementation
Package , Tcl namespace ::dom::tcl.
TclDOMPro
Package , Tcl namespace ::dom::c.
libxml2
Package , Tcl namespace ::dom::libxml2.
TOKENS
The TclDOM API uses as identifiers for nodes within the document tree. This technique has been used to allow alternate implementations of
TclDOM to be efficient, while retaining compatibility with the pure-Tcl implementation.
The format of the token itself as well as the data structure referred to by the token are public and an application should not rely on
these. Instead, an application should use the accessor methods provided by the API.
DOM INTERFACES
Each in the DOM specification is implemented with a Tcl command in the dom namespace. A few interfaces have not been mapped to Tcl com-
mands because Tcl already provides the required functionality, for example the interface.
s for interfaces are methods (subcommands) of the corresponding Tcl command.
Each of an interface is a configuration option for an object in the document tree.
CONVENIENCE COMMANDS AND METHODS
DOM doesn't always provide an interface, method or attribute for every function required. For example, until DOM Level 3 for was no stan-
dard for creating, parsing and serializing a document. Sometimes using the standard DOM interface is awkward. TclDOM provides a number of
non-standard features to overcome these problems.
A major convenience is that each method of the interface is also defined as a command. For example, rather than using dom::DOMImplementa-
tion create to create a new document, the shorter command dom::create may be used.
Implementations may also provide direct access to specific features. Refer to the documentation for a DOM implementation.
COMMANDS
::dom::DOMImplementation
The ::dom::DOMImplementation command implements the DOM interface. It is used to provide implementation-specific features not explicitly
defined in the DOM specification.
Command Options
The following command options may be used. These are also available as commands.
hasFeature hasFeature feature
Provides a test for existence of a feature. Returns if a feature is implemented, otherwise. Uses the default DOM imple-
mentation.
create create type
Creates the root node of a new DOM document, using the default DOM implementation. The document element type may be speci-
fied as an argument, in which case that element is created. The return value is a token referring to the root node of the
newly created document.
createDocument createDocument nsURI type doctype
Creates the root node of a new DOM document, using the default DOM implementation. The document element namespace URI and
local-name (element type) may be specified as an argument, in which case that element is created. If the document type is
given then the newly created document is configured to use that document type. The return value is a token referring to the
root node of the newly created document.
createDocumentType createDocumentType token name publicid systemid internaldtd
Creates a Document Type Declaration, using the default DOM implementation. The return value is a token for the newly created
document type declaration.
createNode createNode token xpath
May create a node in the document. token specifies a context for the XPath expression given by xpath. The expression must
resolve to a node. If the node exists then no further action is taken. Otherwise the node is created. The token of the
matched or newly created node is returned.
destroy destroy token
This method frees all data structures associated with a DOM node. The token argument must refer to a valid token for any
node in the document tree. The node is removed from the tree before it is destroyed. If the node has children, they will
also be destroyed.
isNode isNode token
Tests whether the given token is a valid token for some DOM node in the default DOM implementation.
parse parse xml ? option value?
This method parses XML formatted text given by the xml argument and constructs a DOM tree for the document. The return
result is the token of the root node of the newly created document.
This method requires an event-based XML parser to be loaded to perform the parsing operation. The package itself does not
include an XML parser. Support for the use of is provided. Any other Tcl event-based XML parser implementing the TclXML
API may also be used. The -parser may be used to specify which XML parser to use.
In some circumstances, a DOM implementation may parse the XML document directly, for example libxml2. In this case, it may
not be possible to interpose on the parsing operation.
Valid configuration options are:
-parser ? {} expat tcl?
This option specifies which XML parser to use to parse the XML data. If an empty string is given then the default be-
haviour described above is used. The value expat specifies that the Expat parser must be used. The value tcl spec-
ifies that the Tcl-only parser must be used. If an explicit value is given and that parser cannot be loaded then the
command will fail, despite the fact that another parser may be available.
-progresscommand script
This option specifies a Tcl command to be invoked from time to time while the DOM tree is being constructed. The
script will be invoked after a certain number of element start tags have been processed, given by the -chunksize
option.
-chunksize integer
This option specifies how many element start tags to process before invoking the script given by the -progresscommand
option.
selectNode selectNode token xpath ? option value ... ?
Resolves the XPath location path given by xpath. token is the initial context for the location path. Returns the result-
ing nodeset as a Tcl list.
The following options may be specified:
-namespaces
The value for this option is a list of prefix-URI pairs. Each of these pairs defines an XML Namespace and its prefix
for the purposes of evaluating the XPath expression. The document itself may use a different prefix for the same XML
Namespace.
This option may be repeated, in which case the lists of namespace pairs are merged and all of the XML Namespaces reg-
istered.
serialize serialize token ? option value?
This method returns the XML formatted text corresponding to the node given by token. The text is guaranteed to be a well-
formed XML document, unless the -method option specifies a non-XML output method.
Valid configuration options are:
-newline elementlist
This option specifies a list of element types for which newline characters will be added before and after the start
and end tags for those elements upon serialization.
White space is significant in XML, so the package never adds extra white spacefor purposes of "pretty-printing" the
XML source document. On some platforms, such as VMS, this can actually cause serious problems due to line length lim-
itations. This option provides the convenience of adding newlines to certain nominated element types for formatting
the source into lines.
Examples:
Suppose the following DOM document is constructed:
set doc [::dom::DOMImplementation create]
set top [::dom::document createElement $doc Root]
set node [::dom::document createElement $top First]
::dom::document createElement $node Second
::dom::document createElement $top First
Without the -newline option the serialized document would be:
::dom::DOMImplementation serialize $doc
With the -newline option the serialized document would be:
::dom::DOMImplementation serialize $doc -newline First
trim trim token
This method removes any node containing only white space from the document tree of the node given by token.
::dom::document
This command implements the Document interface in the DOM specification. The most important aspect of this command are its factory methods
for creating nodes.
The methods accepted by this command are as follows:
dom::node
This command implements generic functions for DOM nodes.
The methods accepted by this command are as follows:
dom::element
This command provides functions for element type nodes.
Valid methods for this command are as follows:
dom::processinginstruction
This command provides functions for processingInstruction type nodes.
Valid methods for this command are as follows:
dom::event
This command provides functions for event type nodes.
Valid methods for this command are as follows:
IMPLEMENTATIONS
This section documents the various implmentations of the TclDOM API.
Tcl Implementation
The Tcl implementation is provided by the package.
It is a reference implementation, and implements the TclDOM API as described above.
A DOM tree using this implementation may be created using the dom::tcl::create command.
libxml2 Implementation
The TclDOM/libxml2 implementation is a wrapper for the . It is provided by the package. It is a high-performance library, making use of
Tcl objects for fast access to tree nodes.
A DOM tree using this implementation may be created using the dom::libxml2::create command.
Notes
Tcl Built-In Commands Tcl TclDOM(n)