| TclDOM(n) | TclDOM(n) |
::dom::DOMImplementation - Tcl language binding for the W3C Document Object Model
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 ... ?
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 application, 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.
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:
Package , Tcl namespace ::dom::tcl.
Package , Tcl namespace ::dom::c.
Package , Tcl namespace ::dom::libxml2.
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.
Each in the DOM specification is implemented with a Tcl command in the dom namespace. A few interfaces have not been mapped to Tcl commands 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.
DOM doesn't always provide an interface, method or attribute for every function required. For example, until DOM Level 3 for was no standard 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::DOMImplementation 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.
The ::dom::DOMImplementation command implements the DOM interface. It is used to provide implementation-specific features not explicitly defined in the DOM specification.
The following command options may be used. These are also available as commands.
Provides a test for existence of a feature. Returns if a feature is implemented, otherwise. Uses the default DOM implementation.
Creates the root node of a new DOM document, using the default DOM implementation. The document element type may be specified 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.
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.
Creates a Document Type Declaration, using the default DOM implementation. The return value is a token for the newly created document type declaration.
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.
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.
Tests whether the given token is a valid token for some DOM node in the default DOM implementation.
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:
This option specifies which XML parser to use to parse the XML data. If an empty string is given then the default behaviour described above is used. The value expat specifies that the Expat parser must be used. The value tcl specifies 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.
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.
This option specifies how many element start tags to process before invoking the script given by the -progresscommand option.
Resolves the XPath location path given by xpath. token is the initial context for the location path. Returns the resulting nodeset as a Tcl list.
The following options may be specified:
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 registered.
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:
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 limitations. 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
This method removes any node containing only white space from the document tree of the node given by token.
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:
This command implements generic functions for DOM nodes.
The methods accepted by this command are as follows:
This command provides functions for element type nodes.
Valid methods for this command are as follows:
This command provides functions for processingInstruction type nodes.
Valid methods for this command are as follows:
This command provides functions for event type nodes.
Valid methods for this command are as follows:
This section documents the various implmentations of the TclDOM API.
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.
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.
| Tcl | Tcl Built-In Commands |