Ubuntu Manpage: TclDOM - Tcl language binding for the W3C Document Object Model

name
synopsis
description
packages and namespaces
tokens
document and node commands
dom interfaces
convenience commands and methods
commands
errors
implementations

NAME

       TclDOM - Tcl language binding for the W3C Document Object Model

SYNOPSIS

       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 doc

DESCRIPTION

       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

              Package dom::tcl, Tcl namespace ::dom::tcl.

              libxml2

              Package dom::libxml2, Tcl namespace ::dom::libxml2.

       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.

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

Provides a test for existence of a feature. Returns 1 if a feature is implemented, 0 otherwise.

create
create type

Creates the root node of a new DOM document. 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. A Tcl command is also created with the same name as the
document's token. This command is a shortcut for the ::dom::document command.

Non-standard method. DOM Level 2 introduced the createDocument method.

createDocument
createDocument nsURI type doctype

Creates the root node of a new DOM document. 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. A Tcl
command is also created with the same name as the document's token. This command is a shortcut
for the ::dom::document command.

createDocumentType
createDocumentType name publicid systemid internaldtd

Creates a Document Type Declaration. The return value is a token for the newly created document
type declaration. A Tcl command is also created with the same name as the document type's token.
This command is a shortcut for the ::dom::documenttype command.

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.

Non-standard method.

destroy
destroy token

This method frees all data structures associated with a DOM document or node. The token argument
must refer to a valid token for any document or any node in the tree of a document.

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.

isNode
isNode token

Tests whether the given token is a valid token for some DOM node.

Non-standard method.

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. The
document will also have a Tcl command associated with it, see the createDocument 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:

-baseuri URI

Gives the Base URI for the document. Any relative URIs specified in the document are
resolved against the given base URI. Examples of relative URIs include external entity
references.

If no Base URI is given then relative URIs are resolved in the current context, namely the
current working directory.

-parser {} libxml2 tcl

This option specifies the name of a TclXML parser class to use to parse the XML data. The
given parser class must be registered with the TclXML package. If an empty string is given
then the default parser class is used. If an explicit value is given and that parser class
is not registered 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 resulting nodeset as a (static) 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 registered.

Non-standard method.

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:

-method xml|html|text

Specifies how the document tree is to be serialized as text. The allowed values correspond
to the output methods defined by the XSLT v1.0 W3C Recommendation. The xml method produces
output that conforms to the XML syntax. The html method produces output that conforms to
HTML syntax. The text method serializes only the text nodes of the document and disables
all output escaping.

-indent boolean

Specifies that the output is to be "pretty-printed", ie. element content is indented to
provide a visual indication of nesting levels.

-encoding encoding

Specifies that the output is to be encoded using the given character encoding. If the
encoding is utf-8 (the default) then the output is treated as a string within Tcl. If any
other encoding is specified then the output is treated as a ByteArray object (ie. as
binary).

-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. This option
is deprecated: the -indent option should be used instead.

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>

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:

cget cget token -option

This method returns the value of the given configuration option.

configure
configure token option value

This method sets the value of the given configuration options.

Valid configuration options are:

-doctype

Specifies the token of the Document Type Declaration node.

This is a read-only option. Use the factory method to create a Document Type Declaration
node.

-documentElement

Specifies the token of the document's document element node. A document node may only have
one document element, but may have other types of children (such as comments).

This is a read-only option. Use the factory method to create the document element node.

-keep normal|implicit

Specifies the memory management strategy for the document. The value normal specifies that
the document must be explicitly destroyed in order for resources consumed by the document
to be freed. The value implicit specifies that the resources consumed by the document are
freed when there are no longer any references to the document. Note that object shimmering
can prematurely remove document references.

The default value is implicit.

-implementation

Specifies the token of the document's implementation.

This is a read-only option.

createElement
createElement token type

This method creates an element node as a child of the given node specified by token and returns
the new node's token as its result. token must be a node of type element, document or
documentFragment. The new, child element is added as the last child of token's list of children.
The new element's type is given by the type argument. The new element is created with an empty
attribute list.