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
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>XML Support For Tcl</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id614537"></a>XML Support For Tcl</h1></div><div><h3 class="subtitle"><i>TclXML</i></h3></div><div><div class="author"><h3 class="author"><span class="firstname">Steve</span> <span class="surname">Ball</span></h3><div class="affiliation"><span class="orgname">Explain<br></span><div class="address"><p><br>
<span class="otheraddr"><br>
<a href="http://www.explain.com.au/" target="_top">www.explain.com.au</a><br>
</span><br>
</p></div></div></div></div><div><p class="releaseinfo">$Id: README.xml,v 1.6 2004/07/11 03:15:33 balls Exp $</p></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 3.1</td><td align="left"></td></tr></table></div></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#installation">Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#id681943">Dependencies</a></span></dt><dt><span class="section"><a href="#id682076">Pure-Tcl Installation</a></span></dt><dt><span class="section"><a href="#id682109">Compiled Installation</a></span></dt></dl></dd><dt><span class="section"><a href="#id682545">Usage</a></span></dt><dt><span class="section"><a href="#id682565">XPath</a></span></dt></dl></div><p>This package provides XML parsers for Tcl scripts. There is a generic front-end interface with plugin parser implementations. A number of parser implementations or wrappers are provided:</p><div class="itemizedlist"><ul type="disc"><li><p>James Clark's expat library. This package is known as TclXML/expat.</p></li><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></div><p>The package defines commands in the <tt class="tclnamespace">::xml</tt> Tcl namespace:</p><div class="variablelist"><dl><dt><span class="term"><span><b class="command">xml::parserclass [info] [names]</b></span></span></dt><dd></dd><dt><span class="term"><span><b class="command">xml::parser</b></span></span></dt><dd></dd></dl></div><p>Other packages are also supplied to provide support for related standards. In particular, work has commenced on the 'xpath' package for parsing XPath location paths.</p><p>See <a href="http://tclxml.sourceforge.net/" target="_top">the website</a> for more information on XML support for Tcl.</p><p>Contact <a href="mailto:Steve.Ball@explain.com.au" target="_top">Steve Ball</a> for information about this release.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="installation"></a>Installation</h2></div></div><div></div></div><p>TclXML v3.1 features a pure-Tcl installer.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Future work on the installer will include an 'uninstall' capability, as well as the capability to build the binary libraries in the package from the source.</div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id681943"></a>Dependencies</h3></div></div><div></div></div><div class="variablelist"><dl><dt><span class="term">Tcllib</span></dt><dd><p><a href="http://www.tcl.tk/software/tcllib/" target="_top">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 class="tclpackage">uri</tt> package. Version 1.2 or better is recommended.</p><div class="itemizedlist"><ul type="disc"><li><p><a href="ftp://prdownloads.sf.net/tcllib/tcllib-1.3.tar.gz" target="_top">GZip'd tarball</a></p></li><li><p><a href="ftp://prdownloads.sf.net/tcllib/tcllib-1.3.zip" target="_top">ZIP file</a></p></li></ul></div><p>The latest CVS snapshot may be found at <a href="http://sourceforge.net/projects/tcllib" target="_top">the SourceForge project page</a>.</p></dd><dt><span class="term">Expat</span></dt><dd><p>Expat is only required for the compiled version of the TclXML/expat package.</p><p>TclXML/expat requires expat v0.2, with modifications by Ajuba Solutions. This is now supplied in the <tt class="filename">expat</tt> subdirectory of this distribution and will maintained until TclXML has been resynchronised with the Expat SourceForge project (volunteer needed!).</p></dd><dt><span class="term">libxml2</span></dt><dd><p>libxml2 is only 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 <span class="emphasis"><em>not</em></span> supplied with this package. Download libxml2 from <a href="http://xmlsoft.org/" target="_top">xmlsoft.org</a> separately, and libiconv from a GNU mirror site.</p><p>Version 2.6.9 (or better) is recommended.</p></dd></dl></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id682076"></a>Pure-Tcl Installation</h3></div><div><h4 class="subtitle">no compilation required</h4></div></div><div></div></div><p>The <tt class="filename">install.tcl</tt> script will install the pure-Tcl parser. Run it using <span class="application">wish</span>, eg.</p><pre class="programlisting">wish install.tcl</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>If Tcl/Tk has been configured correctly on your system, you should be able to simply double-click the script.</div><p>If the pure-Tcl parser is good enough for you, then read no further.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id682109"></a>Compiled Installation</h3></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id682114"></a>Unix/Linux</h4></div></div><div></div></div><p>You must have Tcl/Tk version 8.2 or better installed on your system. Tcl/Tk 8.3 or better is recommended.</p><div class="orderedlist"><ol type="1"><li><p>Make sure you have Tcllib 1.2 (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.6.9 (or better) is installed.</p></li><li><p>Unpack the TclXML distribution and <span><b class="command">cd</b></span> into the <tt class="filename">tclxml-3.1</tt> directory.</p></li><li><p>Run the <tt class="filename">configure</tt> script, with the [--prefix] and [--enable-threads] switches (the latter only if Tcl has been built with threads enabled). For example, on my system I have Tcl 8.4 installed in <tt class="filename">/usr/local/tcl8.4</tt> so I would use the command:</p><pre class="programlisting">./configure --prefix=/usr/local/tcl8.4 --enable-threads</pre></li><li><pre class="programlisting">make</pre></li><li><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Don't test the package using <tt class="literal">make test</tt> until all of the packages are installed (it is a current deficiency of the build system that the individual modules cannot be tested before installation - we hope to fix this soon!).</div></li><li><pre class="programlisting">make install</pre><p>You may need to do this as root. This installs the pure-Tcl parser class, as well as support files required for the next step.</p></li><li><pre class="programlisting">cd expat</pre><p>Now TclXML/expat is about to be built.</p></li><li><p>Use exactly the same configure command from step (4) above.</p></li><li><pre class="programlisting">make</pre></li><li><pre class="programlisting">make install</pre><p>You may need to do this as root. This installs the expat parser class.</p></li><li><pre class="programlisting">cd ../libxml2</pre><p>Now TclXML/libxml2 is about to be built. Remember, you must have built and installed libxml2 first.</p></li><li><p>Use exactly the same configure command from step (4) above.</p></li><li><pre class="programlisting">make</pre></li><li><pre class="programlisting">make install</pre><p>You may need to do this as root. This installs the libxml2 parser class.</p></li><li><pre class="programlisting">cd ..; make test</pre></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id682293"></a>Windows (MS VC++)</h4></div></div><div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>[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.3 or better is recommended.</p><p>Before starting, download the binaries for libxml2 (or build them from source). <a href="http://xmlsoft.org/" target="_top">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 <tt class="literal">configure/make/make install</tt> pattern.</p><p>Alternatively, the <tt class="filename">win</tt> subdirectory contains a <tt class="filename">makefile.vc</tt> file for Visual Studio C++ v6.0. This makefile builds both the expat and libxml2 parser classes. In a Command Prompt window set up your environment so that <span class="application">nmake</span> is on the path (by running <tt class="filename">VCVARS32.BAT</tt>), then type the following:</p><div class="informalexample"><pre class="programlisting">nmake -f makefile.vc TCLDIR=<i class="replaceable"><tt>C:\Path\To\Tcl</tt></i> INSTALLDIR=<i class="replaceable"><tt>C:\Path\To\Tcl</tt></i> LIBZDIR=<i class="replaceable"><tt>C:\Path\To\libz</tt></i> LIBICONVDIR=<i class="replaceable"><tt>C:\Path\To\libiconv</tt></i> LIBXML2DIR=<i class="replaceable"><tt>C:\Path\To\libxml2</tt></i></pre></div><p>As an example, on my system I have Tcl installed in <tt class="filename">C:\Tcl</tt> and the libxml2 binaries unpacked in the directory <tt class="filename">C:\gnome</tt>. Accordingly, I would use the following command line:</p><div class="informalexample"><pre class="programlisting">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.6.9.win32</pre></div><p>Install the package by appending 'install' to the command line used above, for example:</p><div class="informalexample"><pre class="programlisting">nmake -f makefile.vc TCLDIR=<i class="replaceable"><tt>C:\Path\To\Tcl</tt></i> INSTALLDIR=<i class="replaceable"><tt>C:\Path\To\Tcl</tt></i> LIBZDIR=<i class="replaceable"><tt>C:\Path\To\libz</tt></i> LIBICONVDIR=<i class="replaceable"><tt>C:\Path\To\libiconv</tt></i> LIBXML2DIR=<i class="replaceable"><tt>C:\Path\To\libxml2</tt></i> install</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id682422"></a>Macintosh OS X</h4></div></div><div></div></div><p>There are two ways to build TclXML under Mac OS X:</p><div class="orderedlist"><ol type="1"><li><p>The usual Unix way, see above.</p></li><li><p>As an embedded Framework using Xcode.</p></li></ol></div><p>The <tt class="filename">macosx</tt> directory contains the Xcode files for building under OS X (Panther). TclXML has been tested on OS X 10.3 (or is that X.3?).</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 six Mac OS X Frameworks; three "normal" and three "embedded". The embedded frameworks will be in the <tt class="filename">embedded</tt> subdirectory of the Build Products directory. Copy <tt class="filename">tclxml.framework</tt>, <tt class="filename">TclXMLlibxml2.framework</tt> and <tt class="filename">expat.framework</tt> to any of the usual places for frameworks (<tt class="filename">~/Library/Frameworks</tt>, <tt class="filename">/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 class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id682499"></a>Macintosh OS 9 (or earlier)</h4></div></div><div></div></div><p>The installer script doesn't work properly on Macintosh yet, and the binary parsers have not been ported yet (sorry).</p><p>Since the distribution has an all-Tcl parser, you can get a working parser fairly easily.</p><p>Copy the <tt class="filename">library</tt> folder to the Tcl library folder in the Extensions folder of the System folder.</p><p>Rename the <tt class="filename">library</tt> folder to <tt class="filename">tclxml3.1</tt>. This isn't strictly necessary, but it helps keep things organised.</p><p>You're on your own as far as the demos, programs and documentation go.</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id682545"></a>Usage</h2></div></div><div></div></div><p>See the website for links to tutorials and the reference manual.</p><p>In the meantime, here's a quick tutorial:</p><pre class="programlisting">
package require xml
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 contained $count characters"
exit 0
</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id682565"></a>XPath</h2></div></div><div></div></div><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" target="_top">TclDOM</a> for a package that will interpret XPath location paths.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>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><pre class="programlisting">
package require xpath
</pre><p>To parse a location path:</p><pre class="programlisting">
xpath::split {/simple/example}
</pre><p>This returns a Tcl list, each element of which is a three element sublist: {axis node-test {?predicate ...?}}.</p></div></div></body></html>
|
