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

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.