|
|
Эта страница руководства для версии 10.9 Mac OS XЕсли Вы выполняете различную версию Mac OS X, просматриваете документацию локально:
Читать страницы руководстваСтраницы руководства предназначаются как справочник для людей, уже понимающих технологию.
|
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 inter-faces. interfaces.
faces. 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 several implementations of the API, with a layered architecture. A generic
layer provides a stable API to the application, and specific implementations may register themselves.
Currently, three implementations exists: a pure-Tcl implementation, a C implementation (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 document tree. This technique has
been used to allow alternate implementations of TclDOM to be efficient, while retaining com-patibility compatibility
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
functionality, 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 docu-ment. document.
ment. 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 features. Refer to the documenta-tion documentation
tion for a DOM implementation.
COMMANDS
::dom::DOMImplementation
The ::dom::DOMImplementation command implements the 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 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 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 docu-ment. document.
ment.
createDocument createDocument nsURI type doctype
Creates the root node of a new DOM document, using the default DOM
implementation. 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.
createDocumentType createDocumentType token name publicid sys-temid systemid
temid internaldtd
Creates a Document Type Declaration, using the default DOM imple-mentation. implementation.
mentation. The return value is a token for the newly created doc-ument document
ument 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 structures associated with a DOM node.
The token argument must refer to a valid token for any node in
the document tree. The node is removed from the tree before it is
destroyed. If the node has children, 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 document. 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 implementation may parse the XML doc-ument document
ument 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 specifies which XML parser
to use to parse the XML data. If an
empty string is given then the default
behaviour described above is used.
The value expat specifies that the
Expat parser must be used. The value
tcl specifies 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
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 -progresscom-mand -progresscommand
mand 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 Tcl list.
The following options may be specified:
-namespaces
The value for
this option is a
list of prefix-URI prefixURI
URI pairs. Each
of these pairs
defines an XML
Namespace and its
prefix for the
purposes of eval-uating evaluating
uating the XPath
expression. The
document itself
may use a differ-ent different
ent prefix for
the same XML
Namespace.
This option may
be repeated, in
which case the
lists of names-pace namespace
pace pairs are
merged and all of
the XML Names-paces Namespaces
paces registered.
serialize serialize
token ? option value?
This method returns the
XML formatted text cor-responding corresponding
responding to the node
given by token. The
text is guaranteed to be
a well-formed XML docu-ment, document,
ment, unless the
-method option specifies
a non-XML output method.
Valid configuration
options are:
-new-line -newline
line
ele-mentlist elementlist
mentlist
This
option
spec-i speci
i-fies ifies
fies
a
list
of
ele-ment element
ment
types
for
which
new-line newline
line
char-ac charac
ac-ters acters
ters
will
be
added
before
and
after
the
start
and
end
tags
for
those
ele-ments elements
ments
upon
seri-al serial
al-iza aliza
iza-tion. ization.
tion.
White
space
is
sig-nif signif
nif-i nifi
i-cant icant
cant
in
XML,
so
the
pack-age package
age
never
adds
extra
white
space-for spacefor
for
pur-poses purposes
poses
of
"pretty-print "prettyprint
print-ing" printing"
ing"
the
XML
source
doc-u docu
u-ment. ument.
ment.
On
some
plat-forms, platforms,
forms,
such
as
VMS,
this
can
actu-ally actually
ally
cause
seri-ous serious
ous
prob-lems problems
lems
due
to
line
length
lim-i limi
i-ta ita
ta-tions. tations.
tions.
This
option
pro-vides provides
vides
the
con-ve conve
ve-nience venience
nience
of
adding
new-lines newlines
lines
to
cer-tain certain
tain
nom-i nomi
i-nated inated
nated
ele-ment element
ment
types
for
for-mat format
mat-ting matting
ting
the
source
into
lines.
Exam-ples: Examples:
ples:
Sup-pose Suppose
pose
the
fol-low follow
low-ing lowing
ing
DOM
doc-u docu
u-ment ument
ment
is
con-structed: constructed:
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 Without
out
the
-new-line -newline
line
option
the
seri-al serial
al-ized alized
ized
doc-u docu
u-ment ument
ment
would
be:
::dom::DOMImplementation serialize $doc
With
the
-new-line -newline
line
option
the
seri-al serial
al-ized alized
ized
doc-u docu
u-ment ument
ment
would
be:
::dom::DOMImplementation serialize $doc -newline First
trim
trim
token
This
method
removes
any
node
con-tain contain
tain-ing taining
ing
only
white
space
from
the
doc-u docu
u-ment ument
ment
tree
of
the
node
given
by
token.
::dom::document
This command
implements the
Document inter-face interface
face in the DOM
specification.
The most impor-tant important
tant aspect of
this command are
its factory meth-ods methods
ods for creating
nodes.
The methods
accepted by this
command are as
follows:
dom::node
This command
implements
generic functions
for DOM nodes.
The methods
accepted by this
command are as
follows:
dom::element
This command pro-vides provides
vides functions
for element type
nodes.
Valid methods for
this command are
as follows:
dom::processin-ginstruction dom::processinginstruction
ginstruction
This command pro-vides provides
vides functions
for processingIn-struction processingInstruction
struction type
nodes.
Valid methods for
this command are
as follows:
dom::event
This command pro-vides provides
vides functions
for event type
nodes.
Valid methods for
this command are
as follows:
IMPLEMENTATIONS
This section doc-uments documents
uments the vari-ous various
ous implmenta-tions implmentations
tions of the
TclDOM API.
Tcl Implementa-tion Implementation
tion
The Tcl implemen-tation implementation
tation is pro-vided provided
vided by the
package.
It is a reference
implementation,
and implements
the TclDOM API as
described above.
A DOM tree using
this implementa-tion implementation
tion may be cre-ated created
ated using the
dom::tcl::create
command.
libxml2 Implemen-tation Implementation
tation
The
TclDOM/libxml2
implementation is
a wrapper for the
. It is provided
by the package.
It is a high-per-formance high-performance
formance library,
making use of Tcl
objects for fast
access to tree
nodes.
A DOM tree using
this implementa-tion implementation
tion may be cre-ated created
ated using the
dom::libxml2::cre-ate dom::libxml2::create
ate command.
Notes
Tcl Built-In Commands Tcl TclDOM(n)
|
Сообщение о проблемах
Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:
- Ошибки содержания
- Ошибки отчета в содержании этой документации к проекту Tcl.
- Отчеты об ошибках
- Сообщите об ошибках в функциональности описанного инструмента или API к Apple через Генератор отчетов Ошибки и к проекту Tcl через их страницу создания отчетов ошибки.
- Форматирование проблем
- Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.