+libxslt Tutorial

John Fleck

+ This is verion 0.1 of the libxslt Tutorial +
+

Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation + License, Version 1.1 or any later version + published by the Free Software Foundation with no Invariant + Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of + the license can be found here.

Table of Contents

Introduction +

Primary Functions +

Preparing to Parse +
Parse the Stylesheet +
Parse the Input File +
Applying the Stylesheet +
Saving the result +

+ +Abstract +

A tutorial on building a simple application using the + libxslt library to perform + XSLT transformations to convert an + XML file into HTML.

+ +

+ +Introduction +

The Extensible Markup Language (XML) is a World + Wide Web Consortium standard for the exchange of structured data in text + form. Its popularity stems from its universality. Any computer can + read a text file. With the proper tools, any computer can read any other + computer's XML files. +

One of the most imporant of those tools is XSLT: + Extensible Stylesheet Language Transformations. XSLT + is a declarative language that allows you to + translate your XML into arbitrary text output + using a stylesheet. libxslt provides the + functions to perform the transformation. +

libxslt is a free C language library + written by Daniel Veillard for the GNOME project + allowing you to write programs that perform XSLT + transformations. + +

Note

+ While libxslt was written + under the auspices of the GNOME project, it does not + depend on any GNOME libraries. None are used in the + example in this tutorial. +

+ +

This tutorial illustrates a simple program that reads an + XML file, applies a stylesheet and saves the resulting + output. This is not a program you would want to create + yourself. xsltproc, which is included with the + libxslt package, does the same thing and is + more robust and full-featured. The program written for this tutorial is a + stripped-down version of xsltproc designed to + illustrate the functionality of libxslt. +

References: +

+ +W3C XML page +
+ +W3C + XSL page. +
+ +libxslt +

+ +

+ +Primary Functions +

To transform an XML file, you must perform three + functions: +

+parse the input file
+parse the stylesheet
+apply the stylesheet

+ +

+ +Preparing to Parse +

Before you can begin parsing input files or stylesheets, there are + several steps you need to take to set up entity handling. These steps are + not unique to libxslt. Any + libxml2 program that parses + XML files would need to take similar steps. +

First, you need set up some libxml + housekeeping. Pass the integer value 1 to the + xmlSubstituteEntitiesDefault function, which tells + the libxml2 parser to substitute entities as + it parses your file. (Passing 0 causes + libxml2 to not perform entity substitution.) +

Second, set xmlLoadExtDtdDefaultValue equal to + 1. This tells libxml + to load external entity subsets. If you do not do this and the file your + input file includes entities through external subsets, you will get + errors.

+ +

+ +Parse the Stylesheet +

Parsing the stylesheet takes a single function call, which takes a + variable of type xmlChar: +

+	  cur = xsltParseStylesheetFile((const xmlChar *)argv[1]);
+

+ In this case, I cast the stylesheet file name, passed in as a + command line argument, to xmlChar. The return value + is of type xsltStylesheetPtr, a struct in memory + that contains the stylesheet tree and other information about the + stylesheet. It can be manipulated directly, but for this example you + will not need to. +

+ +

+ +Parse the Input File +

Parsing the input file takes a single function call: +

+doc = xmlParseFile(argv[2]);
+

+ It returns an xmlDocPtr, a struct in memory that + contains the document tree. It can be manipulated directly, but for this + example you will not need to. +

+ +

+ +Applying the Stylesheet +

Now that you have trees representing the document and the stylesheet + in memory, apply the stylesheet to the document. The + function that does this is xsltApplyStylesheet: +

+res = xsltApplyStylesheet(cur, doc, NULL);
+

+ For parameters, the function takes an xsltStylesheetPtr and an + xmlDocPtr, the values returned by the previous two functions. The third + parameter, NULL in this case, can be used to pass parameters to the + stylesheet. It is a NULL-terminated array of name/value pairs of const + char's. +

+ +

+ +Saving the result +

libxslt includes a function to use in + saving the resulting output: xsltSaveResultToFile. In + this case, we save the results to stdout: + +

+xsltSaveResultToFile(stdout, res, cur);
+

+Appendix A. The Code

+libxslt_tutorial.c +

