diff options
Diffstat (limited to 'tclxml/README.md')
-rw-r--r-- | tclxml/README.md | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/tclxml/README.md b/tclxml/README.md new file mode 100644 index 0000000..7419da1 --- /dev/null +++ b/tclxml/README.md @@ -0,0 +1,356 @@ +### TclXML, TclDOM and TclXSLT + +Contents +-------- + +- [TclXML](#id18498) +- [TclDOM](#id18546) +- [TclXSLT](#id18594) +- [Installation](#id18619) + - [Dependencies](#id18633) + - [Pure-Tcl Installation](#id18747) + - [Compiled Installation](#id18776) + - [Unix/Linux](#id18786) + - [Windows (MSYS/MINGW)](#id18948) + - [Windows (NMAKE/VC++ 6.0)](#id18987) + - [Macintosh OS X](#id19109) +- [Usage](#id19193) + - [Parsing XML, Streaming](#id19216) + - [Parsing XML with DOM](#id19244) + - [Transforming XML with XSLT](#id19268) +- [XPath](#id19306) + +### TclXML, TclDOM and TclXSLT + +This package provides XML parsers, DOM scripting and XSL Transformations +for [Tcl](http://www.tcl.tk). In previous distributions, these features +were supplied as separate packages. Now they have been combined into a +single package to make installation easier. + +Contact [Steve Ball](mailto:Steve.Ball@explain.com.au) for information +about this release. + +### TclXML + +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: + +- Gnome libxml2 library. This package is known as TclXML/libxml2. + +- A generic Tcl implementation (which does not require compilation). + This package is known as TclXML/tcl. + +Both of these implementations may be installed at the same time. See +[the manual page](doc/tclxml.html) for more information. + +### TclDOM + +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: + +- Gnome libxml2 library. This package is known as TclDOM/libxml2. + +- A generic Tcl implementation (which does not require compilation). + This package is known as TclDOM/tcl. + +Only one of these will be installed. + +See [the manual page](doc/tcldom.html) for more information. + +### TclXSLT + +TclXSLT provides a method to invoke XSL Transformations upon XML +documents. This package is a wrapper for the libxslt library. + +See [the manual page](doc/tclxslt.html) for more information. + +### Installation + +#### Dependencies + +Tcllib + +[http://www.tcl.tk/software/tcllib/](http://www.tcl.tk/software/tcllib/) + +In order for the Tcl-only parser to resolve external entities, the +tcllib package must be installed. + +Be sure to get a version which includes the `uri` package. Version 1.11 +or better is recommended. + +- [GZip'd tarball](ftp://prdownloads.sf.net/tcllib/tcllib-1.11.tar.gz) + +- [ZIP file](ftp://prdownloads.sf.net/tcllib/tcllib-1.11.zip) + +The latest CVS snapshot may be found at [the SourceForge project +page](http://sourceforge.net/projects/tcllib). + +libxml2 + +libxml2 is required for the compiled version of the TclXML/libxml2 +package. libiconv may also be required. + +The source code for libxml2 and libiconv is *not* supplied with this +package. Download libxml2 from [xmlsoft.org](http://xmlsoft.org/) +separately. libiconv may also be required; download from a GNU mirror +site. + +Version 2.7.2 (or better) is recommended. + +#### Pure-Tcl Installation + +### no compilation required + +Run the configure script and invoke the command: + + make install + +If the pure-Tcl parser is good enough for you, then read no further. + +#### Compiled Installation + +##### Unix/Linux + +You must have Tcl/Tk version 8.2 or better installed on your system. +Tcl/Tk 8.3 or better is recommended. + +1. Make sure you have Tcllib 1.11 (or better) installed. Tcllib is + still required, even for the compiled parser. + +2. If you wish to use TclXML/libxml2, make sure libxml2-2.7.2 (or + better) is installed. + +3. Unpack the TclXML distribution and **cd** into the `tclxml-3.2` + directory. + +4. Run the `configure` script, with the --prefix and --enable-threads + switches (the latter only if Tcl has been built with threads + enabled). Use the --with-xml2-config switch to specify the location + of the libxml2 configuration script, `xml2Conf.sh`. Similarly, use + the --with-xslt-config if necessary. + + 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 --with-xml-static switch. + + For example, on my system I have Tcl 8.5 installed in + `/usr/local/tcl8.5` and libxm2 installed in `/usr/local/gnome`. I + also need to statically link the libraries. Therefore I would use + the command: + + ./configure --prefix=/usr/local/tcl8.5 --enable-threads --with-xml2-config=/usr/local/gnome/bin/xml2Conf.sh --with-xml-static=1 + +5. make + +6. Don't test the package using make test 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!). +7. make install + + You may need to do this as root, depending on your installation. + +8. make test + +9. make doc + +10. make install-doc + +##### Windows (MSYS/MINGW) + +[Advice: ActiveTcl includes binaries for TclXML.] + +You must have Tcl/Tk version 8.2 or better installed on your system. +Tcl/Tk 8.5.5 or better is recommended. + +Before starting, download the binaries for libxml2 (or build them from +source). [xmlsoft](http://xmlsoft.org/) has a link to the MS Windows +binary distribution. + +If you have a TEA build environment setup, just use the normal +configure/make/make install pattern. + +##### Windows (NMAKE/VC++ 6.0) + +TclXML/libxml2 is built with MSYS/MINGW, see above, so this build system +is untested. + +Alternatively, the `win` subdirectory contains a `makefile.vc` file for +Visual Studio C++ v6.0. In a Command Prompt window set up your +environment so that `nmake` is on the path (by running `VCVARS32.BAT`), +then type the following: + + nmake -f makefile.vc TCLDIR=C:\Path\To\Tcl INSTALLDIR=C:\Path\To\Tcl LIBZDIR=C:\Path\To\libz LIBICONVDIR=C:\Path\To\libiconv LIBXML2DIR=C:\Path\To\libxml2 LIBXSLTDIR=C:\Path\To\libxslt + +As an example, on my system I have Tcl installed in `C:\Tcl` and the +libxml2 and libxslt binaries unpacked in the directory `C:\gnome`. +Accordingly, I would use the following command line: + + 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 + +Install the package by appending 'install' to the command line used +above, for example: + + nmake -f makefile.vc TCLDIR=C:\Path\To\Tcl INSTALLDIR=C:\Path\To\Tcl LIBZDIR=C:\Path\To\libz LIBICONVDIR=C:\Path\To\libiconv LIBXML2DIR=C:\Path\To\libxml2 LIBXSLTDIR=C:\Path\To\libxslt install + +##### Macintosh OS X + +Binary distributions of libxml2, libxslt and TclXML as frameworks are +provided by [Explain](http://www.explain.com.au/oss/). + +There are two ways to build TclXML under Mac OS X: + +1. The usual Unix way, see above. + +2. As an embedded Framework using Xcode. + +The `macosx` 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?). + +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 +`embedded` subdirectory of the Build Products directory. Copy +`tclxml.framework` to any of the usual places for frameworks +(`~/Library/Frameworks`, `/Library/Frameworks`, etc). + +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. + +### Usage + +See [the website](http://tclxml.sourceforge.net/) for links to tutorials +and the reference manual. + +In the meantime, here's a quick tutorial: + +#### Parsing XML, Streaming + +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. + + 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 + +#### Parsing XML with DOM + +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. + + 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" + + +#### Transforming XML with XSLT + +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. + + 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] + + +The XSL stylesheet `count.xsl`, which counts the number of characters in +the source document, looks like this: + + <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> + +### XPath + +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 +[TclDOM](http://tclxml.sourceforge.net/tcldom.html) for a package that +will interpret XPath location paths. + +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. + +To use the XPath package: + + package require xpath + +To parse a location path: + + xpath::split {/simple/example} + +This returns a Tcl list, each element of which is a three element +sublist: {axis node-test {?predicate ...?}}. |