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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>XML Support For Tcl</title>
<link rel="stylesheet" href="tclxml.css">
</head>
<body><div class="article">
<h1 class="title"><a name="id18406">XML Support For Tcl</a></h1>
<h3>TclXML, TclDOM and TclXSLT</h3>
<h2>Contents</h2>
<ul>
<li><a href="#id18498">TclXML</a></li>
<li><a href="#id18546">TclDOM</a></li>
<li><a href="#id18594">TclXSLT</a></li>
<li>
<a href="#id18619">Installation</a><ul>
<li><a href="#id18633">Dependencies</a></li>
<li><a href="#id18747">Pure-Tcl Installation</a></li>
<li>
<a href="#id18776">Compiled Installation</a><ul>
<li><a href="#id18786">Unix/Linux</a></li>
<li><a href="#id18948">Windows (MSYS/MINGW)</a></li>
<li><a href="#id18987">Windows (NMAKE/VC++ 6.0)</a></li>
<li><a href="#id19109">Macintosh OS X</a></li>
</ul>
</li>
</ul>
</li>
<li>
<a href="#id19193">Usage</a><ul>
<li><a href="#id19216">Parsing XML, Streaming</a></li>
<li><a href="#id19244">Parsing XML with DOM</a></li>
<li><a href="#id19268">Transforming XML with XSLT</a></li>
</ul>
</li>
<li><a href="#id19306">XPath</a></li>
</ul>
<h3>TclXML, TclDOM and TclXSLT</h3>
<p>This package provides XML parsers, DOM scripting and XSL Transformations for <a href="http://www.tcl.tk">Tcl</a>. In previous distributions, these features were supplied as separate packages. Now they have been combined into a single package to make installation easier.</p>
<p>Contact <a href="mailto:Steve.Ball@explain.com.au">Steve Ball</a> for information about this release.</p>
<div class="section">
<h3>
<a name="id18498"></a>TclXML</h3>
<p>TclXML provides a streaming parser for XML documents. This is the lowest-level interface for processing XML documents in Tcl. The package has a generic front-end interface with plugin parser implementations. A number of parser implementations or wrappers are provided:</p>
<ul>
<li><p>Gnome libxml2 library. This package is known as TclXML/libxml2.</p></li>
<li><p>A generic Tcl implementation (which does not require compilation). This package is known as TclXML/tcl.</p></li>
</ul>
<p>Both of these implementations may be installed at the same time. See <a href="doc/tclxml.html">the manual page</a> for more information.</p>
</div>
<div class="section">
<h3>
<a name="id18546"></a>TclDOM</h3>
<p>TclDOM provides a tree view for XML documents. This is usually the best interface for scripting XML documents using Tcl. The package has two implementations:</p>
<ul>
<li><p>Gnome libxml2 library. This package is known as TclDOM/libxml2.</p></li>
<li><p>A generic Tcl implementation (which does not require compilation). This package is known as TclDOM/tcl.</p></li>
</ul>
<p>Only one of these will be installed.</p>
<p>See <a href="doc/tcldom.html">the manual page</a> for more information.</p>
</div>
<div class="section">
<h3>
<a name="id18594"></a>TclXSLT</h3>
<p>TclXSLT provides a method to invoke XSL Transformations upon XML documents. This package is a wrapper for the libxslt library.</p>
<p>See <a href="doc/tclxslt.html">the manual page</a> for more information.</p>
</div>
<div class="section">
<h3>
<a name="id18619"></a>Installation</h3>
<div class="section">
<h4>
<a name="id18633"></a>Dependencies</h4>
<dl>
<span class="term">Tcllib</span><dd>
<p><a href="http://www.tcl.tk/software/tcllib/">http://www.tcl.tk/software/tcllib/</a></p>
<p>In order for the Tcl-only parser to resolve external entities, the tcllib package must be installed.</p>
<p>Be sure to get a version which includes the <tt>uri</tt> package. Version 1.11 or better is recommended.</p>
<ul>
<li><p><a href="ftp://prdownloads.sf.net/tcllib/tcllib-1.11.tar.gz">GZip'd tarball</a></p></li>
<li><p><a href="ftp://prdownloads.sf.net/tcllib/tcllib-1.11.zip">ZIP file</a></p></li>
</ul>
<p>The latest CVS snapshot may be found at <a href="http://sourceforge.net/projects/tcllib">the SourceForge project page</a>.</p>
</dd>
<span class="term">libxml2</span><dd>
<p>libxml2 is required for the compiled version of the TclXML/libxml2 package. libiconv may also be required.</p>
<p>The source code for libxml2 and libiconv is <em>not</em> supplied with this package. Download libxml2 from <a href="http://xmlsoft.org/">xmlsoft.org</a> separately. libiconv may also be required; download from a GNU mirror site.</p>
<p>Version 2.7.2 (or better) is recommended.</p>
</dd>
</dl>
</div>
<div class="section">
<h4>
<a name="id18747"></a>Pure-Tcl Installation</h4>
<h3>no compilation required</h3>
<p>Run the configure script and invoke the command:</p>
<div class="informalexample"><pre><strong>make install</strong></pre></div>
<p>If the pure-Tcl parser is good enough for you, then read no further.</p>
</div>
<div class="section">
<h4>
<a name="id18776"></a>Compiled Installation</h4>
<div class="section">
<h5>
<a name="id18786"></a>Unix/Linux</h5>
<p>You must have Tcl/Tk version 8.2 or better installed on your system. Tcl/Tk 8.3 or better is recommended.</p>
<ol>
<li><p>Make sure you have Tcllib 1.11 (or better) installed. Tcllib is still required, even for the compiled parser.</p></li>
<li><p>If you wish to use TclXML/libxml2, make sure libxml2-2.7.2 (or better) is installed.</p></li>
<li><p>Unpack the TclXML distribution and <strong>cd</strong> into the <tt>tclxml-3.2</tt> directory.</p></li>
<li>
<p>Run the <tt>configure</tt> script, with the <span class="arg">--prefix</span> and <span class="arg">--enable-threads</span> switches (the latter only if Tcl has been built with threads enabled). Use the <span class="arg">--with-xml2-config</span> switch to specify the location of the libxml2 configuration script, <tt>xml2Conf.sh</tt>. Similarly, use the <span class="arg">--with-xslt-config</span> if necessary.</p>
<p>TclXML/libxml2 may be configured to statically link the libxml2 and libxslt libraries to the libtclxml.so shared library. This is advantageous when using TclXML/libxml2 in a StarKit. To statically link the libraries use the <span class="arg">--with-xml-static</span> switch.</p>
<p>For example, on my system I have Tcl 8.5 installed in <tt>/usr/local/tcl8.5</tt> and libxm2 installed in <tt>/usr/local/gnome</tt>. I also need to statically link the libraries. Therefore I would use the command:</p>
<div class="programlisting"><pre>./configure --prefix=/usr/local/tcl8.5 --enable-threads --with-xml2-config=/usr/local/gnome/bin/xml2Conf.sh --with-xml-static=1</pre></div>
</li>
<li><div class="programlisting"><pre>make</pre></div></li>
<li><div class="note">Don't test the package using <span class="literal">make test</span> until all of the packages are installed (it is a current deficiency of the build system that the package cannot be tested before installation - we hope to fix this soon!).</div></li>
<li>
<div class="programlisting"><pre>make install</pre></div>
<p>You may need to do this as root, depending on your installation.</p>
</li>
<li><div class="programlisting"><pre>make test</pre></div></li>
<li><div class="programlisting"><pre>make doc</pre></div></li>
<li><div class="programlisting"><pre>make install-doc</pre></div></li>
</ol>
</div>
<div class="section">
<h5>
<a name="id18948"></a>Windows (MSYS/MINGW)</h5>
<div class="note">[Advice: ActiveTcl includes binaries for TclXML.]</div>
<p>You must have Tcl/Tk version 8.2 or better installed on your system. Tcl/Tk 8.5.5 or better is recommended.</p>
<p>Before starting, download the binaries for libxml2 (or build them from source). <a href="http://xmlsoft.org/">xmlsoft</a> has a link to the MS Windows binary distribution.</p>
<p>If you have a TEA build environment setup, just use the normal <span class="literal">configure/make/make install</span> pattern.</p>
</div>
<div class="section">
<h5>
<a name="id18987"></a>Windows (NMAKE/VC++ 6.0)</h5>
<div class="note">TclXML/libxml2 is built with MSYS/MINGW, see above, so this build system is untested.</div>
<p>Alternatively, the <tt>win</tt> subdirectory contains a <tt>makefile.vc</tt> file for Visual Studio C++ v6.0. In a Command Prompt window set up your environment so that <tt>nmake</tt> is on the path (by running <tt>VCVARS32.BAT</tt>), then type the following:</p>
<div class="informalexample"><pre><div class="programlisting"><pre>nmake -f makefile.vc TCLDIR=<em>C:\Path\To\Tcl</em> INSTALLDIR=<em>C:\Path\To\Tcl</em> LIBZDIR=<em>C:\Path\To\libz</em> LIBICONVDIR=<em>C:\Path\To\libiconv</em> LIBXML2DIR=<em>C:\Path\To\libxml2</em> LIBXSLTDIR=<em>C:\Path\To\libxslt</em></pre></div></pre></div>
<p>As an example, on my system I have Tcl installed in <tt>C:\Tcl</tt> and the libxml2 and libxslt binaries unpacked in the directory <tt>C:\gnome</tt>. Accordingly, I would use the following command line:</p>
<div class="informalexample"><pre><div class="programlisting"><pre>nmake -f makefile.vc TCLDIR=C:\Tcl INSTALLDIR=C:\Tcl LIBZDIR=C:\gnome\zlib-1.1.4.win32 LIBICONVDIR=C:\gnome\libiconv-1.9.1.win32 LIBXML2DIR=C:\gnome\libxml2-2.7.2.win32 LIBXSLTDIR=C:\gnome\libxslt-1.1.24.win32</pre></div></pre></div>
<p>Install the package by appending 'install' to the command line used above, for example:</p>
<div class="informalexample"><pre><div class="programlisting"><pre>nmake -f makefile.vc TCLDIR=<em>C:\Path\To\Tcl</em> INSTALLDIR=<em>C:\Path\To\Tcl</em> LIBZDIR=<em>C:\Path\To\libz</em> LIBICONVDIR=<em>C:\Path\To\libiconv</em> LIBXML2DIR=<em>C:\Path\To\libxml2</em> LIBXSLTDIR=<em>C:\Path\To\libxslt</em> install</pre></div></pre></div>
</div>
<div class="section">
<h5>
<a name="id19109"></a>Macintosh OS X</h5>
<div class="note">Binary distributions of libxml2, libxslt and TclXML as frameworks are provided by <a href="http://www.explain.com.au/oss/">Explain</a>.</div>
<p>There are two ways to build TclXML under Mac OS X:</p>
<ol>
<li><p>The usual Unix way, see above.</p></li>
<li><p>As an embedded Framework using Xcode.</p></li>
</ol>
<p>The <tt>macosx</tt> directory contains the Xcode files for building under OS X (Leopard/Panther). TclXML/libxml2 has been tested on OS X 10.5 (or is that X.5?).</p>
<p>Start-up the project. Make sure that the references to the libxml2 and Tcl external frameworks are correct. Select the 'Make' target and build. This builds everything. The result is two Mac OS X Frameworks; a "normal" and an "embedded". The embedded framework will be in the <tt>embedded</tt> subdirectory of the Build Products directory. Copy <tt>tclxml.framework</tt> to any of the usual places for frameworks (<tt>~/Library/Frameworks</tt>, <tt>/Library/Frameworks</tt>, etc).</p>
<p>For earlier version of OS X using Project Builder, you will have to retrieve a previous version of the Project Builder files from the CVS repository.</p>
</div>
</div>
</div>
<div class="section">
<h3>
<a name="id19193"></a>Usage</h3>
<p>See <a href="http://tclxml.sourceforge.net/">the website</a> for links to tutorials and the reference manual.</p>
<p>In the meantime, here's a quick tutorial:</p>
<div class="section">
<h4>
<a name="id19216"></a>Parsing XML, Streaming</h4>
<p>This is the lowest-level access to an XML document; use SAX-like events to stream through the document. The simple program below counts the number of characters in the content of an XML document.</p>
<div class="programlisting"><pre>
package require xml 3.2
set parser [xml::parser]
$parser configure -elementstartcommand EStart \
-characterdatacommand PCData
proc EStart {tag attlist args} {
array set attr $attlist
puts "Element \"$tag\" started with [array size attr] attributes"
}
proc PCData text {
incr ::count [string length $text]
}
set count 0
$parser parse [read stdin]
puts "The document contains $count characters"
exit 0
</pre></div>
</div>
<div class="section">
<h4>
<a name="id19244"></a>Parsing XML with DOM</h4>
<p>This is the next level up in accessing an XML document; use the Document Object Model (DOM) to view the XML document as a tree. The simple program below counts the number of characters in the content of an XML document.</p>
<div class="programlisting"><pre>
package require xml 3.2
set doc [dom::parse [read stdin]]
set count 0
foreach textNode [dom::selectNode $doc //text()] {
incr count [string length [$textNode cget -nodeValue]]
}
puts "The document contains $count characters"
</pre></div>
</div>
<div class="section">
<h4>
<a name="id19268"></a>Transforming XML with XSLT</h4>
<p>This is the highest level in processing an XML document; use a XSL stylesheet to transform a XML document. The simple program below reads two XML documents, compiles one into a XSL stylesheet and performs the transformation.</p>
<div class="programlisting"><pre>
package require xml 3.2
set chan [open "count.xsl"]
set styleDoc [dom::parse [read $chan]]
close $chan
set sourceDoc [dom::parse [read stdin]]
set style [xslt::compile $styleDoc]
set resultDoc [$style transform $sourceDoc]
puts [dom::serialize $resultDoc]
</pre></div>
<p>The XSL stylesheet <tt>count.xsl</tt>, which counts the number of characters in the source document, looks like this:</p>
<div class="programlisting"><pre>
<xsl:stylesheet version='1.0'
xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
<xsl:template match='/'>
<xsl:text>The document contains </xsl:text>
<xsl:call-template name='add'>
<xsl:with-param name='nodes' select='//text()'/>
</xsl:call-template>
<xsl:text> characters.
</xsl:text>
</xsl:template>
<xsl:template name='add'>
<xsl:param name='sum' select='0'/>
<xsl:param name='nodes' select='/..'/>
<xsl:choose>
<xsl:when test='not($nodes)'>
<xsl:value-of select='$sum'/>
</xsl:when>
<xsl:otherwise>
<xsl:call-template name='add'>
<xsl:with-param name='sum'
select='$sum + string-length($nodes[1])'/>
<xsl:with-param name='nodes'
select='$nodes[position() != 1]'/>
</xsl:call-template>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>
</pre></div>
</div>
</div>
<div class="section">
<h3>
<a name="id19306"></a>XPath</h3>
<p>In addition to XML parsing packages, TclXML also provides a package for parsing XPath location paths. The XPath package only parsing the path's syntax, it does interpret the path. See <a href="http://tclxml.sourceforge.net/tcldom.html">TclDOM</a> for a package that will interpret XPath location paths.</p>
<div class="note">This package is in its infancy, and does not support the full range of XPath features. Only a very limited subset of location paths are supported, of the form "/simple/example[2]". Paths within predicates will definitely fail.</div>
<p>To use the XPath package:</p>
<div class="programlisting"><pre>
package require xpath
</pre></div>
<p>To parse a location path:</p>
<div class="programlisting"><pre>
xpath::split {/simple/example}
</pre></div>
<p>This returns a Tcl list, each element of which is a three element sublist: {axis node-test {?predicate ...?}}.</p>
</div>
</div></body>
</html>
|
