TclDOM(n)TclDOM(n)______________________________________________________________________________NAME
::dom::DOMImplementation - Tcl language binding for the W3C Document
Object Model
SYNOPSIS
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 ... ?
_________________________________________________________________DESCRIPTION
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-stan‐
dard 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 inter‐
faces. 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 applica‐
tion, and specific implementations may register themselves. Currently,
three implementations exists: a pure-Tcl implementation, a C implemen‐
tation (based on TclDOMPro) and another C implementation based on the
Gnome libxml2 & gdome2 libraries.
PACKAGES AND NAMESPACES
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:
Tcl implementation
Package , Tcl namespace ::dom::tcl.
TclDOMPro
Package , Tcl namespace ::dom::c.
libxml2
Package , Tcl namespace ::dom::libxml2.
TOKENS
The TclDOM API uses as identifiers for nodes within the docu‐
ment tree. This technique has been used to allow alternate
implementations of TclDOM to be efficient, while retaining com‐
patibility 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.
DOM INTERFACES
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 function‐
ality, 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.
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 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 fea‐
tures. Refer to the documentation for a DOM implementation.
COMMANDS
::dom::DOMImplementation
The ::dom::DOMImplementation command implements the DOM inter‐
face. 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 if a feature is
implemented, otherwise. Uses the
default DOM implementation.
create create type
Creates the root node of a new DOM
document, using the default DOM
implementation. The document ele‐
ment 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.
createDocument createDocument nsURI
type doctype
Creates the root node of a new DOM
document, using the default DOM
implementation. The document ele‐
ment namespace URI and local-name
(element type) may be specified as
an argument, in which case that ele‐
ment 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.
createDocumentType createDocument‐
Type token name publicid systemid
internaldtd
Creates a Document Type Declaration,
using the default DOM implementa‐
tion. The return value is a token
for the newly created document type
declaration.
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.
destroy destroy token
This method frees all data struc‐
tures associated with a DOM node.
The token argument must refer to a
valid token for any node in the doc‐
ument tree. The node is removed
from the tree before it is
destroyed. If the node has chil‐
dren, they will also be destroyed.
isNode isNode token
Tests whether the given token is a
valid token for some DOM node in the
default DOM implementation.
parse parse xml ? option value?
This method parses XML formatted
text given by the xml argument and
constructs a DOM tree for the docu‐
ment. 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 imple‐
mentation 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:
-parser
? {}
expat
tcl?
This
option
speci‐
fies
which
XML
parser
to use
to parse
the XML
data.
If an
empty
string
is given
then the
default
behav‐
iour
described
above is
used.
The
value
expat
speci‐
fies
that the
Expat
parser
must be
used.
The
value
tcl
speci‐
fies
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
avail‐
able.
-pro‐
gress‐
command
script
This
option
speci‐
fies a
Tcl com‐
mand to
be
invoked
from
time to
time
while
the DOM
tree is
being
con‐
structed.
The
script
will be
invoked
after a
certain
number
of ele‐
ment
start
tags
have
been
pro‐
cessed,
given by
the
-chunk‐
size
option.
-chunk‐
size
integer
This
option
speci‐
fies how
many
element
start
tags to
process
before
invoking
the
script
given by
the
-pro‐
gress‐
command
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 node‐
set as a Tcl
list.
The following
options may be
specified:
-names‐
paces
The
value
for
this
option
is
a
list
of
pre‐
fix-
URI
pairs.
Each
of
these
pairs
defines
an
XML
Names‐
pace
and
its
pre‐
fix
for
the
pur‐
poses
of
eval‐
u‐
at‐
ing
the
XPath
expres‐
sion.
The
doc‐
u‐
ment
itself
may
use
a
dif‐
fer‐
ent
pre‐
fix
for
the
same
XML
Names‐
pace.
This
option
may
be
repeated,
in
which
case
the
lists
of
names‐
pace
pairs
are
merged
and
all
of
the
XML
Names‐
paces
reg‐
is‐
tered.
seri‐
al‐
ize
seri‐
al‐
ize
token
?
option
value?
This
method
returns
the
XML
for‐
mat‐
ted
text
cor‐
re‐
spond‐
ing
to
the
node
given
by
token.
The
text
is
guar‐
an‐
teed
to
be
a
well-
formed
XML
doc‐
u‐
ment,
unless
the
-method
option
spec‐
i‐
fies
a
non-
XML
out‐
put
method.
Valid
con‐
fig‐
u‐
ra‐
tion
options
are:
-new‐
line
ele‐
mentlist
This
option
spec‐
i‐
fies
a
list
of
ele‐
ment
types
for
which
new‐
line
char‐
ac‐
ters
will
be
added
before
and
after
the
start
and
end
tags
for
those
ele‐
ments
upon
seri‐
al‐
iza‐
tion.
White
space
is
sig‐
nif‐
i‐
cant
in
XML,
so
the
pack‐
age
never
adds
extra
white
space‐
for
pur‐
poses
of
"pretty-
print‐
ing"
the
XML
source
doc‐
u‐
ment.
On
some
plat‐
forms,
such
as
VMS,
this
can
actu‐
ally
cause
seri‐
ous
prob‐
lems
due
to
line
length
lim‐
i‐
ta‐
tions.
This
option
pro‐
vides
the
con‐
ve‐
nience
of
adding
new‐
lines
to
cer‐
tain
nom‐
i‐
nated
ele‐
ment
types
for
for‐
mat‐
ting
the
source
into
lines.
Exam‐
ples:
Sup‐
pose
the
fol‐
low‐
ing
DOM
doc‐
u‐
ment
is
con‐
structed:
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
With‐
out
the
-new‐
line
option
the
seri‐
al‐
ized
doc‐
u‐
ment
would
be:
::dom::DOMImplementation serialize $doc
With
the
-new‐
line
option
the
seri‐
al‐
ized
doc‐
u‐
ment
would
be:
::dom::DOMImplementation serialize $doc -newline First
trim
trim
token
This
method
removes
any
node
con‐
tain‐
ing
only
white
space
from
the
doc‐
u‐
ment
tree
of
the
node
given
by
token.
::dom::doc‐
u‐
ment
This
com‐
mand
imple‐
ments
the
Doc‐
u‐
ment
inter‐
face
in
the
DOM
spec‐
i‐
fi‐
ca‐
tion.
The
most
impor‐
tant
aspect
of
this
com‐
mand
are
its
fac‐
tory
meth‐
ods
for
cre‐
at‐
ing
nodes.
The
meth‐
ods
accepted
by
this
com‐
mand
are
as
fol‐
lows:
dom::node
This
com‐
mand
imple‐
ments
generic
func‐
tions
for
DOM
nodes.
The
meth‐
ods
accepted
by
this
com‐
mand
are
as
fol‐
lows:
dom::ele‐
ment
This
com‐
mand
pro‐
vides
func‐
tions
for
ele‐
ment
type
nodes.
Valid
meth‐
ods
for
this
com‐
mand
are
as
fol‐
lows:
dom::pro‐
cessin‐
gin‐
struc‐
tion
This
com‐
mand
pro‐
vides
func‐
tions
for
pro‐
cessin‐
gIn‐
struc‐
tion
type
nodes.
Valid
meth‐
ods
for
this
com‐
mand
are
as
fol‐
lows:
dom::event
This
com‐
mand
pro‐
vides
func‐
tions
for
event
type
nodes.
Valid
meth‐
ods
for
this
com‐
mand
are
as
fol‐
lows:
IMPLE‐
MEN‐
TA‐
TIONS
This
sec‐
tion
doc‐
u‐
ments
the
var‐
i‐
ous
impl‐
men‐
ta‐
tions
of
the
TclDOM
API.
Tcl
Imple‐
men‐
ta‐
tion
The
Tcl
imple‐
men‐
ta‐
tion
is
pro‐
vided
by
the
pack‐
age.
It
is
a
ref‐
er‐
ence
imple‐
men‐
ta‐
tion,
and
imple‐
ments
the
TclDOM
API
as
described
above.
A
DOM
tree
using
this
imple‐
men‐
ta‐
tion
may
be
cre‐
ated
using
the
dom::tcl::cre‐
ate
com‐
mand.
libxml2
Imple‐
men‐
ta‐
tion
The
TclDOM/libxml2
imple‐
men‐
ta‐
tion
is
a
wrap‐
per
for
the
.
It
is
pro‐
vided
by
the
pack‐
age.
It
is
a
high-
per‐
for‐
mance
library,
mak‐
ing
use
of
Tcl
objects
for
fast
access
to
tree
nodes.
A
DOM
tree
using
this
imple‐
men‐
ta‐
tion
may
be
cre‐
ated
using
the
dom::libxml2::cre‐
ate
com‐
mand.
Notes
Tcl Built-In Commands Tcl TclDOM(n)
