TclDOM(3tcl) | TclDOM(3tcl) |
See the file "LICENSE" for information on
usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
::dom::DOMImplementation method ? args ... ?
::dom::hasfeature feature version
::dom::create
::dom::destroy token
::dom::parse xml ? option value ... ?
::dom::serialize token ? option value ...
?
::dom::document method token ? args ...
?
::dom::documenttype method token ? args
... ?
::dom::node method token ? args ... ?
::dom::element method token ? args ...
?
::dom::event method token ? args ... ?
::dom::selectNode token xpath ? option
value ... ?
::dom::isNode token
::dom::xinclude doc
::dom::prefix2namespaceURI node prefix
::dom::trim doc
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 two implementations of the API: a pure-Tcl implementation
and a C implementation based on the Gnome libxml2 library.
Implementations define their own package name and Tcl namespace within the
::dom Tcl namespace:
Each DOM Document is allocated a Tcl namespace within the ::dom Tcl
namespace. All storage for the document and commands are defined within that
Tcl namespace.
The format of the token itself as well as the data structure referred to by the
token are not public and an application should not rely on these.
Instead, an application should use the accessor methods provided by the API.
There is no requirement to always use the same token for a node. In fact, an
important performance optimisation for some implementations is to create a new
token when a node is accessed, regardless of whether a token has already been
issued for that node. This implies that in order to test whether two tokens
refer to the same node it is not sufficient to test the string values of the
tokens; the isSameNode method must be used for this purpose. For
example,
proc NodeCompare1 {A B} {
return [string equal $A $B] } proc NodeCompare2 {A B} {
return [$A isSameNode $B] }
In the above example, NodeCompare2 correctly determines whether its two
arguments refer to the same node.
methods for interfaces are methods (subcommands) of the corresponding Tcl
command.
Each attribute of an interface is a configuration option for an object in
the document tree.
A major convenience is that each method of the DOMImplementation
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.
Non-standard method. DOM Level 2 introduced the createDocument method.
Non-standard method.
When the given token refers to a DOM document then the entire document is
destroyed; the Tcl namespace for the document is deleted and all document and
node commands are deleted. All tokens for the document or nodes in the
document become invalid.
When the token refers to a node the node is removed from the tree before it is
destroyed. If the node has children or attributes, they will also be
destroyed. The Tcl command for the node is deleted.
Non-standard method.
This method uses the TclXML package to perform the parsing operation. The
dom package itself does not include an XML parser. TclXML supports the
use of multiple parser implementations. The -parser may be used to
specify which XML parser class to use.
All options not listed below are passed to the TclXML parser.
Valid configuration options are:
If no Base URI is given then relative URIs are resolved in the current context,
namely the current working directory.
The following options may be specified:
This option may be repeated, in which case the lists of namespace pairs are
merged and all of the XML Namespaces registered.
Non-standard method.
Valid configuration options are:
White space is significant in XML, so the dom package never adds extra
white space for 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
<?xml version="1.0"?> <!DOCTYPE Root>
<Root><First><Second/></First><First/></Root>
With the -newline option the serialized document would be:
::dom::DOMImplementation serialize $doc -newline First
<?xml version="1.0"?> <!DOCTYPE Root> <Root>
<First> <Second/> </First> <First/> </Root>
The methods accepted by this command are as follows:
Valid configuration options are:
This is a read-only option. Use the factory method to create a Document Type
Declaration node.
This is a read-only option. Use the factory method to create the document
element node.
The default value is implicit.
This is a read-only option.
A Tcl command is created with the same name as the new node's token. This
command is a shortcut for the ::dom::node command.
A Tcl command is created with the same name as the new node's token. This
command is a shortcut for the ::dom::node command.
A Tcl command is created with the same name as the new node's token. This
command is a shortcut for the ::dom::node command.
A Tcl command is created with the same name as the new node's token. This
command is a shortcut for the ::dom::node command.
A Tcl command is created with the same name as the new node's token. This
command is a shortcut for the ::dom::node command.
A Tcl command is created with the same name as the new node's token. This
command is a shortcut for the ::dom::node command.
A Tcl command is created with the same name as the new node's token. This
command is a shortcut for the ::dom::node command.
A Tcl command is created with the same name as the new node's token. This
command is a shortcut for the ::dom::node command.
This method is included for completeness with respect to the DOM specification.
The preferred method for setting element attributes is to use the
::dom::element command.
A Tcl command is created with the same name as the new node's token. This
command is a shortcut for the ::dom::event command.
Example:
set schema [dom::parse $XML] $schema relaxng compile set instance [dom::parse
$XML2] $schema relaxng validate $instance
If the document is changed after compiling, then schema document must be
recompiled.
Example:
set schema [dom::parse $XML] $schema schema compile set instance [dom::parse
$XML2] $schema schema validate $instance
If the document is changed after compiling, then schema document must be
recompiled.
The methods accepted by this command are as follows:
Valid configuration options are as follows:
The DOM specification gives the meaning of names for different types of nodes.
For example, the -nodeName option of an element node is the element
type.
This is not a standard DOM method for this interface.
This is not a standard DOM method for this interface.
This is not a standard DOM method for this interface.
This is not a standard DOM method for this interface.
This is not a standard DOM method for this interface.
This is not a standard DOM method for this interface.
When an event of type type occurs the script
listener is evaluated, in the global context. The token of the
event node is appended to the script.
If the listener argument is omitted then the listener for the
given event type is returned.
Valid options are:
Valid options are:
Valid methods for this command are as follows:
Valid configuration options are as follows:
This option has no effect upon output (serialization) of the XML document. Empty
element syntax is automatically used where appropriate.
Valid methods for this command are as follows:
Valid configuration options are as follows:
Valid methods for this command are as follows:
Valid configuration options are as follows:
The implementation of this method depends on the Tcl_GetTime
function.This function only became publically available in Tcl 8.4. If a
version of Tcl prior to 8.4 is being used, then this option will have the
value 0.
Invoking this method does not prevent event listeners at the current node from
being triggered.
type gives the type of the event. Any of the event types defined
by the W3C DOM Level 2 Event module may be specified, or a user-defined event
type may be used instead.
bubbles indicates whether the event will enter the bubbling phase
after the capturing phase. cancelable indicates whether the
event may be cancelled.
view gives the view for the event (not supported by TclDOM).
detail provides extra data for the event.
screenX and screenY give the coordinates at which
the event occurred relative to the screen. screenX and
screenY give the coordinates at which the event occurred relative
to the window.
ctrlKey, altKey, shiftKey,
metaKey indicate whether the respective modifier key was pressed
when the event occurred.
button indicates which button, if any, was pressed when the event
occurred.
relatedNode specifies that a DOM node is associated with the
event.
relatedNode specifies a DOM node to associate with the event.
prevValue gives the previous value of the node.
newValue gives the new value of the node. attrName
gives the name of the attribute where the event is modifying an attribute
value.
Create an event node,
Initialise the event node (using default values where required),
Dispatch the event,
Destroy the event node.
type gives the event type.
The following options are valid:
Create an event node,
Initialise the event node (using default values where required),
Dispatch the event,
Destroy the event node.
type gives the event type.
The following options are valid:
Create an event node,
Initialise the event node (using default values where required),
Dispatch the event,
Destroy the event node.
type gives the event type.
The following options are valid:
The format of the list is described in the TclXML manual page.
* Validation: DTD, XML Schema or RelaxNG validation are not supported.
* Character encodings: The TclDOM/tcl implementation itself does not handle
character encodings other than utf-8. Character encodings are handled by Tcl
itself.
* The TclXML/libxml2 parser must be used to parse an XML document. It is not
possible to use any other parser class.
* The importNode method has not been implemented.
NAME¶
TclDOM - Tcl language binding for the W3C Document Object ModelSYNOPSIS¶
package require domDESCRIPTION¶
TclDOM is a Tcl language binding for the W3C Document Object Model (DOM). DOM provides a view of a XML (or HTML) document as a tree structure. Currently, TclDOM only supports XML documents.PACKAGES AND NAMESPACES¶
TclDOM defines the dom package and also a Tcl namespace using that same name.- Tcl implementation
-
- libxml2
-
TOKENS¶
The TclDOM API uses tokens 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.return [string equal $A $B] } proc NodeCompare2 {A B} {
return [$A isSameNode $B] }
DOCUMENT AND NODE COMMANDS¶
Each Document and Node has a Tcl command defined that may be used to control the object. This command may be used to invoke the methods by the ::dom::document command (for Documents) or the ::dom::node command (for all other Nodes). If a Document' or Node's Tcl command is destroyed then the Document or Node is also destroyed.DOM INTERFACES¶
Each Interface 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 CharacterData interface.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 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.COMMANDS¶
::dom::DOMImplementation¶
The ::dom::DOMImplementation command implements the DOMImplementation 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
- create
- create type
- createDocument
- createDocument nsURI type doctype
- createDocumentType
- createDocumentType name publicid systemid internaldtd
- createNode
- createNode token xpath
- destroy
- destroy token
- isNode
- isNode token
- parse
- parse xml option value
- -baseuri URI
-
- -parser {} libxml2 tcl
-
- -progresscommand script
-
- -chunksize integer
-
- selectNode
- selectNode token xpath ? option value ... ?
- -namespaces
-
- serialize
- serialize token option value
- -method xml|html|text
-
- -indent boolean
-
- -encoding encoding
-
- -newline elementlist
-
- trim
- trim 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.- cget
- cget token -option
- configure
- configure token option value
- -doctype
-
- -documentElement
-
- -keep normal|implicit
-
- -implementation
-
- createElement
- createElement token type
- createElementNS
- createElementNS token nsuri qualname
- createDocumentFragment
- createDocumentFragment token
- createTextNode
- createTextNode token text
- createComment
- createComment token data
- createCDATASection
- createCDATASection token text
- createProcessingInstruction
- createProcessingInstruction token target data
- createAttribute
- createAttribute token name
- createEntity
- createEntity token
- createEntityReference
- createEntityReference token name
- createEvent
- createEvent token name
- getElementsByTagName
- getElementsByTagName token name
- dtd
- dtd validate
- relaxng
- submethod ? args ... ?
- schema
- submethod ? args ... ?
dom::node¶
This command implements generic functions for DOM nodes.- cget
- cget token option
- configure
- configure token option value
- -nodeName
-
- -nodeType
-
- -parentNode
-
- -childNodes
-
- -firstChild
-
- -lastChild
-
- -previousSibling
-
- -nextSibling
-
- -attributes
-
- -nodeValue data
-
- -id
-
- insertBefore
- insertBefore token newchild refchild
- replaceChild
- replaceChild token newchild oldchild
- removeChild
- removeChild token oldchild
- appendChild
- appendChild token newchild
- hasChildNodes
- hasChildNodes token
- isSameNode
- isSameNode token ref
- cloneNode
- cloneNode token deep
- children
- children token
- parent
- parent token
- path
- path token
- createNode
- createNode token xpath
- selectNode
- selectNode token xpath
- stringValue
- stringValue token
- addEventListener
- addEventListener token type listener ? option value ... ?
- -usecapture boolean
-
- removeEventListener
- removeEventListener token type listener ? option value ... ?
- -usecapture boolean
-
- dispatchEvent
- dispatchEvent token event
dom::element¶
This command provides functions for element type nodes.- cget
- cget token option
- configure
- configure token option value
- -tagName name
- The tag name, or element type, of this element.
- -empty boolean
-
- getAttribute
- getAttribute token name
- setAttribute
- setAttribute token name value
- removeAttribute
- removeAttribute token name
- getAttributeNode
- getAttributeNode token name
- setAttributeNode
- setAttributeNode token name
- removeAttributeNode
- removeAttributeNode token name
- getAttributeNS
- getAttributeNS token ns name
- setAttributeNS
- setAttributeNS token ns name value
- removeAttributeNS
- removeAttributeNS token ns name
- getElementsByTagName
- getElementsByTagName token name
- normalize
- normalize token
dom::processinginstruction¶
This command provides functions for processingInstruction type nodes.- cget
- cget token option
- configure
- configure token option value
- -target name
- This option sets the target of the processing instruction. This is a read-only configuration option.
- -data data
-
dom::event¶
This command provides functions for event type nodes.- cget
- cget token
- -altKey
- This option determines whether the ALT modifier key has been specified for this event.
- -attrName -timeStamp
- This option gives the name of the attribute associated with this event.
- -type
- The type of this event.
- -view
- This option gives whether the view of the event.
- configure
- configure token option value
- stopPropagation
- stopPropagation token
- preventDefault
- preventDefault token
- initEvent
- initEvent token type bubbles cancelable
- initUIEvent
- initUIEvent token type bubbles cancelable view detail
- initMouseEvent
- initMouseEvent token type bubbles cancelable view detail screenX screenY clientX clientY ctrlKey altKey shiftKey metaKey button relatedNode
- initMutationEvent
- initMutationEvent token type bubbles cancelable relatedNode prevValue newValue attrName
- postUIEvent
- postUIEvent token type ? option value ... ?
- -bubbles
-
- -cancelable
-
- -view
-
- -detail
-
- postMouseEvent
- postMouseEvent token type ? option value ... ?
- -bubbles
-
- -cancelable
-
- -view
-
- -detail
-
- -screenX
-
- -screenY
-
- -clientX
-
- -clientY
-
- -ctrlKey
-
- -altKey
-
- -shiftKey
-
- -metaKey
-
- -button
-
- -relatedNode
-
- postMutationEvent
- postMutationEvent token type ? option value ... ?
- -bubbles
-
- -cancelable
-
- -relatedNode
-
- -prevValue
-
- -newValue
-
- -attrName
-
ERRORS¶
If an operation results in an error condition, an error message is returned as a structured Tcl list. The list has members as follows: {domain level code node line message int1 int2 string1 string2 string3}IMPLEMENTATIONS¶
This section documents the various implmentations of the TclDOM API.Tcl Implementation¶
The Tcl implementation is provided by the dom::tcl package.Limitations¶
This implementation is not able to preform the following functions:libxml2 Implementation¶
The TclDOM/libxml2 implementation is a wrapper for the Gnome libxml2 library. It is provided by the dom::libxml2 package. It is a high-performance library, making use of Tcl objects for fast access to tree nodes.Limitations¶
TclXML | TclXML Package Commands |