TclDOM(3tcl) | TclDOM(3tcl) |
See the file "LICENSE" for information on
usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
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.
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.
Non-standard method.
NAME¶
TclDOM - Tcl language binding for the W3C Document Object ModelSYNOPSIS¶
package require dom ::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 docDESCRIPTION¶
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. 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.PACKAGES AND NAMESPACES¶
TclDOM defines the dom package and also a Tcl namespace using that same name. Implementations define their own package name and Tcl namespace within the ::dom Tcl namespace:- 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. 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.
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. 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.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. 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.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. The methods accepted by this command are as follows:- 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. The methods accepted by this command are as follows:- 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. Valid methods for this command are as follows:- 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. Valid methods for this command are as follows:- 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. Valid methods for this command are as follows:- 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 ... ?
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:
- -bubbles
- -cancelable
- -view
- -detail
- postMouseEvent
- postMouseEvent token type ? option 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:
- -bubbles
- -cancelable
- -view
- -detail
- -screenX
- -screenY
- -clientX
- -clientY
- -ctrlKey
- -altKey
- -shiftKey
- -metaKey
- -button
- -relatedNode
- postMutationEvent
- postMutationEvent token type ? option 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:
- -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} The format of the list is described in the TclXML manual page.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:
* 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.
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¶
* 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.
TclXML | TclXML Package Commands |