+/*
+ * libxslt_tutorial.c: demo program for the XSL Transformation 1.0 engine
+ *
+ * based on xsltproc.c, by Daniel.Veillard@imag.fr
+ * by John Fleck 
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ */ 
+
+#include <libxml/xmlmemory.h>
+#include <libxml/debugXML.h>
+#include <libxml/HTMLtree.h>
+#include <libxml/xmlIO.h>
+#include <libxml/DOCBparser.h>
+#include <libxml/xinclude.h>
+#include <libxml/catalog.h>
+#include <libxslt/xslt.h>
+#include <libxslt/xsltInternals.h>
+#include <libxslt/transform.h>
+#include <libxslt/xsltutils.h>
+
+
+
+extern int xmlLoadExtDtdDefaultValue;
+
+static void usage(const char *name) {
+    printf("Usage: %s [options] stylesheet file [file ...]\n", name);
+}
+
+int
+main(int argc, char **argv) {
+	xsltStylesheetPtr cur = NULL;
+	xmlDocPtr doc, res;
+
+	if (argc <= 1) {
+		usage(argv[0]);
+		return(1);
+	}
+
+	xmlSubstituteEntitiesDefault(1);
+	xmlLoadExtDtdDefaultValue = 1;
+	cur = xsltParseStylesheetFile((const xmlChar *)argv[1]);
+	doc = xmlParseFile(argv[2]);
+	res = xsltApplyStylesheet(cur, doc, NULL);
+	xsltSaveResultToFile(stdout, res, cur);
+
+	xsltFreeStylesheet(cur);
+	xmlFreeDoc(res);
+	xmlFreeDoc(doc);
+
+	return(0);
+
+}
+
+

+ +

+ + libxslt Tutorial + + 2001 + John Fleck + + + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation + License, Version 1.1 or any later version + published by the Free Software Foundation with no Invariant + Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of + the license can be found here. + + + + John + Fleck + + + This is verion 0.1 of the libxslt Tutorial + + + + A tutorial on building a simple application using the + libxslt library to perform + XSLT transformations to convert an + XML file into HTML. + + + Introduction + + The Extensible Markup Language (XML) is a World + Wide Web Consortium standard for the exchange of structured data in text + form. Its popularity stems from its universality. Any computer can + read a text file. With the proper tools, any computer can read any other + computer's XML files. + + + One of the most imporant of those tools is XSLT: + Extensible Stylesheet Language Transformations. XSLT + is a declarative language that allows you to + translate your XML into arbitrary text output + using a stylesheet. libxslt provides the + functions to perform the transformation. + + + libxslt is a free C language library + written by Daniel Veillard for the GNOME project + allowing you to write programs that perform XSLT + transformations. + + + + While libxslt was written + under the auspices of the GNOME project, it does not + depend on any GNOME libraries. None are used in the + example in this tutorial. + + + + + + This tutorial illustrates a simple program that reads an + XML file, applies a stylesheet and saves the resulting + output. This is not a program you would want to create + yourself. xsltproc, which is included with the + libxslt package, does the same thing and is + more robust and full-featured. The program written for this tutorial is a + stripped-down version of xsltproc designed to + illustrate the functionality of libxslt. + + + References: + + + W3C XML page + + + W3C + XSL page. + + + libxslt + + + + + + + + Primary Functions + To transform an XML file, you must perform three + functions: + + + parse the input file + + + parse the stylesheet + + + apply the stylesheet + + + + + Preparing to Parse + Before you can begin parsing input files or stylesheets, there are + several steps you need to take to set up entity handling. These steps are + not unique to libxslt. Any + libxml2 program that parses + XML files would need to take similar steps. + + First, you need set up some libxml + housekeeping. Pass the integer value 1 to the + xmlSubstituteEntitiesDefault function, which tells + the libxml2 parser to substitute entities as + it parses your file. (Passing 0 causes + libxml2 to not perform entity substitution.) + + + Second, set xmlLoadExtDtdDefaultValue equal to + 1. This tells libxml + to load external entity subsets. If you do not do this and the file your + input file includes entities through external subsets, you will get + errors. + + + Parse the Stylesheet + Parsing the stylesheet takes a single function call, which takes a + variable of type xmlChar: + + cur = xsltParseStylesheetFile((const xmlChar *)argv[1]); + + In this case, I cast the stylesheet file name, passed in as a + command line argument, to xmlChar. The return value + is of type xsltStylesheetPtr, a struct in memory + that contains the stylesheet tree and other information about the + stylesheet. It can be manipulated directly, but for this example you + will not need to. + + + + + Parse the Input File + Parsing the input file takes a single function call: + +doc = xmlParseFile(argv[2]); + + It returns an xmlDocPtr, a struct in memory that + contains the document tree. It can be manipulated directly, but for this + example you will not need to. + + + + + Applying the Stylesheet + Now that you have trees representing the document and the stylesheet + in memory, apply the stylesheet to the document. The + function that does this is xsltApplyStylesheet: + +res = xsltApplyStylesheet(cur, doc, NULL); + + For parameters, the function takes an xsltStylesheetPtr and an + xmlDocPtr, the values returned by the previous two functions. The third + parameter, NULL in this case, can be used to pass parameters to the + stylesheet. It is a NULL-terminated array of name/value pairs of const + char's. + + + + + Saving the result + libxslt includes a function to use in + saving the resulting output: xsltSaveResultToFile. In + this case, we save the results to stdout: + + +xsltSaveResultToFile(stdout, res, cur); + + + + + + + + The Code + libxslt_tutorial.c + &CODE; + + + +