libxslt: An Extended Tutorial

Panos Louridas

Permission is hereby granted, free of charge, to +libxslt: An Extended Tutorial

libxslt: An Extended Tutorial

Panos Louridas

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, @@ -13,8 +13,9 @@ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION - WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Table of Contents

Introduction

Setting the Scene

Program Start

Arguments Collection

Parsing

File Processing

*NIX Compiling and Linking

MS-Windows Compiling and Linking

Building the Ports in -MS-Windows

The Complete Program

Introduction

The Extensible Stylesheet Language Transformations (XSLT) + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Table of Contents

Introduction

Setting the Scene

Program Start

Arguments Collection

Parsing

File Processing

*NIX Compiling and Linking

MS-Windows Compiling and +Linking

Building the Ports in +MS-Windows

zlib, iconv and All That

The Complete Program

Introduction

The Extensible Stylesheet Language Transformations (XSLT) specification defines an XML template language for transforming XML documents. An XSLT engine reads an XSLT file and an XML document and transforms the document accordingly.

We want to perform a series of XSLT transformations to a series @@ -49,7 +50,7 @@ systems and MS-Windows, where by *NIX systems we mean Linux, BSD, and other members of the family. The gcc suite is used in the *NIX platform and the Microsoft compiler and linker are used in the -MS-Windows platform.

Setting the Scene

+MS-Windows platform.

Setting the Scene

We need to include the necessary libraries:

@@ -57,7 +58,6 @@ We need to include the necessary libraries:
   #include <stdio.h>
   #include <string.h>
   #include <stdlib.h>
-  #include <malloc.h>
   
   #include <libxslt/transform.h>
   #include <libxslt/xsltutils.h>
@@ -91,7 +91,7 @@ describing its usage:
       printf("      --param name value: pass a (parameter,value) pair\n");
   }

Program Start

We need to define a few variables that are used throughout the +

Program Start

