TclDOM Reference


		TclDOM Reference TclDOM is a Tcl language binding for the DOM - the Document Object Model. DOM provides a view of a XML (or HTML) document as a tree structure. Currently, TclDOM only supports XML documents. It provides a convenience function to parse XML documents into a DOM structure, allows DOM structures to be built in-memory from scratch and finally provides a method to output XML formatted text from a DOM structure. This version of TclDOM implements DOM Level 1. The DOM Level 1 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. Table Of Contents Packages and Namespaces Tokens DOM Commands `dom::DOMImplementation` Methods: `dom::DOMImplementation hasFeature feature` `dom::DOMImplementation create` `dom::DOMImplementation destroy token` `dom::DOMImplementation parse data ?options ...?` Configuration options: `-parser` `-progresscommand` `-chunksize` `dom::DOMImplementation serialize token ?options ...?` Configuration options: `-newline` `dom::DOMImplementation trim token` `dom::document method token ?arguments...?` Methods: `dom::document cget token option` `dom::configure token option value` Configuration options: `-doctype` `-implementation` `-documentElement` `dom::document createElement token type` `dom::document createDocumentFragment token` `dom::document createTextNode token text` `dom::document createComment token data` `dom::document createCDATASection token text` `dom::document createProcessingInstruction token target data` `dom::document createAttribute token name` `dom::document createEntity token` `dom::document createEntityReference token` `dom::document createDocTypeDecl token name extid dtd entities notations` `dom::document getElementsByTagName token name` `dom::node method token ?arguments...?` Methods: `dom::node cget token option` `dom::node token option value` Configuration options: `-nodeNam`e `-nodeType` `-parentNode` `-childNodes` `-firstChild` `-lastChild` `-previousSibling` `-nextSibling` `-attributes` `-nodeValue` `dom::node insertBefore token newchild ?refchild?` `dom::node replaceChild token newchild oldchild` `dom::node removeChild token oldchild` `dom::node appendChild token newchild` `dom::node hasChildNodes token` `dom::node clodeNode token ?deep?` `dom::node children token` `dom::node parent token` `dom::element method token ?arguments...?` Methods: `dom::element cget token option` `dom::element token option value` Configuration options: `-tagName` `-empty` `dom::element getAttribute token name` `dom::element setAttribute token name value` `dom::element removeAttribute token name` `dom::element getAttributeNode token name` `dom::element setAttributeNode token name` `dom::element removeAttributeNode token name` `dom::element getElementsByTagName token name` `dom::element normalize token` `dom::processinginstruction method token ?arguments...?` Methods: `dom::processinginstruction cget token option` `dom::processinginstruction token option value` Configuration options: `-target` `-data` Packages and Namespaces The TclDOM package defines the `dom` package and also a namespace using that name. Tokens The TclDOM package 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 package. DOM Commands Each Interface in the DOM specification is implemented with a Tcl command in the `dom` namespace. These commands are described below: `dom::DOMImplementation method ?args ...?` This command provides implementation-specific features not explicitly defined in the DOM specification. Methods include: `dom::DOMImplementation hasFeature feature` Provides a test for existence of a feature. Returns "1" if a feature is implemented, "0" otherwise. `dom::DOMImplementation create ?arrayName?` Creates the root node of a new DOM document. The return value is a token referring to the root node of the newly created document. With no argument this command creates a data structure within the `dom` namespace. An `arrayName` argument may be supplied which the package will use to store its data structures in. Future implementations of TclDOM may choose to ignore this argument. `dom::DOMImplementation destroy token` This method frees all data structures associated with a DOM document. The `token` argument must refer to a valid token for any node in the document tree. `dom::DOMImplementation parse data ?options ...?` This method parses XML formatted text given by the `data` 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 `dom` package itself does not include a XML parser. Support for the use of two Tcl event-based parsers is provided: TclXML and TclExpat. Any other Tcl event-based XML parser implementing the TclXML API may also be used. By default the `dom` package will automatically attempt to load either of the supported parsers (using the `package require` Tcl command). It will first attempt to load TclExpat and if that fails it will then attempt to load TclXML. The command fails if neither parser can be loaded. This behaviour can be overridden by the `-parser` option. 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 TclExpat package must be used. The value "tcl" specifies that the TclXML package must be used. If an explicit value is given and that parser cannot be loaded then the command will fail, despite the fact that the other 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. `dom::DOMImplementation serialize token ?options ...?` 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. Valid configuration options are: `-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. 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> `dom::DOMImplementation trim token` This method removes any node containing only white space from the document tree of the node given by `token`. `dom::document method token ?arguments...?` 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 token option` This method returns the value of the given configuration option. `configure token option value` This method sets the value of the given configuration option. Valid configuration options are: `-doctype token` 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. `-implementation token` Specifies the token of the document's implementation. `-documentElement token` Specifies the token of the document's document element node. A document may only have one document element, but may have other types of children. This is a read-only option. Use the factory method to create a document element node. `dom::document createElement token type` This method creates an element node as a child of the given node specified by `token`. `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.` `dom::document createDocumentFragment token` `This method creates a documentFragment node as a child of the given node specified by token. 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.` `dom::document createTextNode token text` `This method creates a textNode node as a child of the given node specified by token. 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 is created with its value set to text.` `dom::document createComment token data` `This method creates a comment node as a child of the given node specified by token. 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 is created with its value set to data.` `dom::document createCDATASection token text` `This method creates a CDATASection node as a child of the given node specified by token. 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 is created with its value set to text.` `dom::document createProcessingInstruction token target data` `This method creates a processingInstruction node as a child of the given node specified by token. 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 is created with its name set to target and its value set to data.` `dom::document createAttribute token name` `This method creates an attribute node as a child of the given node specified by token. token must be a node of type element. The new attribute is created with its name set to name and an empty value. NB. This method is included for completeness with respect to the DOM specification. The preferred method for setting element attributes is to use the element command.` `dom::document createEntity token` `Not currently implemented.` `dom::document createEntityReference token` `Not currently implemented.` `dom::document createDocTypeDecl token name extid dtd entities notations` This method creates a Document Type Declaration node as a child of the given node specified by token. token must be a node of type document. name is the element type of the document element. If the document already has a document element then this name must match with that element type. extid is an external identifier to include in the document type declaration. dtd is an internal DTD subset to incldue in the document type declaration. This is specified as XML text. entities and notations are included for completeness with the DOM specification, but are not currently implemented. Non-standard: This method is not a standard method as specified by the DOM Recommendation. `dom::document getElementsByTagName token name` `This method searches the node given by the argument token for child elements with a type matching the argument name. The tokens for all those elements which match are returned as a Tcl list. The search only occurs on the immediate children of token, not any descendants.` `dom::node method token ?arguments...?` This command implements generic functions for DOM nodes. The methods accepted by this command are as follows: dom::node cget token option This method returns the value of the given configuration option for the node given by token. dom::node configure token option value This method sets the value of the given configuration option for the node given by token. Valid configuration options are as follows: -nodeName Returns the node name. This is a read-only option. The DOM specification gives the meaning of names for different types of nodes. For example, the nodeName option of an element node is the element type. -nodeType Returns the type of the node given by token. This is a read-only option. -parentNode Returns the parent node of the node given by token. This is a read-only option. -childNodes Returns a Tcl variable which contains a list of the children of the node given by token. The variable contains the "live" list of children. This is a read-only option. -firstChild Returns the first child node of the node given by token. This is a read-only option. -lastChild Returns the last child node of the node given by token. This is a read-only option. -previousSibling Returns the parent's child node which appears before this node. If this child is the first child of its parent then returns an empty string. This is a read-only option. -nextSibling Returns the parent's child node which appears after this node. If this child is the last child of its parent then returns an empty string. This is a read-only option. -attributes Returns a Tcl array variable which contains the attribute list for an element node. If the node is not an element type node then returns an empty string. The indices of the array are attribute names, and the values of the array elements are their corresponding attribute values. This is a read-only option. -nodeValue data Specifies the value of a node. The DOM specification gives the meaning of values for different types of nodes. For example, the nodeValue option of a textNode node is the node's text. dom::node insertBefore token newchild ?refchild? This method removes the node given by newchild from its parent. If no refchild argument is given then newchild is appended to token's list of children. If the refchild argument is given then this method adds newchild as a child of token. The new child node is positioned before the node refchild in token's list of children. Returns an empty string. dom::node replaceChild token newchild oldchild This method removes the node given by newchild from its parent. It then also removes the node given by oldchild from token. newchild is then added as a child of token in oldchild's original position in the list of children. The method returns the token oldchild, which will now have no parent. dom::node removeChild token oldchild This method removes the node given by oldchild from token. The method returns the token oldchild, which will now have no parent. dom::node appendChild token newchild This method appends the node given by oldchild to the end of the list of children for node token. dom::node hasChildNodes token Returns "1" if the given node has any child nodes, "0" otherwise. dom::node clodeNode token ?deep? This method makes a copy the node given by token. If the argument deep is not specified or has the value "0" then only the node itself is copied, not its children. If the argument deep has the value "1" then token's children are also copied recursively. This method returns the token of the newly created node. This new node will have no parent. dom::node children token This is a convenience method which returns the list of child nodes for the given node. This is not a standard DOM method for this interface dom::node parent token This is a convenience method which returns the parent node for the given node. This is not a standard DOM method for this interface `dom::element method token ?arguments...?` This command provides functions for element type nodes. Valid methods for this command are as follows: dom::element cget token option This method returns the current setting of configuration options for an element. See the configure method for the list of valid configuration options. dom::element configure token option value This method sets configuration options for an element. Note that element type nodes only have read-only options. Valid configuration options are as follows: -tagName name The tag name, or element type, of this element. -empty boolean Sets whether this element was specified as an empty element when the document was parsed. That is, XML empty element syntax such as <Empty/> was used. This option has no effect upon output (serialization) of the XML document. Empty element syntax is automatically used where appropriate. dom::element getAttribute token name This method returns the attribute value of the attribute given by name. If the attribute does not exist, then an empty string is returned. dom::element setAttribute token name value This method sets the attribute value for the attribute given by name. If the attribute already exists then its value is replaced, otherwise the attribute is created. dom::element removeAttribute token name This method deletes the attribute given by name. If the attribute does not exist then the method has no effect. dom::element getAttributeNode token name dom::element setAttributeNode token name dom::element removeAttributeNode token name Interfaces to attributeNodes are not implemented. dom::element getElementsByTagName token name This method searches the node given by the argument token for child elements with a type matching the argument name. The tokens for all those elements which match are returned as a Tcl list. The search only occurs on the immediate children of token, not any descendants. dom::element normalize token This method recursively coalesces textNodes within the children of the given node. textNodes which are adjacent in the DOM tree cannot be distinguished in the serialized XML document. `dom::processinginstruction method token ?arguments...?` This command provides functions for processingInstruction type nodes. Valid methods for this command are as follows: dom::processinginstruction cget token option This method returns the current setting of configuration options for a processing instruction. dom::processinginstruction configure token option value This method sets the configuration options for a processing instruction. Valid configuration options are as follows: -target name This option sets the target of the processing instruction. This is a read-only configuration option. -data string This option sets the data of the processing instruction.
		Copyright © 1998,1999 Zveno Pty Ltd. All Rights Reserved. Comments on this site? Contact mailto:webmaster@zveno.com