/usr/share/doc/tclxml/tcldom.html is in tclxml 3.3~svn11-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 | <html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>TclDOM</title>
<link rel="stylesheet" href="tclxml.css">
</head>
<body><div class="refentry">
<h1 class="title"><a name="idm47122586993600">TclDOM</a></h1>
<h2>Contents</h2>
<ul>
<li><a href="#synopsis">Synopsis</a></li>
<li><a href="#idm47122586915040">Description</a></li>
<li><a href="#idm47122586910000">Packages and Namespaces</a></li>
<li><a href="#idm47122586758032">Tokens</a></li>
<li><a href="#idm47122586751056">Document and Node Commands</a></li>
<li><a href="#idm47122586747600">DOM Interfaces</a></li>
<li><a href="#idm47122586726352">Convenience Commands and Methods</a></li>
<li>
<a href="#idm47122586720976">Commands</a><ul>
<li>
<a href="#idm47122586719616">::dom::DOMImplementation</a><ul><li><a href="#idm47122586716016">Command Options</a></li></ul>
</li>
<li><a href="#idm47122586560096">::dom::document</a></li>
<li><a href="#idm47122586404272">dom::node</a></li>
<li><a href="#idm47122586201920">dom::element</a></li>
<li><a href="#idm47122586117104">dom::processinginstruction</a></li>
<li><a href="#idm47122586096288">dom::event</a></li>
</ul>
</li>
<li><a href="#idm47122585893904">Errors</a></li>
<li>
<a href="#idm47122585890384">Implementations</a><ul>
<li>
<a href="#idm47122585888464">Tcl Implementation</a><ul><li><a href="#idm47122585886144">Limitations</a></li></ul>
</li>
<li>
<a href="#idm47122585881792">libxml2 Implementation</a><ul><li><a href="#idm47122585878192">Limitations</a></li></ul>
</li>
</ul>
</li>
</ul>
<div class="refnamediv">
<span class="refname">TclDOM</span> ? <span class="refpurpose">Tcl language binding for the W3C Document Object Model</span>
</div>
<div class="refsynopsisdiv">
<a name="synopsis"></a><h2>Synopsis</h2>
<div class="cmdsynopsis" id="idm47122586969312">
<a name="idm47122586969312"></a><span class="command" id="idm47122586968944"><a name="package_require_dom"></a><tt>package require dom</tt> </span>
</div>
<br><span class="pkgsynopsis"><pre>package require dom ?3.3?</pre></span><div class="cmdsynopsis" id="idm47122586964784">
<a name="idm47122586964784"></a><span class="command" id="idm47122586964416"><a name="__dom__DOMImplementation"></a><tt>::dom::DOMImplementation</tt> </span><em>method</em> ?args...?</div>
<div class="cmdsynopsis" id="idm47122586961264">
<a name="idm47122586961264"></a><span class="command" id="idm47122586960944"><a name="__dom__hasfeature"></a><tt>::dom::hasfeature</tt> </span><em>feature</em> <em>version</em>
</div>
<div class="cmdsynopsis" id="idm47122586958560">
<a name="idm47122586958560"></a><span class="command" id="idm47122586958192"><a name="__dom__create"></a><tt>::dom::create</tt> </span>
</div>
<div class="cmdsynopsis" id="idm47122586957568">
<a name="idm47122586957568"></a><span class="command" id="idm47122586957200"><a name="__dom__destroy"></a><tt>::dom::destroy</tt> </span><em>token</em>
</div>
<div class="cmdsynopsis" id="idm47122586955696">
<a name="idm47122586955696"></a><span class="command" id="idm47122586955328"><a name="__dom__parse"></a><tt>::dom::parse</tt> </span><em>xml</em> ?option value...?</div>
<div class="cmdsynopsis" id="idm47122586951936">
<a name="idm47122586951936"></a><span class="command" id="idm47122586951568"><a name="__dom__serialize"></a><tt>::dom::serialize</tt> </span><em>token</em> ?option value...?</div>
<div class="cmdsynopsis" id="idm47122586948320">
<a name="idm47122586948320"></a><span class="command" id="idm47122586947952"><a name="__dom__document"></a><tt>::dom::document</tt> </span><em>method</em> <em>token</em> ?args...?</div>
<div class="cmdsynopsis" id="idm47122586944208">
<a name="idm47122586944208"></a><span class="command" id="idm47122586943840"><a name="__dom__documenttype"></a><tt>::dom::documenttype</tt> </span><em>method</em> <em>token</em> ?args...?</div>
<div class="cmdsynopsis" id="idm47122586940064">
<a name="idm47122586940064"></a><span class="command" id="idm47122586939696"><a name="__dom__node"></a><tt>::dom::node</tt> </span><em>method</em> <em>token</em> ?args...?</div>
<div class="cmdsynopsis" id="idm47122586935952">
<a name="idm47122586935952"></a><span class="command" id="idm47122586935584"><a name="__dom__element"></a><tt>::dom::element</tt> </span><em>method</em> <em>token</em> ?args...?</div>
<div class="cmdsynopsis" id="idm47122586931840">
<a name="idm47122586931840"></a><span class="command" id="idm47122586931472"><a name="__dom__event"></a><tt>::dom::event</tt> </span><em>method</em> <em>token</em> ?args...?</div>
<div class="cmdsynopsis" id="idm47122586927728">
<a name="idm47122586927728"></a><span class="command" id="idm47122586927360"><a name="__dom__selectNode"></a><tt>::dom::selectNode</tt> </span><em>token</em> <em>xpath</em> ?option value...?</div>
<div class="cmdsynopsis" id="idm47122586923584">
<a name="idm47122586923584"></a><span class="command" id="idm47122586923216"><a name="__dom__isNode"></a><tt>::dom::isNode</tt> </span><em>token</em>
</div>
<div class="cmdsynopsis" id="idm47122586921712">
<a name="idm47122586921712"></a><span class="command" id="idm47122586921344"><a name="__dom__xinclude"></a><tt>::dom::xinclude</tt> </span><em>doc</em>
</div>
<div class="cmdsynopsis" id="idm47122586919840">
<a name="idm47122586919840"></a><span class="command" id="idm47122586919472"><a name="__dom__prefix2namespaceURI"></a><tt>::dom::prefix2namespaceURI</tt> </span><em>node</em> <em>prefix</em>
</div>
<div class="cmdsynopsis" id="idm47122586917040">
<a name="idm47122586917040"></a><span class="command" id="idm47122586916672"><a name="__dom__trim"></a><tt>::dom::trim</tt> </span><em>doc</em>
</div>
<h3>Tcl Namespace Usage</h3>
<br><tt>::dom</tt><br><tt>::dom::tcl</tt><br><tt>::dom::libxml2</tt><p></p>
</div>
<div class="refsect1">
<h2>
<a name="idm47122586915040"></a>Description</h2>
<p>TclDOM is a Tcl language binding for the <a href="http://www.w3c.org/DOM/">W3C Document Object Model</a> (DOM). DOM provides a view of a XML (or HTML) document as a tree structure. Currently, TclDOM only supports XML documents.</p>
<p>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).</p>
<p>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.</p>
<p>TclDOM also provides two implementations of the API: a pure-Tcl implementation and a C implementation based on the Gnome libxml2 library.</p>
</div>
<div class="refsect1">
<h2>
<a name="idm47122586910000"></a>Packages and Namespaces</h2>
<p>TclDOM defines the <tt>dom</tt> package and also a Tcl namespace using that same name.</p>
<p>Implementations define their own package name and Tcl namespace within the <tt>::dom</tt> Tcl namespace:</p>
<dl>
<span class="term">Tcl implementation</span><dd><p>Package <tt>dom::tcl</tt>, Tcl namespace <tt>::dom::tcl</tt>.</p></dd>
<span class="term">libxml2</span><dd><p>Package <tt>dom::libxml2</tt>, Tcl namespace <tt>::dom::libxml2</tt>.</p></dd>
</dl>
<p>Each DOM Document is allocated a Tcl namespace within the <tt>::dom</tt> Tcl namespace. All storage for the document and commands are defined within that Tcl namespace.</p>
</div>
<div class="refsect1">
<h2>
<a name="idm47122586758032"></a>Tokens</h2>
<p>The TclDOM API uses <em>tokens</em> 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.</p>
<p>The format of the token itself as well as the data structure referred to by the token are <em>not</em> public and an application should not rely on these. Instead, an application should use the accessor methods provided by the API.</p>
<p>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 <tt>isSameNode</tt> method must be used for this purpose. For example,</p>
<div class="informalexample"><pre><div class="programlisting"><pre>
proc NodeCompare1 {A B} {
return [string equal $A $B]
}
proc NodeCompare2 {A B} {
return [$A isSameNode $B]
}
</pre></div></pre></div>
<p>In the above example, <span class="literal">NodeCompare2</span> correctly determines whether its two arguments refer to the same node.</p>
</div>
<div class="refsect1">
<h2>
<a name="idm47122586751056"></a>Document and Node Commands</h2>
<p>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 <strong>::dom::document</strong> command (for Documents) or the <strong>::dom::node</strong> command (for all other Nodes). If a Document' or Node's Tcl command is destroyed then the Document or Node is also destroyed.</p>
</div>
<div class="refsect1">
<h2>
<a name="idm47122586747600"></a>DOM Interfaces</h2>
<p>Each <em>Interface</em> in the DOM specification is implemented with a Tcl command in the <tt>dom</tt> namespace. A few interfaces have not been mapped to Tcl commands because Tcl already provides the required functionality, for example the <tt>CharacterData</tt> interface.</p>
<p><em>method</em>s for interfaces are methods (subcommands) of the corresponding Tcl command.</p>
<p>Each <em>attribute</em> of an interface is a configuration option for an object in the document tree.</p>
</div>
<div class="refsect1">
<h2>
<a name="idm47122586726352"></a>Convenience Commands and Methods</h2>
<p>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.</p>
<p>A major convenience is that each method of the <tt>DOMImplementation</tt> interface is also defined as a command. For example, rather than using <strong>dom::DOMImplementation create</strong> to create a new document, the shorter command <strong>dom::create</strong> may be used.</p>
<p>Implementations may also provide direct access to specific features. Refer to the documentation for a DOM implementation.</p>
</div>
<div class="refsect1">
<h2>
<a name="idm47122586720976"></a>Commands</h2>
<div class="refsect2">
<h3>
<a name="idm47122586719616"></a><strong>::dom::DOMImplementation</strong>
</h3>
<p>The <strong>::dom::DOMImplementation</strong> command implements the <tt>DOMImplementation</tt> DOM interface. It is used to provide implementation-specific features not explicitly defined in the DOM specification.</p>
<div class="refsect3">
<h4>
<a name="idm47122586716016"></a>Command Options</h4>
<p>The following command options may be used. These are also available as commands.</p>
<dl>
<span class="term"><span class="methodname">hasFeature</span></span><dd>
<div class="cmdsynopsis" id="idm47122586712512">
<a name="idm47122586712512"></a>hasFeature <em>feature</em>
</div>
<p>Provides a test for existence of a feature. Returns <span class="literal">1</span> if a feature is implemented, <span class="literal">0</span> otherwise.</p>
</dd>
<span class="term"><span class="methodname">create</span></span><dd>
<div class="cmdsynopsis" id="idm47122586707504">
<a name="idm47122586707504"></a>create <em>type</em>
</div>
<p>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 <strong>::dom::document</strong> command.</p>
<div class="note"><p>Non-standard method. DOM Level 2 introduced the <span class="methodname">createDocument</span> method.</p></div>
</dd>
<span class="term"><span class="methodname">createDocument</span></span><dd>
<div class="cmdsynopsis" id="idm47122586701168">
<a name="idm47122586701168"></a>createDocument <em>nsURI</em> <em>type</em> <em>doctype</em>
</div>
<p>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 <strong>::dom::document</strong> command.</p>
</dd>
<span class="term"><span class="methodname">createDocumentType</span></span><dd>
<div class="cmdsynopsis" id="idm47122586694352">
<a name="idm47122586694352"></a>createDocumentType <em>name</em> <em>publicid</em> <em>systemid</em> <em>internaldtd</em>
</div>
<p>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 <strong>::dom::documenttype</strong> command.</p>
</dd>
<span class="term"><span class="methodname">createNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586687120">
<a name="idm47122586687120"></a>createNode <em>token</em> <em>xpath</em>
</div>
<p>May create a node in the document. <em><em>token</em></em> specifies a context for the XPath expression given by <em><em>xpath</em></em>. 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.</p>
<div class="note"><p>Non-standard method.</p></div>
</dd>
<span class="term"><span class="methodname">destroy</span></span><dd>
<div class="cmdsynopsis" id="idm47122586680304">
<a name="idm47122586680304"></a>destroy <em>token</em>
</div>
<p>This method frees all data structures associated with a DOM document or node. The <em><em>token</em></em> argument must refer to a valid token for any document or any node in the tree of a document.</p>
<p>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.</p>
<p>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.</p>
</dd>
<span class="term"><span class="methodname">isNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586653904">
<a name="idm47122586653904"></a>isNode <em>token</em>
</div>
<p>Tests whether the given token is a valid token for some DOM node.</p>
<div class="note"><p>Non-standard method.</p></div>
</dd>
<span class="term"><span class="methodname">parse</span></span><dd>
<div class="cmdsynopsis" id="idm47122586649232">
<a name="idm47122586649232"></a>parse <em>xml</em> "<em>option</em> <em>value</em>"</div>
<p>This method parses XML formatted text given by the <em><em>xml</em></em> 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 <tt>createDocument</tt> method.</p>
<p>This method uses the <a href="http://tclxml.sourceforge.net/">TclXML</a> package to perform the parsing operation. The <tt>dom</tt> package itself does not include an XML parser. TclXML supports the use of multiple parser implementations. The <em>-parser</em> may be used to specify which XML parser class to use.</p>
<p>All options not listed below are passed to the TclXML parser.</p>
<p>Valid configuration options are:</p>
<dl>
<span class="term"><span class="arg">-baseuri</span> <span class="arg"><em>URI</em></span></span><dd>
<p>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.</p>
<p>If no Base URI is given then relative URIs are resolved in the current context, namely the current working directory.</p>
</dd>
<span class="term"><span class="arg">-parser</span> <span class="arg"> "<span class="arg">{}</span> | <span class="arg">libxml2</span> | <span class="arg">tcl</span>"</span></span><dd><p>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.</p></dd>
<span class="term"><span class="arg">-progresscommand</span> <span class="arg"><em>script</em></span></span><dd><p>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 <em>-chunksize</em> option.</p></dd>
<span class="term"><span class="arg">-chunksize</span> <span class="arg"><em>integer</em></span></span><dd><p>This option specifies how many element start tags to process before invoking the script given by the <em>-progresscommand</em> option.</p></dd>
</dl>
</dd>
<span class="term"><span class="methodname">selectNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586602864">
<a name="idm47122586602864"></a>selectNode <em>token</em> <em>xpath</em> ?option value...?</div>
<p>Resolves the XPath location path given by <em><em>xpath</em></em>. <em><em>token</em></em> is the initial context for the location path. Returns the resulting nodeset as a (static) Tcl list.</p>
<p>The following options may be specified:</p>
<dl>
<span class="term"> <em>-namespaces</em></span><dd>
<p>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.</p>
<p>This option may be repeated, in which case the lists of namespace pairs are merged and all of the XML Namespaces registered.</p>
</dd>
</dl>
<div class="note"><p>Non-standard method.</p></div>
</dd>
<span class="term"><span class="methodname">serialize</span></span><dd>
<div class="cmdsynopsis" id="idm47122586591600">
<a name="idm47122586591600"></a>serialize <em>token</em> "<em>option</em> <em>value</em>"</div>
<p>This method returns the XML formatted text corresponding to the node given by <em>token</em>. The text is guaranteed to be a well-formed XML document, unless the <em>-method</em> option specifies a non-XML output method.</p>
<p>Valid configuration options are:</p>
<dl>
<span class="term"><span class="arg">-method</span> <span class="arg">xml|html|text</span></span><dd><p>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 <span class="literal">xml</span> method produces output that conforms to the XML syntax. The <span class="literal">html</span> method produces output that conforms to HTML syntax. The <span class="literal">text</span> method serializes only the text nodes of the document and disables all output escaping.</p></dd>
<span class="term"><span class="arg">-indent</span> <span class="arg"><em>boolean</em></span></span><dd><p>Specifies that the output is to be "pretty-printed", ie. element content is indented to provide a visual indication of nesting levels.</p></dd>
<span class="term"><span class="arg">-encoding</span> <span class="arg"><em>encoding</em></span></span><dd><p>Specifies that the output is to be encoded using the given character encoding. If the encoding is <span class="literal">utf-8</span> (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).</p></dd>
<span class="term"><span class="arg">-newline</span> <span class="arg"><em>elementlist</em></span></span><dd>
<p>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 <span class="arg">-indent</span> option should be used instead.</p>
<p>White space is significant in XML, so the <tt>dom</tt> 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.</p>
<p>Examples:</p>
<p>Suppose the following DOM document is constructed:</p>
<div class="informalexample"><pre><div class="programlisting"><pre>
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
</pre></div></pre></div>
<p>Without the <em>-newline</em> option the serialized document would be:</p>
<div class="informalexample"><pre><div class="programlisting"><pre>
::dom::DOMImplementation serialize $doc
<div class="computeroutput"><pre>
<?xml version="1.0"?>
<!DOCTYPE Root>
<Root><First><Second/></First><First/></Root>
</pre></div>
</pre></div></pre></div>
<p>With the <em>-newline</em> option the serialized document would be:</p>
<div class="informalexample"><pre><div class="programlisting"><pre>
::dom::DOMImplementation serialize $doc -newline First
<div class="computeroutput"><pre>
<?xml version="1.0"?>
<!DOCTYPE Root>
<Root>
<First>
<Second/>
</First>
<First/>
</Root>
</pre></div>
</pre></div></pre></div>
</dd>
</dl>
</dd>
<span class="term"><span class="methodname">trim</span></span><dd>
<div class="cmdsynopsis" id="idm47122586563408">
<a name="idm47122586563408"></a>trim <em>token</em>
</div>
<p>This method removes any node containing only white space from the document tree of the node given by <em><em>token</em></em>.</p>
</dd>
</dl>
</div>
</div>
<div class="refsect2">
<h3>
<a name="idm47122586560096"></a><strong>::dom::document</strong>
</h3>
<p>This command implements the Document interface in the DOM specification. The most important aspect of this command are its factory methods for creating nodes.</p>
<p>The methods accepted by this command are as follows:</p>
<dl>
<span class="term"><span class="methodname">cget</span></span><dd>
<div class="cmdsynopsis" id="idm47122586555680">
<a name="idm47122586555680"></a><span class="methodname">cget</span><em>token</em> -option</div>
<p>This method returns the value of the given configuration option.</p>
</dd>
<span class="term"><span class="methodname">configure</span></span><dd>
<div class="cmdsynopsis" id="idm47122586677232">
<a name="idm47122586677232"></a><span class="methodname">configure</span><em>token</em> "<em>option</em> <em>value</em>..."</div>
<p>This method sets the value of the given configuration options.</p>
<p>Valid configuration options are:</p>
<dl>
<span class="term"><span class="arg">-doctype</span></span><dd>
<p>Specifies the token of the Document Type Declaration node.</p>
<p>This is a read-only option. Use the factory method to create a Document Type Declaration node.</p>
</dd>
<span class="term"><span class="arg">-documentElement</span></span><dd>
<p>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).</p>
<p>This is a read-only option. Use the factory method to create the document element node.</p>
</dd>
<span class="term"><span class="arg">-keep</span> <span class="arg">normal|implicit</span></span><dd>
<p>Specifies the memory management strategy for the document. The value <span class="arg">normal</span> specifies that the document must be explicitly destroyed in order for resources consumed by the document to be freed. The value <span class="arg">implicit</span> 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.</p>
<p>The default value is <span class="arg">implicit</span>.</p>
</dd>
<span class="term"><span class="arg">-implementation</span></span><dd>
<p>Specifies the token of the document's implementation.</p>
<p>This is a read-only option.</p>
</dd>
</dl>
</dd>
<span class="term"><span class="methodname">createElement</span></span><dd>
<div class="cmdsynopsis" id="idm47122586512288">
<a name="idm47122586512288"></a><span class="methodname">createElement</span><em>token</em> <em>type</em>
</div>
<p>This method creates an element node as a child of the given node specified by <em><em>token</em></em> and returns the new node's token as its result. <em><em>token</em></em> must be a node of type element, document or documentFragment. The new, child element is added as the last child of <em><em>token</em></em>'s list of children. The new element's type is given by the <em><em>type</em></em> argument. The new element is created with an empty attribute list.</p>
<p>A Tcl command is created with the same name as the new node's token. This command is a shortcut for the <strong>::dom::node</strong> command.</p>
</dd>
<span class="term"><span class="methodname">createElementNS</span></span><dd>
<div class="cmdsynopsis" id="idm47122586504176">
<a name="idm47122586504176"></a><span class="methodname">createElementNS</span><em>token</em> <em>nsuri</em> <em>qualname</em>
</div>
<p>This method creates an element node in an XML Namespace as a child of the given node specified by <em><em>token</em></em> and returns the new node's token as its result. <em><em>token</em></em> must be a node of type element, document or documentFragment. The new, child element is added as the last child of <em><em>token</em></em>'s list of children. The new element is created in the XML Namespace given by the namespace URI <em><em>nsuri</em></em>. The new element's qualifed name (QName) is given by the <em><em>qualname</em></em> argument. Qualified names have the form <span class="literal">prefix:local-part</span>. The new element is created with an empty attribute list.</p>
<p>A Tcl command is created with the same name as the new node's token. This command is a shortcut for the <strong>::dom::node</strong> command.</p>
</dd>
<span class="term"><span class="methodname">createDocumentFragment</span></span><dd>
<div class="cmdsynopsis" id="idm47122586494000">
<a name="idm47122586494000"></a><span class="methodname">createDocumentFragment</span><em>token</em>
</div>
<p>This method creates a documentFragment node as a child of the given node specified by <em><em>token</em></em> and returns the new node's token as its result. <em><em>token</em></em> must be a node of type element, document or documentFragment.</p>
<p>A Tcl command is created with the same name as the new node's token. This command is a shortcut for the <strong>::dom::node</strong> command.</p>
</dd>
<span class="term"><span class="methodname">createTextNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586487904">
<a name="idm47122586487904"></a><span class="methodname">createTextNode</span><em>token</em> <em>text</em>
</div>
<p>This method creates a textNode node as a child of the given node specified by <em><em>token</em></em> and returns the new node's token as its result. <em><em>token</em></em> must be a node of type element, document or documentFragment. The new, child textNode is added as the last child of <em><em>token</em></em>'s list of children. The new textNode is created with its value set to <em><em>text</em></em>.</p>
<p>A Tcl command is created with the same name as the new node's token. This command is a shortcut for the <strong>::dom::node</strong> command.</p>
</dd>
<span class="term"><span class="methodname">createComment</span></span><dd>
<div class="cmdsynopsis" id="idm47122586479792">
<a name="idm47122586479792"></a><span class="methodname">createComment</span><em>token</em> <em>data</em>
</div>
<p>This method creates a comment node as a child of the given node specified by <em><em>token</em></em> and returns the new node's token as its result. <em><em>token</em></em> must be a node of type element, document or documentFragment. The new, child comment is added as the last child of <em><em>token</em></em>'s list of children. The new comment is created with its value set to <em><em>data</em></em>.</p>
<p>A Tcl command is created with the same name as the new node's token. This command is a shortcut for the <strong>::dom::node</strong> command.</p>
</dd>
<span class="term"><span class="methodname">createCDATASection</span></span><dd>
<div class="cmdsynopsis" id="idm47122586471664">
<a name="idm47122586471664"></a><span class="methodname">createCDATASection</span><em>token</em> <em>text</em>
</div>
<p>TclDOM does not distinguish between textNodes and CDATASection nodes. Accordingly, this method creates a textNode node as a child of the given node specified by <em><em>token</em></em> and returns the new node's token as its result. <em><em>token</em></em> must be a node of type element, document or documentFragment. The new, child textNode is added as the last child of <em><em>token</em></em>'s list of children. The new node is created with its value set to <em><em>text</em></em> and has the attribute <em>-cdatasection</em> set to the value <span class="literal">1</span>.</p>
<p>A Tcl command is created with the same name as the new node's token. This command is a shortcut for the <strong>::dom::node</strong> command.</p>
</dd>
<span class="term"><span class="methodname">createProcessingInstruction</span></span><dd>
<div class="cmdsynopsis" id="idm47122586462576">
<a name="idm47122586462576"></a><span class="methodname">createProcessingInstruction</span><em>token</em> <em>target</em> <em>data</em>
</div>
<p>This method creates a processingInstruction node as a child of the given node specified by <em><em>token</em></em> and returns the new node's token as its result. <em><em>token</em></em> must be a node of type element, document or documentFragment. The new, child processingInstruction is added as the last child of <em><em>token</em></em>'s list of children. The new node is created with its name set to <em><em>target</em></em> and its value set to <em><em>data</em></em>.</p>
<p>A Tcl command is created with the same name as the new node's token. This command is a shortcut for the <strong>::dom::node</strong> command.</p>
</dd>
<span class="term"><span class="methodname">createAttribute</span></span><dd>
<div class="cmdsynopsis" id="idm47122586452976">
<a name="idm47122586452976"></a><span class="methodname">createAttribute</span><em>token</em> <em>name</em>
</div>
<p>This method creates an attribute node for the given element specified by <em><em>token</em></em> and returns the new node's token as its result. <em><em>token</em></em> must be a node of type element. The new attribute is created with its name set to <em><em>name</em></em> and an empty value.</p>
<p>A Tcl command is created with the same name as the new node's token. This command is a shortcut for the <strong>::dom::node</strong> command.</p>
<div class="note"><p>This method is included for completeness with respect to the DOM specification. The preferred method for setting element attributes is to use the <strong>::dom::element</strong> command.</p></div>
</dd>
<span class="term"><span class="methodname">createEntity</span></span><dd>
<div class="cmdsynopsis" id="idm47122586444048">
<a name="idm47122586444048"></a><span class="methodname">createEntity</span><em>token</em>
</div>
<p>Not currently implemented.</p>
</dd>
<span class="term"><span class="methodname">createEntityReference</span></span><dd>
<div class="cmdsynopsis" id="idm47122586440176">
<a name="idm47122586440176"></a><span class="methodname">createEntityReference</span><em>token</em> <em>name</em>
</div>
<p>Not currently implemented.</p>
</dd>
<span class="term"><span class="methodname">createEvent</span></span><dd>
<div class="cmdsynopsis" id="idm47122586435424">
<a name="idm47122586435424"></a><span class="methodname">createEvent</span><em>token</em> <em>name</em>
</div>
<p>This method creates an event node in the document specified by <em><em>token</em></em> and returns the new node's token as its result. <em><em>token</em></em> must be a node of type document. The event type is specified by <em><em>name</em></em>.</p>
<p>A Tcl command is created with the same name as the new node's token. This command is a shortcut for the <strong>::dom::event</strong> command.</p>
</dd>
<span class="term"><span class="methodname">getElementsByTagName</span></span><dd>
<div class="cmdsynopsis" id="idm47122586427936">
<a name="idm47122586427936"></a><span class="methodname">getElementsByTagName</span><em>token</em> <em>name</em>
</div>
<p>This method searches the node given by the argument <em><em>token</em></em> for child elements with a type matching the argument <em><em>name</em></em>. The name <span class="literal">*</span> matches all elements. All descendants of <em><em>token</em></em> are searched. This method returns a "live-list"; the return result of this method is the name of a Tcl variable, the content of which is a Tcl list containing tokens for all elements that match.</p>
</dd>
<span class="term"><span class="methodname">dtd</span></span><dd>
<div class="cmdsynopsis" id="idm47122586420912">
<a name="idm47122586420912"></a><span class="methodname">dtd</span>validate</div>
<p>This method performs DTD validation upon the document. If the method returns successfully, then the document is valid. Otherwise the document is invalid and the error returned contains the reason.</p>
</dd>
<span class="term"><span class="methodname">relaxng</span></span><dd>
<div class="cmdsynopsis" id="idm47122586417296">
<a name="idm47122586417296"></a><span class="methodname"><em>submethod</em></span> ?<em>args</em>...?</div>
<p>This method performs RELAX NG Schema validation upon the document. RELAX NG Schema validation is performed in two steps. First the document is compiled into a schema document. Second, the schema document is used to schema-validate an instance document.</p>
<p>Example:</p>
<div class="informalexample"><pre><div class="programlisting"><pre>
set schema [dom::parse $XML]
$schema relaxng compile
set instance [dom::parse $XML2]
$schema relaxng validate $instance
</pre></div></pre></div>
<p>If the document is changed after compiling, then schema document must be recompiled.</p>
</dd>
<span class="term"><span class="methodname">schema</span></span><dd>
<div class="cmdsynopsis" id="idm47122586410208">
<a name="idm47122586410208"></a><span class="methodname"><em>submethod</em></span> ?<em>args</em>...?</div>
<p>This method performs XML Schema validation upon the document. Schema validation is performed in two steps. First the document is compiled into a schema document. Second, the schema document is used to schema-validate an instance document.</p>
<p>Example:</p>
<div class="informalexample"><pre><div class="programlisting"><pre>
set schema [dom::parse $XML]
$schema schema compile
set instance [dom::parse $XML2]
$schema schema validate $instance
</pre></div></pre></div>
<p>If the document is changed after compiling, then schema document must be recompiled.</p>
</dd>
</dl>
</div>
<div class="refsect2">
<h3>
<a name="idm47122586404272"></a><strong>dom::node</strong>
</h3>
<p>This command implements generic functions for DOM nodes.</p>
<p>The methods accepted by this command are as follows:</p>
<dl>
<span class="term"><span class="methodname">cget</span></span><dd>
<div class="cmdsynopsis" id="idm47122586399776">
<a name="idm47122586399776"></a><span class="methodname">cget</span><em>token</em> option</div>
<p>This method returns the value of the given configuration option for the node given by <em><em>token</em></em>.</p>
</dd>
<span class="term"><span class="methodname">configure</span></span><dd>
<div class="cmdsynopsis" id="idm47122586394880">
<a name="idm47122586394880"></a><span class="methodname">configure</span><em>token</em> "<em>option</em> <em>value</em>..."</div>
<p>This method sets the value of the given configuration option for the node given by <em><em>token</em></em>.</p>
<p>Valid configuration options are as follows:</p>
<dl>
<span class="term"><span class="arg">-nodeName</span></span><dd>
<p>Returns the node name. This is a read-only option.</p>
<p>The DOM specification gives the meaning of names for different types of nodes. For example, the <em>-nodeName</em> option of an element node is the element type.</p>
</dd>
<span class="term"><span class="arg">-nodeType</span></span><dd><p>Returns the type of the node given by <em><em>token</em></em>. This is a read-only option.</p></dd>
<span class="term"> <em>-parentNode</em></span><dd><p>Returns the parent node of the node given by <em><em>token</em></em>. This is a read-only option.</p></dd>
<span class="term"> <em>-childNodes</em></span><dd><p>Returns the name of a Tcl variable which contains a list of the children of the node given by <em><em>token</em></em>. The variable contains the "live" list of children. This is a read-only option.</p></dd>
<span class="term"> <em>-firstChild</em></span><dd><p>Returns the first child node of the node given by <em><em>token</em></em>. This is a read-only option.</p></dd>
<span class="term"> <em>-lastChild</em></span><dd><p>Returns the last child node of the node given by <em><em>token</em></em>. This is a read-only option.</p></dd>
<span class="term"> <em>-previousSibling</em></span><dd><p>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.</p></dd>
<span class="term"> <em>-nextSibling</em></span><dd><p>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.</p></dd>
<span class="term"> <em>-attributes</em></span><dd><p>Returns the name of 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.</p></dd>
<span class="term"> <em>-nodeValue</em><span class="arg"><em>data</em></span></span><dd><p>Specifies the value of a node. The DOM specification gives the meaning of values for different types of nodes. For example, the <em>-nodeValue</em> option of a textNode node is the node's text.</p></dd>
<span class="term"> <em>-id</em></span><dd><p>Read-only. Returns a unique identifier for the node. The same identifier is always returned for the same node.</p></dd>
</dl>
</dd>
<span class="term"><span class="methodname">insertBefore</span></span><dd>
<div class="cmdsynopsis" id="idm47122586359808">
<a name="idm47122586359808"></a><span class="methodname">insertBefore</span><em>token</em> <em>newchild</em> <em>refchild</em>
</div>
<p>This method removes the node given by <em><em>newchild</em></em> from its parent. If no <em><em>refchild</em></em> argument is given then <em><em>newchild</em></em> is appended to <em><em>token</em></em>'s list of children. If the <em><em>refchild</em></em> argument is given then this method adds <em><em>newchild</em></em> as a child of <em><em>token</em></em>. The new child node is positioned before the node <em><em>refchild</em></em> in <em><em>token</em></em>'s list of children. Returns an empty string.</p>
</dd>
<span class="term"><span class="methodname">replaceChild</span></span><dd>
<div class="cmdsynopsis" id="idm47122586348992">
<a name="idm47122586348992"></a><span class="methodname">replaceChild</span><em>token</em> <em>newchild</em> <em>oldchild</em>
</div>
<p>This method removes the node given by <em><em>newchild</em></em> from its parent. It then also removes the node given by <em><em>oldchild</em></em> from <em><em>token</em></em>. <em><em>newchild</em></em> is then added as a child of <em><em>token</em></em> in <em><em>oldchild</em></em>'s original position in the list of children. The method returns the token <em><em>oldchild</em></em>, which will now have no parent.</p>
</dd>
<span class="term"><span class="methodname">removeChild</span></span><dd>
<div class="cmdsynopsis" id="idm47122586339536">
<a name="idm47122586339536"></a><span class="methodname">removeChild</span><em>token</em> <em>oldchild</em>
</div>
<p>This method removes the node given by <em><em>oldchild</em></em> from its parent, <em><em>token</em></em>. The method returns the token <em><em>oldchild</em></em>, which will now have no parent.</p>
</dd>
<span class="term"><span class="methodname">appendChild</span></span><dd>
<div class="cmdsynopsis" id="idm47122586333152">
<a name="idm47122586333152"></a><span class="methodname">appendChild</span><em>token</em> <em>newchild</em>
</div>
<p>This method removes the node given by <em><em>newchild</em></em> from its parent. <em><em>newchild</em></em> is then appended to the end of the list of children for node <em><em>token</em></em>. The method returns the token <em><em>newchild</em></em>.</p>
</dd>
<span class="term"><span class="methodname">hasChildNodes</span></span><dd>
<div class="cmdsynopsis" id="idm47122586326224">
<a name="idm47122586326224"></a><span class="methodname">hasChildNodes</span><em>token</em>
</div>
<p>Returns <span class="literal">1</span> if the given node has any child nodes, <span class="literal">0</span> otherwise.</p>
</dd>
<span class="term"><span class="methodname">isSameNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586321600">
<a name="idm47122586321600"></a><span class="methodname">isSameNode</span><em>token</em> <em>ref</em>
</div>
<p>Returns <span class="literal">1</span> if the given node is the same node as the node given by the <span class="arg"><span class="literal">ref</span></span> token, <span class="literal">0</span> otherwise.</p>
</dd>
<span class="term"><span class="methodname">cloneNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586315568">
<a name="idm47122586315568"></a><span class="methodname">cloneNode</span><em>token</em> <em>deep</em>
</div>
<p>This method makes a copy the node given by <em><em>token</em></em>. If the argument <em><em>deep</em></em> is not specified or has the value <span class="literal">0</span> then only the node itself is copied, not its children. If the argument <em><em>deep</em></em> has the value <span class="literal">1</span> then <em><em>token</em></em>'s children are also copied recursively. This method returns the token of the newly created node. This new node will have no parent.</p>
</dd>
<span class="term"><span class="methodname">children</span></span><dd>
<div class="cmdsynopsis" id="idm47122586307456">
<a name="idm47122586307456"></a><span class="methodname">children</span><em>token</em>
</div>
<p>This is a convenience method which returns the list of child nodes for the given node as a (static) Tcl list.</p>
<p>This is not a standard DOM method for this interface.</p>
</dd>
<span class="term"><span class="methodname">parent</span></span><dd>
<div class="cmdsynopsis" id="idm47122586550560">
<a name="idm47122586550560"></a><span class="methodname">parent</span><em>token</em>
</div>
<p>This is a convenience method which returns the parent node for the given node.</p>
<p>This is not a standard DOM method for this interface.</p>
</dd>
<span class="term"><span class="methodname">path</span></span><dd>
<div class="cmdsynopsis" id="idm47122586546224">
<a name="idm47122586546224"></a><span class="methodname">path</span><em>token</em>
</div>
<p>Returns a Tcl list of the ancestor nodes of the given node, starting with the root node.</p>
<p>This is not a standard DOM method for this interface.</p>
</dd>
<span class="term"><span class="methodname">createNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586541872">
<a name="idm47122586541872"></a><span class="methodname">createNode</span><em>token</em> <em>xpath</em>
</div>
<p>May create nodes in order to satisfy the given XPath location path. The initial context for the location path is the node <span class="arg"><em>token</em></span>. For more detail, see the <strong>::dom::createNode</strong> command.</p>
<p>This is not a standard DOM method for this interface.</p>
</dd>
<span class="term"><span class="methodname">selectNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586535520">
<a name="idm47122586535520"></a><span class="methodname">selectNode</span><em>token</em> <em>xpath</em>
</div>
<p>Returns a (static) Tcl list of nodes selected by the XPath location path <span class="arg"><em>xpath</em></span>. The initial context for the location path is the node <span class="arg"><em>token</em></span>. For more detail, see the <strong>::dom::selectNode</strong> command.</p>
<p>This is not a standard DOM method for this interface.</p>
</dd>
<span class="term"><span class="methodname">stringValue</span></span><dd>
<div class="cmdsynopsis" id="idm47122586528624">
<a name="idm47122586528624"></a><span class="methodname">stringValue</span><em>token</em>
</div>
<p>Returns the string value of the node given by <span class="arg"><em>token</em></span>. The string value of a node is defined by the XPath specification: for element nodes it is the concatenation of the string values of all descendant text nodes, for text nodes it is the node's character data value, for attribute nodes it is the attribute value, for comment nodes it is the comment data and for processing instruction nodes it is the PI data.</p>
<p>This is not a standard DOM method for this interface.</p>
</dd>
<span class="term"><span class="methodname">addEventListener</span></span><dd>
<div class="cmdsynopsis" id="idm47122586523408">
<a name="idm47122586523408"></a><span class="methodname">addEventListener</span><em>token</em> <em>type</em> <em>listener</em> ?option value...?</div>
<p>Register an event listener for the node given by <span class="arg"><em>token</em></span> listening for events of type <span class="arg"><em>type</em></span>. The event mechanism functions as described in the W3C DOM Level 2 Event module.</p>
<p>When an event of type <span class="arg"><em>type</em></span> occurs the script <span class="arg"><em>listener</em></span> is evaluated, in the global context. The token of the event node is appended to the script.</p>
<p>If the <span class="arg"><em>listener</em></span> argument is omitted then the listener for the given event type is returned.</p>
<p>Valid options are:</p>
<dl>
<span class="term"><span class="arg">-usecapture</span> <span class="arg"><em>boolean</em></span></span><dd><p>If true the listener is triggered in the event capturing phase. If false the listener is triggered in the event bubbling phase.</p></dd>
</dl>
</dd>
<span class="term"><span class="methodname">removeEventListener</span></span><dd>
<div class="cmdsynopsis" id="idm47122586220672">
<a name="idm47122586220672"></a><span class="methodname">removeEventListener</span><em>token</em> <em>type</em> <em>listener</em> ?option value...?</div>
<p>Removes an event listener previously registered for the node given by <span class="arg"><em>token</em></span> listening for events of type <span class="arg"><em>type</em></span>.</p>
<p>Valid options are:</p>
<dl>
<span class="term"><span class="arg">-usecapture</span> <span class="arg"><em>boolean</em></span></span><dd><p>If true the capturing listener is removed. If false the bubbling listener is removed.</p></dd>
</dl>
</dd>
<span class="term"><span class="methodname">dispatchEvent</span></span><dd>
<div class="cmdsynopsis" id="idm47122586208608">
<a name="idm47122586208608"></a><span class="methodname">dispatchEvent</span><em>token</em> <em>event</em>
</div>
<p>Dispatches the event given by <span class="arg"><em>event</em></span> with target node <span class="arg"><em>token</em></span>. The event mechanism functions as described in the W3C DOM Level 2 Event module. The event enters the capturing phase first, followed by the bubbling phase. During each phase any event listeners registered for the same event type as the event <span class="arg"><em>event</em></span> are triggered; their script is evaluated. Unless the script invokes the <tt>stopPropagation</tt> method of the <strong>dom::event</strong> command, all registered event listeners will be triggered. The order in which listeners registered at a particular node for a particular phase are triggered is undefined.</p>
</dd>
</dl>
</div>
<div class="refsect2">
<h3>
<a name="idm47122586201920"></a><strong>dom::element</strong>
</h3>
<p>This command provides functions for element type nodes.</p>
<p>Valid methods for this command are as follows:</p>
<dl>
<span class="term"><span class="methodname">cget</span></span><dd>
<div class="cmdsynopsis" id="idm47122586197536">
<a name="idm47122586197536"></a><span class="methodname">cget</span><em>token</em> <em>option</em>
</div>
<p>This method returns the current setting of configuration options for an element. See the <span class="methodname">configure</span> method for the list of valid configuration options.</p>
</dd>
<span class="term"><span class="methodname">configure</span></span><dd>
<div class="cmdsynopsis" id="idm47122586192304">
<a name="idm47122586192304"></a><span class="methodname">configure</span><em>token</em> "<em>option</em> <em>value</em>..."</div>
<p>This method sets configuration options for an element. Note that element type nodes only have read-only options.</p>
<p>Valid configuration options are as follows:</p>
<dl>
<span class="term"> <em>-tagName</em><span class="arg"><em>name</em></span></span><dd>The tag name, or element type, of this element.</dd>
<span class="term"> <em>-empty</em><span class="arg"><em>boolean</em></span></span><dd>
<p>Sets whether this element was specified as an empty element when the document was parsed. That is, XML empty element syntax such as <span class="literal"><Empty/></span> was used.</p>
<p>This option has no effect upon output (serialization) of the XML document. Empty element syntax is automatically used where appropriate.</p>
</dd>
</dl>
</dd>
<span class="term"><span class="methodname">getAttribute</span></span><dd>
<div class="cmdsynopsis" id="idm47122586179120">
<a name="idm47122586179120"></a><span class="methodname">getAttribute</span><em>token</em> <em>name</em>
</div>
<p>This method returns the attribute value of the attribute given by <em><em>name</em></em>. If the attribute does not exist, then an empty string is returned.</p>
</dd>
<span class="term"><span class="methodname">setAttribute</span></span><dd>
<div class="cmdsynopsis" id="idm47122586173776">
<a name="idm47122586173776"></a><span class="methodname">setAttribute</span><em>token</em> <em>name</em> <em>value</em>
</div>
<p>This method sets the attribute value of the attribute given by <em><em>name</em></em>. If the attribute already exists then its value is replaced, otherwise the attribute is created.</p>
</dd>
<span class="term"><span class="methodname">removeAttribute</span></span><dd>
<div class="cmdsynopsis" id="idm47122586167520">
<a name="idm47122586167520"></a><span class="methodname">removeAttribute</span><em>token</em> <em>name</em>
</div>
<p>This method deletes the attribute given by <em><em>name</em></em>. If the attribute does not exist then the method has no effect.</p>
</dd>
<span class="term"><span class="methodname">getAttributeNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586162160">
<a name="idm47122586162160"></a><span class="methodname">getAttributeNode</span><em>token</em> <em>name</em>
</div>
<p>Not implemented.</p>
</dd>
<span class="term"><span class="methodname">setAttributeNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586157392">
<a name="idm47122586157392"></a><span class="methodname">setAttributeNode</span><em>token</em> <em>name</em>
</div>
<p>Not implemented.</p>
</dd>
<span class="term"><span class="methodname">removeAttributeNode</span></span><dd>
<div class="cmdsynopsis" id="idm47122586152624">
<a name="idm47122586152624"></a><span class="methodname">removeAttributeNode</span><em>token</em> <em>name</em>
</div>
<p>Not implemented.</p>
</dd>
<span class="term"><span class="methodname">getAttributeNS</span></span><dd>
<div class="cmdsynopsis" id="idm47122586147888">
<a name="idm47122586147888"></a><span class="methodname">getAttributeNS</span><em>token</em> <em>ns</em> <em>name</em>
</div>
<p>This method returns the attribute value of the attribute given by <em><em>name</em></em> in the XML namespace <span class="arg"><em>ns</em></span>. If the attribute does not exist, then an empty string is returned.</p>
</dd>
<span class="term"><span class="methodname">setAttributeNS</span></span><dd>
<div class="cmdsynopsis" id="idm47122586141120">
<a name="idm47122586141120"></a><span class="methodname">setAttributeNS</span><em>token</em> <em>ns</em> <em>name</em> <em>value</em>
</div>
<p>This method sets the attribute value of the attribute given by <em><em>name</em></em> in the XML namespace <span class="arg"><em>ns</em></span>. If the attribute already exists then its value is replaced, otherwise the attribute is created.</p>
</dd>
<span class="term"><span class="methodname">removeAttributeNS</span></span><dd>
<div class="cmdsynopsis" id="idm47122586133408">
<a name="idm47122586133408"></a><span class="methodname">removeAttributeNS</span><em>token</em> <em>ns</em> <em>name</em>
</div>
<p>This method deletes the attribute given by <em><em>name</em></em> in the XML namespace <span class="arg"><em>ns</em></span>. If the attribute does not exist then the method has no effect.</p>
</dd>
<span class="term"><span class="methodname">getElementsByTagName</span></span><dd>
<div class="cmdsynopsis" id="idm47122586126592">
<a name="idm47122586126592"></a><span class="methodname">getElementsByTagName</span><em>token</em> <em>name</em>
</div>
<p>This method searches the node given by the argument <em><em>token</em></em> for descendant child elements with a type matching the argument <em><em>name</em></em>. The wildcard character <span class="literal">*</span> matches any element type. The return result is a "live-list" which is represented by a Tcl variable. This method returns the name of the Tcl variable that contains the list of tokens that match.</p>
</dd>
<span class="term"><span class="methodname">normalize</span></span><dd>
<div class="cmdsynopsis" id="idm47122586120080">
<a name="idm47122586120080"></a><span class="methodname">normalize</span><em>token</em>
</div>
<p>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.</p>
</dd>
</dl>
</div>
<div class="refsect2">
<h3>
<a name="idm47122586117104"></a><strong>dom::processinginstruction</strong>
</h3>
<p>This command provides functions for processingInstruction type nodes.</p>
<p>Valid methods for this command are as follows:</p>
<dl>
<span class="term"><span class="methodname">cget</span></span><dd>
<div class="cmdsynopsis" id="idm47122586112656">
<a name="idm47122586112656"></a><span class="methodname">cget</span><em>token</em> <em>option</em>
</div>
<p>This method returns the current setting of configuration options for an element. See the <span class="methodname">configure</span> method for the list of valid configuration options.</p>
</dd>
<span class="term"><span class="methodname">configure</span></span><dd>
<div class="cmdsynopsis" id="idm47122586107424">
<a name="idm47122586107424"></a><span class="methodname">configure</span><em>token</em> "<em>option</em> <em>value</em>..."</div>
<p>This method sets configuration options for a processing instruction.</p>
<p>Valid configuration options are as follows:</p>
<dl>
<span class="term"> <em>-target</em><span class="arg"><em>name</em></span></span><dd>This option sets the target of the processing instruction. This is a read-only configuration option.</dd>
<span class="term"> <em>-data</em><span class="arg"><em>data</em></span></span><dd><p>This option sets the data of the processing instruction.</p></dd>
</dl>
</dd>
</dl>
</div>
<div class="refsect2">
<h3>
<a name="idm47122586096288"></a><strong>dom::event</strong>
</h3>
<p>This command provides functions for event type nodes.</p>
<p>Valid methods for this command are as follows:</p>
<dl>
<span class="term"><span class="methodname">cget</span></span><dd>
<div class="cmdsynopsis" id="idm47122586091904">
<a name="idm47122586091904"></a><span class="methodname">cget</span><em>token</em>
</div>
<p>This method retrieves configuration options for an event.</p>
<p>Valid configuration options are as follows:</p>
<dl>
<span class="term"> <em>-altKey</em></span><dd>This option determines whether the ALT modifier key has been specified for this event.</dd>
<span class="term"> <em>-attrName</em></span><dd>This option gives the name of the attribute associated with this event.</dd>
<span class="term"> <em>-bubbles</em></span><dd>This option determines whether the event uses the bubbling phase.</dd>
<span class="term"> <em>-button</em></span><dd>This option gives the button pressed for this event.</dd>
<span class="term"> <em>-cancelable</em></span><dd>This option determines whether the event may be cancelled.</dd>
<span class="term"> <em>-clientX</em></span><dd>This option gives the window X coordinate for this event.</dd>
<span class="term"> <em>-clientY</em></span><dd>This option gives the window Y coordinate for this event.</dd>
<span class="term"> <em>-ctrlKey</em></span><dd>This option determines whether the control modifier key has been specified for this event.</dd>
<span class="term"> <em>-currentNode</em></span><dd>The current node of the capturing or bubbling phase.</dd>
<span class="term"> <em>-detail</em></span><dd>This option gives an additional information item for the event, for example the key that was pressed or the button number.</dd>
<span class="term"> <em>-eventPhase</em></span><dd>The current phase of the event.</dd>
<span class="term"> <em>-metaKey</em></span><dd>This option determines whether the META modifier key has been specified for this event.</dd>
<span class="term"> <em>-newValue</em></span><dd>This option gives the new value of a node.</dd>
<span class="term"> <em>-prevValue</em></span><dd>This option gives the previous value of a node.</dd>
<span class="term"> <em>-relatedNode</em></span><dd>This option gives a related node for this event. See the W3C DOM Level 2 Event module specification for further details.</dd>
<span class="term"> <em>-screenX</em></span><dd>This option gives the screen X coordinate for this event.</dd>
<span class="term"> <em>-screenY</em></span><dd>This option gives the screen Y coordinate for this event.</dd>
<span class="term"> <em>-shiftKey</em></span><dd>This option determines whether the shift modifier key has been specified for this event.</dd>
<span class="term"> <em>-target</em></span><dd>The node that is the target of this event.</dd>
<span class="term"> <em>-timeStamp</em></span><dd>
<p>This option gives the time at which the event was posted. The value is the number of milliseconds since the epoch, which is compatible with the Tcl <strong>clock</strong> command. </p>
<div class="note">The implementation of this method depends on the <span class="methodname">Tcl_GetTime</span> function.This function only became publically available in Tcl 8.4. If a version of Tcl prior to 8.4 is being used, then this option will have the value <span class="literal">0</span>.</div>
</dd>
<span class="term"> <em>-type</em></span><dd>The type of this event.</dd>
<span class="term"> <em>-view</em></span><dd>This option gives whether the view of the event.</dd>
</dl>
</dd>
<span class="term"><span class="methodname">configure</span></span><dd>
<div class="cmdsynopsis" id="idm47122586049360">
<a name="idm47122586049360"></a><span class="methodname">configure</span><em>token</em> "<em>option</em> <em>value</em>..."</div>
<p>This method sets the configuration options for an event. However, all event options are read-only. See the <span class="methodname">cget</span> method for the list of valid configuration options.</p>
</dd>
<span class="term"><span class="methodname">stopPropagation</span></span><dd>
<div class="cmdsynopsis" id="idm47122586042720">
<a name="idm47122586042720"></a><span class="methodname">stopPropagation</span><em>token</em>
</div>
<p>This method cancels further propagation of the event.</p>
<div class="note">Invoking this method does not prevent event listeners at the current node from being triggered.</div>
</dd>
<span class="term"><span class="methodname">preventDefault</span></span><dd>
<div class="cmdsynopsis" id="idm47122586038368">
<a name="idm47122586038368"></a><span class="methodname">preventDefault</span><em>token</em>
</div>
<p>This method stops the default action for this event from occurring.</p>
</dd>
<span class="term"><span class="methodname">initEvent</span></span><dd>
<div class="cmdsynopsis" id="idm47122586034496">
<a name="idm47122586034496"></a><span class="methodname">initEvent</span><em>token</em> <em>type</em> <em>bubbles</em> <em>cancelable</em>
</div>
<p>Initialise the event.</p>
<p><span class="arg"><em>type</em></span> gives the type of the event. Any of the event types defined by the W3C DOM Level 2 Event module may be specified, or a user-defined event type may be used instead.</p>
<p><span class="arg"><em>bubbles</em></span> indicates whether the event will enter the bubbling phase after the capturing phase. <span class="arg"><em>cancelable</em></span> indicates whether the event may be cancelled.</p>
</dd>
<span class="term"><span class="methodname">initUIEvent</span></span><dd>
<div class="cmdsynopsis" id="idm47122586025648">
<a name="idm47122586025648"></a><span class="methodname">initUIEvent</span><em>token</em> <em>type</em> <em>bubbles</em> <em>cancelable</em> <em>view</em> <em>detail</em>
</div>
<p>Initialise a user interface event. See <tt>initEvent</tt> for further information.</p>
<p><span class="arg"><em>view</em></span> gives the view for the event (not supported by TclDOM). <span class="arg"><em>detail</em></span> provides extra data for the event.</p>
</dd>
<span class="term"><span class="methodname">initMouseEvent</span></span><dd>
<div class="cmdsynopsis" id="idm47122586015552">
<a name="idm47122586015552"></a><span class="methodname">initMouseEvent</span><em>token</em> <em>type</em> <em>bubbles</em> <em>cancelable</em> <em>view</em> <em>detail</em> <em>screenX</em> <em>screenY</em> <em>clientX</em> <em>clientY</em> <em>ctrlKey</em> <em>altKey</em> <em>shiftKey</em> <em>metaKey</em> <em>button</em> <em>relatedNode</em>
</div>
<p>Initialise a mouse event. See <tt>initUIEvent</tt> for further information.</p>
<p><span class="arg"><em>screenX</em></span> and <span class="arg"><em>screenY</em></span> give the coordinates at which the event occurred relative to the screen. <span class="arg"><em>screenX</em></span> and <span class="arg"><em>screenY</em></span> give the coordinates at which the event occurred relative to the window.</p>
<p><span class="arg"><em>ctrlKey</em></span>, <span class="arg"><em>altKey</em></span>, <span class="arg"><em>shiftKey</em></span>, <span class="arg"><em>metaKey</em></span> indicate whether the respective modifier key was pressed when the event occurred.</p>
<p><span class="arg"><em>button</em></span> indicates which button, if any, was pressed when the event occurred.</p>
<p><span class="arg"><em>relatedNode</em></span> specifies that a DOM node is associated with the event.</p>
</dd>
<span class="term"><span class="methodname">initMutationEvent</span></span><dd>
<div class="cmdsynopsis" id="idm47122585991456">
<a name="idm47122585991456"></a><span class="methodname">initMutationEvent</span><em>token</em> <em>type</em> <em>bubbles</em> <em>cancelable</em> <em>relatedNode</em> <em>prevValue</em> <em>newValue</em> <em>attrName</em>
</div>
<p>Initialise a tree mutation event event. See <tt>initEvent</tt> for further information.</p>
<p><span class="arg"><em>relatedNode</em></span> specifies a DOM node to associate with the event. <span class="arg"><em>prevValue</em></span> gives the previous value of the node. <span class="arg"><em>newValue</em></span> gives the new value of the node. <span class="arg"><em>attrName</em></span> gives the name of the attribute where the event is modifying an attribute value.</p>
</dd>
<span class="term"><span class="methodname">postUIEvent</span></span><dd>
<div class="cmdsynopsis" id="idm47122585978400">
<a name="idm47122585978400"></a><span class="methodname">postUIEvent</span><em>token</em> <em>type</em> ?option <em>value</em>...?</div>
<p>Non-standard convenience method that handles posting an user interface event with <span class="arg"><em>token</em></span> as the target node. This method performs the following functions:</p>
<ol>
<li><p>Create an event node,</p></li>
<li><p>Initialise the event node (using default values where required),</p></li>
<li><p>Dispatch the event,</p></li>
<li><p>Destroy the event node.</p></li>
</ol>
<p><span class="arg"><em>type</em></span> gives the event type.</p>
<p>The following options are valid:</p>
<dl>
<span class="term"> <em>-bubbles</em></span><dd><p>Indicates whether the event bubbles.</p></dd>
<span class="term"> <em>-cancelable</em></span><dd><p>Indicates whether the event can be cancelled.</p></dd>
<span class="term"> <em>-view</em></span><dd><p>The view.</p></dd>
<span class="term"> <em>-detail</em></span><dd><p>Extra data for the event.</p></dd>
</dl>
</dd>
<span class="term"><span class="methodname">postMouseEvent</span></span><dd>
<div class="cmdsynopsis" id="idm47122585958016">
<a name="idm47122585958016"></a><span class="methodname">postMouseEvent</span><em>token</em> <em>type</em> ?option <em>value</em>...?</div>
<p>Non-standard convenience method that handles posting a mouse event with <span class="arg"><em>token</em></span> as the target node. This method performs the following functions:</p>
<ol>
<li><p>Create an event node,</p></li>
<li><p>Initialise the event node (using default values where required),</p></li>
<li><p>Dispatch the event,</p></li>
<li><p>Destroy the event node.</p></li>
</ol>
<p><span class="arg"><em>type</em></span> gives the event type.</p>
<p>The following options are valid:</p>
<dl>
<span class="term"> <em>-bubbles</em></span><dd><p>Indicates whether the event bubbles.</p></dd>
<span class="term"> <em>-cancelable</em></span><dd><p>Indicates whether the event can be cancelled.</p></dd>
<span class="term"> <em>-view</em></span><dd><p>The view.</p></dd>
<span class="term"> <em>-detail</em></span><dd><p>Extra data for the event.</p></dd>
<span class="term"> <em>-screenX</em></span><dd><p>Gives the screen X coordinate.</p></dd>
<span class="term"> <em>-screenY</em></span><dd><p>Gives the screen Y coordinate.</p></dd>
<span class="term"> <em>-clientX</em></span><dd><p>Gives the window X coordinate.</p></dd>
<span class="term"> <em>-clientY</em></span><dd><p>Gives the window Y coordinate.</p></dd>
<span class="term"> <em>-ctrlKey</em></span><dd><p>Indicates whether the control modifier key was pressed.</p></dd>
<span class="term"> <em>-altKey</em></span><dd><p>Indicates whether the ALT modifier key was pressed.</p></dd>
<span class="term"> <em>-shiftKey</em></span><dd><p>Indicates whether the shift modifier key was pressed.</p></dd>
<span class="term"> <em>-metaKey</em></span><dd><p>Indicates whether the meta modifier key was pressed.</p></dd>
<span class="term"> <em>-button</em></span><dd><p>Gives the button pressed.</p></dd>
<span class="term"> <em>-relatedNode</em></span><dd><p>Gives a node to associate with the event.</p></dd>
</dl>
</dd>
<span class="term"><span class="methodname">postMutationEvent</span></span><dd>
<div class="cmdsynopsis" id="idm47122585917456">
<a name="idm47122585917456"></a><span class="methodname">postMutationEvent</span><em>token</em> <em>type</em> ?option <em>value</em>...?</div>
<p>Non-standard convenience method that handles posting a mutation event with <span class="arg"><em>token</em></span> as the target node. This method performs the following functions:</p>
<ol>
<li><p>Create an event node,</p></li>
<li><p>Initialise the event node (using default values where required),</p></li>
<li><p>Dispatch the event,</p></li>
<li><p>Destroy the event node.</p></li>
</ol>
<p><span class="arg"><em>type</em></span> gives the event type.</p>
<p>The following options are valid:</p>
<dl>
<span class="term"> <em>-bubbles</em></span><dd><p>Indicates whether the event bubbles.</p></dd>
<span class="term"> <em>-cancelable</em></span><dd><p>Indicates whether the event can be cancelled.</p></dd>
<span class="term"> <em>-relatedNode</em></span><dd><p>Gives a node to associate with the event.</p></dd>
<span class="term"> <em>-prevValue</em></span><dd><p>Gives the previous value of the target node.</p></dd>
<span class="term"> <em>-newValue</em></span><dd><p>Gives the new value of the target node.</p></dd>
<span class="term"> <em>-attrName</em></span><dd><p>Gives the name of the attribute modified.</p></dd>
</dl>
</dd>
</dl>
</div>
</div>
<div class="refsect1">
<h2>
<a name="idm47122585893904"></a>Errors</h2>
<p>If an operation results in an error condition, an error message is returned as a structured Tcl list. The list has members as follows:</p>
<div class="informalexample"><pre><div class="programlisting"><pre>{domain level code node line message int1 int2 string1 string2 string3}</pre></div></pre></div>
<p>The format of the list is described in the TclXML manual page.</p>
</div>
<div class="refsect1">
<h2>
<a name="idm47122585890384"></a>Implementations</h2>
<p>This section documents the various implmentations of the TclDOM API.</p>
<div class="refsect2">
<h3>
<a name="idm47122585888464"></a>Tcl Implementation</h3>
<p>The Tcl implementation is provided by the <tt>dom::tcl</tt> package.</p>
<div class="refsect3">
<h4>
<a name="idm47122585886144"></a>Limitations</h4>
<p>This implementation is not able to preform the following functions:</p>
<ul>
<li><p>Validation: DTD, XML Schema or RelaxNG validation are not supported.</p></li>
<li><p>Character encodings: The TclDOM/tcl implementation itself does not handle character encodings other than utf-8. Character encodings are handled by Tcl itself.</p></li>
</ul>
</div>
</div>
<div class="refsect2">
<h3>
<a name="idm47122585881792"></a>libxml2 Implementation</h3>
<p>The TclDOM/libxml2 implementation is a wrapper for the <a href="http://xmlsoft.org/">Gnome libxml2 library</a>. It is provided by the <tt>dom::libxml2</tt> package. It is a high-performance library, making use of Tcl objects for fast access to tree nodes.</p>
<div class="refsect3">
<h4>
<a name="idm47122585878192"></a>Limitations</h4>
<ul>
<li><p>The TclXML/libxml2 parser must be used to parse an XML document. It is not possible to use any other parser class.</p></li>
<li><p>The importNode method has not been implemented.</p></li>
</ul>
</div>
</div>
</div>
</div></body>
</html>
|