We need to define a few variables that are used throughout the program:

     int main(int argc, char **argv) {
@@ -140,7 +140,7 @@ space, but not much (the size of xmlStyleSheetPtr and
 later on. The array memory is allocated with
 calloc to ensure contents are initialised to
 zero.
-

Arguments Collection

If the program gets no arguments at all, we print the usage +

Arguments Collection

If the program gets no arguments at all, we print the usage description, set the program return value to 1 and exit. Instead of returning directly we go to (literally) to the end of the program text where some housekeeping takes place.

@@ -187,7 +187,7 @@ arguments starting with a dash. The XSLT parameters are put into the is set to the user request, if any. After processing all the parameter key-value pairs we set the last element of the params array to null. -

Parsing

The rest of the argument list is taken to be stylesheets and +

Parsing

The rest of the argument list is taken to be stylesheets and files to be transformed. Stylesheets are identified by their suffix, which is expected to be xsl (case sensitive). All other files are assumed to be XML documents, regardless of suffix.

@@ -223,7 +223,7 @@ resulting xsltStylesheetPtr is placed in the parsed using the xmlParseFile function that takes as argument the file's name; the resulting xmlDocPtr is placed in the files array. -

File Processing

All stylesheets are applied to each file one after the +

File Processing

All stylesheets are applied to each file one after the other. Stylesheets are applied with the xsltApplyStylesheet function that takes as argument the stylesheet to be applied, the file to be transformed and @@ -282,23 +282,35 @@ clean up all global variables used by the XSLT library using allocated for the XML parser is reclaimed by a call to xmlCleanupParser. Before returning we deallocate the memory allocated for the holding the pointers to the XML documents -and stylesheets.

*NIX Compiling and Linking

Compiling and linking in a *NIX environment +and stylesheets.

*NIX Compiling and Linking

Compiling and linking in a *NIX environment is easy, as the required libraries are almost certain to be already in place (remember that libxml and libxslt are used by the GNOME project, so they are present in most installations). The program can be dynamically linked so that its footprint is minimized, or statically -linked, so that it stands by itself, carrying all required code. For -dynamic linking the following one liner will do:

-gcc -o libxslt_pipes -Wall -I/usr/include/libxml2 -lxslt -lxml2 -L/usr/lib -libxslt_pipes.c +linked, so that it stands by itself, carrying all required code.

For dynamic linking the following one liner will do:

+gcc -o libxslt_pipes -Wall -I/usr/include/libxml2 -lxslt +-lxml2 -L/usr/lib libxslt_pipes.c

We assume that the necessary header files are in /usr/include/libxml2 and that the required libraries (libxslt.so, -libxsml2.so) are in /usr/lib.

For static linking we must list more libraries in the command -line, as the libraries on which the libxsl and libxslt libraries -depend are also needed. Still, an one-liner will do:

+libxml2.so) are in /usr/lib.

In general, a program may need to link to additional libraries, +depending on the processing it actually performs. A good way to start +is to use the xslt-config script. The +--help option displays usage +information. Running

+ + xslt-config --cflags + +

we get compile flags, while running

+ + xslt-config --libs + +

we get the library settings for the linker.

For static linking we must list more libraries than we did for +dynamic linking, as the libraries on which the libxsl and libxslt +libraries depend are also needed. Using xslt-config +on a particular installation we create the following one-liner:

gcc -o libxslt_pipes -Wall -I/usr/include/libxml2 libxslt_pipes.c --static -lxslt -lxml2 -lpthread -lz -lm +-static -L/usr/lib -lxslt -lxml2 -lz -lpthread -lm

If we get warnings to the effect that some function in statically linked applications requires at runtime the shared @@ -311,7 +323,8 @@ to avoid this it to use an alternative C runtime, for example

MS-Windows Compiling and Linking

Compiling and linking in MS-Windows requires +

MS-Windows Compiling and +Linking

Compiling and linking in MS-Windows requires some attention. First, the MS-Windows ports must be downloaded and installed in the programming workstation. The ports are available in Igor @@ -351,7 +364,7 @@ with a compiler whose version is greater than 6, your program is likely to crash unexpectedly. Alternatively, you may wish to compile all iconv, zlib, libxml and libxslt yourself, using the new runtime library. This is not a tall order, and some details are given -below.

There are three kinds of libraries in MS-Windows. Dynamically Linked Libraries (DLLs), like msvcrt.dll we met above, are used for dynamic linking; an application links to them at @@ -403,7 +416,7 @@ Microsoft developer tools with a version number greater than 6, we are no longer using msvcrt.dll, but another runtime like msvcrt71.dll, and we then need that DLL. In contrast to msvcrt.dll it may not be present on -the target computer, so we may have to copy it along.

Building the Ports in +the target computer, so we may have to copy it along.
Building the Ports in MS-Windows
The source code of the ports is readily available on the web, one has to check the ports sites. Each port can be built without problems in an MS-Windows environment using Microsoft development @@ -434,7 +447,35 @@ distributions before starting; moreover, pay attention to the dependencies between the ports. If we configure libxml and libxslt to use iconv and zlib we must build these two first and make sure their headers and libraries can be found by the compiler and the -linker when building libxml and libxslt.

The Complete Program

+linker when building libxml and libxslt.

zlib, iconv and All That

We saw that libxml and libxslt depend on various other +libraries, for instance zlib, iconv, and so forth. Taking a look into +them gives us clues on the capabilities of libxml and libxslt.

zlib is a free general +purpose lossless data compression library. It is a venerable +workhorse; more than 500 applications +(both commercial and open source) seem to use the library. libxml uses +zlib so that it can read from or write to compressed files +directly. The xmlParseFile function can +transparently parse a compressed document to produce an +xmlDoc. If we want to create a compressed +document with libxml we can use an +xmlTextWriterPtr (obtained through +xmlNewTextWriterDoc), or another related +structure from libxml/xmlwriter.h, with +compression enabled.

XML allows documents to use a variety of different character +encodings. iconv is a free +library for converting between different character encodings. libxml +provides a set of default converters for some encodings: UTF-8, UTF-16 +(little endian and big endian), ISO-8859-1, ASCII, and HTML (a +specific handler for the conversion of UTF-8 to ASCII with HTML +predefined entities like © for the copyright sign). However, +when compiled with iconv support, libxml and libxslt can handle the +full range of encodings provided by iconv; these should cover most +needs.

libxml and libxslt can be used in multi-threaded +applications. In MS-Windows they are linked against +MSVCRT.DLL (or one of its descendants, as we saw +above). In *NIX the pthreads +(POSIX threads) library is used.

The Complete Program

The complete program listing is given below. The program is also available online.

@@ -445,34 +486,25 @@ The complete program listing is given below. The program is also * * Writen by Panos Louridas, based on libxslt_tutorial.c by John Fleck. * - * Copyright (c) 2004 Panagiotis Louridas + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. * - * Permission is hereby granted, free of charge, to any person - * obtaining a copy of this software and associated documentation - * files (the "Software"), to deal in the Software without - * restriction, including without limitation the rights to use, copy, - * modify, merge, publish, distribute, sublicense, and/or sell copies - * of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: </para> + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. * - * The above copyright notice and this permission notice shall be - * included in all copies or substantial portions of the Software. + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Cambridge, MA 02139, USA. * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. */ #include <stdio.h> #include <string.h> #include <stdlib.h> -#include <malloc.h> -#include <stdarg.h> #include <libxslt/transform.h> #include <libxslt/xsltutils.h> diff --git a/doc/tutorial2/libxslt_pipes.xml b/doc/tutorial2/libxslt_pipes.xml index 188aa29..9a672a9 100644 --- a/doc/tutorial2/libxslt_pipes.xml +++ b/doc/tutorial2/libxslt_pipes.xml @@ -100,7 +100,6 @@ We need to include the necessary libraries: #include #include #include - #include #include #include @@ -382,28 +381,52 @@ is easy, as the required libraries are almost certain to be already in place (remember that libxml and libxslt are used by the GNOME project, so they are present in most installations). The program can be dynamically linked so that its footprint is minimized, or statically -linked, so that it stands by itself, carrying all required code. For -dynamic linking the following one liner will do: +linked, so that it stands by itself, carrying all required code. + +For dynamic linking the following one liner will do: -gcc -o libxslt_pipes -Wall -I/usr/include/libxml2 -lxslt -lxml2 -L/usr/lib -libxslt_pipes.c +gcc -o libxslt_pipes -Wall -I/usr/include/libxml2 -lxslt +-lxml2 -L/usr/lib libxslt_pipes.c We assume that the necessary header files are in /usr/include/libxml2 and that the required libraries (libxslt.so, -libxsml2.so) are in libxml2.so) are in /usr/lib. -For static linking we must list more libraries in the command -line, as the libraries on which the libxsl and libxslt libraries -depend are also needed. Still, an one-liner will do: +In general, a program may need to link to additional libraries, +depending on the processing it actually performs. A good way to start +is to use the xslt-config script. The + option displays usage +information. Running + + + + xslt-config --cflags + + + +we get compile flags, while running + + + + xslt-config --libs + + + +we get the library settings for the linker. + +For static linking we must list more libraries than we did for +dynamic linking, as the libraries on which the libxsl and libxslt +libraries depend are also needed. Using xslt-config +on a particular installation we create the following one-liner: gcc -o libxslt_pipes -Wall -I/usr/include/libxml2 libxslt_pipes.c --static -lxslt -lxml2 -lpthread -lz -lm +-static -L/usr/lib -lxslt -lxml2 -lz -lpthread -lm @@ -423,7 +446,8 @@ using uClibc might be a good idea anyway). -MS-Windows Compiling and Linking +MS-Windows Compiling and +Linking Compiling and linking in MS-Windows requires some attention. First, the MS-Windows ports must be @@ -473,7 +497,7 @@ with a compiler whose version is greater than 6, your program is likely to crash unexpectedly. Alternatively, you may wish to compile all iconv, zlib, libxml and libxslt yourself, using the new runtime library. This is not a tall order, and some details are given -below. +below. There are three kinds of libraries in MS-Windows. Dynamically Linked Libraries (DLLs), like msvcrt.dll we met @@ -536,7 +560,7 @@ like msvcrt71.dll, and we then need that DLL. In contrast to msvcrt.dll it may not be present on the target computer, so we may have to copy it along. -Building the Ports in +<sect2 id="windows-ports-build"><title>Building the Ports in MS-Windows The source code of the ports is readily available on the web, @@ -577,6 +601,47 @@ linker when building libxml and libxslt. +zlib, iconv and All That + +We saw that libxml and libxslt depend on various other +libraries, for instance zlib, iconv, and so forth. Taking a look into +them gives us clues on the capabilities of libxml and libxslt. + +zlib is a free general +purpose lossless data compression library. It is a venerable +workhorse; more than 500 applications +(both commercial and open source) seem to use the library. libxml uses +zlib so that it can read from or write to compressed files +directly. The xmlParseFile function can +transparently parse a compressed document to produce an +xmlDoc. If we want to create a compressed +document with libxml we can use an +xmlTextWriterPtr (obtained through +xmlNewTextWriterDoc), or another related +structure from libxml/xmlwriter.h, with +compression enabled. + +XML allows documents to use a variety of different character +encodings. iconv is a free +library for converting between different character encodings. libxml +provides a set of default converters for some encodings: UTF-8, UTF-16 +(little endian and big endian), ISO-8859-1, ASCII, and HTML (a +specific handler for the conversion of UTF-8 to ASCII with HTML +predefined entities like © for the copyright sign). However, +when compiled with iconv support, libxml and libxslt can handle the +full range of encodings provided by iconv; these should cover most +needs. + +libxml and libxslt can be used in multi-threaded +applications. In MS-Windows they are linked against +MSVCRT.DLL (or one of its descendants, as we saw +above). In *NIX the pthreads +(POSIX threads) library is used. + + + The Complete Program -- 2.7.4