Manual Pages for UNIX Darwin command on man tcldom

TclDOM(n) TclDOM(n)

NAME

::dom::DOMImplementation - Tcl language binding for the W3C Document

Object Model

SYNOPSIS

ppaacckkaaggee rreeqquuiirree ddoomm ddoomm22..55 ::::ddoomm::::ddoomm::::ttccll::::ddoomm::::lliibbxxmmll22 ::::ddoomm::::DDOOMMIImmpplleemmeennttaattiioonn method ? args ... ? ::::ddoomm::::ccrreeaattee element ::::ddoomm::::ppaarrssee xml ? option value ... ? ::::ddoomm::::sseerriiaalliizzee token ? option value ... ? ::::ddoomm::::ddooccuummeenntt method token ? args ... ? ::::ddoomm::::nnooddee method token ? args ... ? ::::ddoomm::::eelleemmeenntt method token ? args ... ? ::::ddoomm::::eevveenntt method token ? args ... ? ::::ddoomm::::sseelleeccttNNooddee 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: TTccll iimmpplleemmeennttaattiioonn Package , Tcl namespace ::::ddoomm::::ttccll. TTccllDDOOMMPPrroo Package , Tcl namespace ::::ddoomm::::cc. lliibbxxmmll22 Package , Tcl namespace ::::ddoomm::::lliibbxxmmll22. TTOOKKEENNSS

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. DDOOMM IINNTTEERRFFAACCEESS Each in the DOM specification is implemented with a Tcl command in the ddoomm 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. CCOONNVVEENNIIEENNCCEE CCOOMMMMAANNDDSS AANNDD MMEETTHHOODDSS 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 ddoomm::::DDOOMMIImmpplleemmeennttaattiioonn ccrreeaattee to create a new document, the shorter command ddoomm::::ccrreeaattee may be used.

Implementations may also provide direct access to specific fea-

tures. Refer to the documentation for a DOM implementation. CCOOMMMMAANNDDSS ::::ddoomm::::DDOOMMIImmpplleemmeennttaattiioonn

The ::::ddoomm::::DDOOMMIImmpplleemmeennttaattiioonn 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. hhaassFFeeaattuurree hasFeature feature Provides a test for existence of a feature. Returns if a feature is implemented, otherwise. Uses the default DOM implementation. ccrreeaattee 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. ccrreeaatteeDDooccuummeenntt 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.

ccrreeaatteeDDooccuummeennttTTyyppee 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. ccrreeaatteeNNooddee 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. ddeessttrrooyy 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. iissNNooddee isNode token Tests whether the given token is a valid token for some DOM node in the default DOM implementation. ppaarrssee 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. sseelleeccttNNooddee 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-

at-

ing the XPath

expres-

sion. The

doc-

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.

sseerrii-

aall-

iizzee

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-

ment, unless the

-method

option

spec-

fies a

non-

XML

out-

put method. Valid

con-

fig-

ra-

tion options are:

-new-

line

ele-

mentlist This option

spec-

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-

cant in XML, so the

pack-

age never adds extra white

space-

for

pur-

poses of

"pretty-

print-

ing" the XML source

doc-

ment. On some

plat-

forms, such as VMS, this can

actu-

ally cause

seri-

ous

prob-

lems due to line length

lim-

ta-

tions. This option

pro-

vides the

con-

ve-

nience of adding

new-

lines to

cer-

tain

nom-

nated

ele-

ment types for

for-

mat-

ting the source into lines.

Exam-

ples:

Sup-

pose the

fol-

low-

ing DOM

doc-

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-

ment would be:

::dom::DOMImplementation serialize $doc

With the

-new-

line option the

seri-

al-

ized

doc-

ment would be:

::dom::DOMImplementation serialize $doc -newline First

ttrriimm trim token This method removes any node

con-

tain-

ing only white space from the

doc-

ment tree of the node given by token.

::::ddoomm::::ddoocc-

uu-

mmeenntt This

com-

mand

imple-

ments the

Doc-

ment

inter-

face in the DOM

spec-

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: ddoomm::::nnooddee This

com-

mand

imple-

ments generic

func-

tions for DOM nodes. The

meth-

ods accepted by this

com-

mand are as

fol-

lows:

ddoomm::::eellee-

mmeenntt This

com-

mand

pro-

vides

func-

tions for

ele-

ment type nodes. Valid

meth-

ods for this

com-

mand are as

fol-

lows:

ddoomm::::pprroo-

cceessssiinn-

ggiinn-

ssttrruucc-

ttiioonn 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: ddoomm::::eevveenntt This

com-

mand

pro-

vides

func-

tions for event type nodes. Valid

meth-

ods for this

com-

mand are as

fol-

lows:

IIMMPPLLEE-

MMEENN-

TTAA-

TTIIOONNSS This

sec-

tion

doc-

ments the

var-

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

ddoomm::::ttccll::::ccrree-

aattee

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

ddoomm::::lliibbxxmmll22::::ccrree-

aattee

com-

mand. Notes

Tcl Built-In Commands Tcl TclDOM(n)