Server IP : 92.204.138.22 / Your IP : 3.144.254.254 Web Server : Apache System : Linux ns1009439.ip-92-204-138.us 4.18.0-553.8.1.el8_10.x86_64 #1 SMP Tue Jul 2 07:26:33 EDT 2024 x86_64 User : internationaljou ( 1019) PHP Version : 7.4.33 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /proc/self/root/proc/thread-self/root/usr/share/doc/libxslt-devel/tutorial/ |
Upload File : |
<?xml version="1.0"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ <!ENTITY CODE SYSTEM "libxslt_tutorial.c"> ]> <article> <articleinfo> <title>libxslt Tutorial</title> <copyright> <year>2001</year> <holder>John Fleck</holder> </copyright> <legalnotice id="legalnotice"> <para>Permission is granted to copy, distribute and/or modify this document under the terms of the <citetitle>GNU Free Documentation License</citetitle>, 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 <ulink type="http" url="http://www.gnu.org/copyleft/fdl.html">here</ulink>.</para> </legalnotice> <author> <firstname>John</firstname> <surname>Fleck</surname> </author> <releaseinfo> This is version 0.4 of the libxslt Tutorial </releaseinfo> </articleinfo> <abstract> <para>A tutorial on building a simple application using the <application>libxslt</application> library to perform <acronym>XSLT</acronym> transformations to convert an <acronym>XML</acronym> file into <acronym>HTML</acronym>.</para> </abstract> <sect1 id="introduction"> <title>Introduction</title> <para>The Extensible Markup Language (<acronym>XML</acronym>) 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 <acronym>XML</acronym> files. </para> <para>One of the most important of those tools is <acronym>XSLT</acronym>: Extensible Stylesheet Language Transformations. <acronym>XSLT</acronym> is a declarative language that allows you to translate your <acronym>XML</acronym> into arbitrary text output using a stylesheet. <application>libxslt</application> provides the functions to perform the transformation. </para> <para><application>libxslt</application> is a free C language library written by Daniel Veillard for the <acronym>GNOME</acronym> project allowing you to write programs that perform <acronym>XSLT</acronym> transformations. <note> <para> While <application>libxslt</application> was written under the auspices of the <acronym>GNOME</acronym> project, it does not depend on any <acronym>GNOME</acronym> libraries. None are used in the example in this tutorial. </para> </note> </para> <para>This tutorial illustrates a simple program that reads an <acronym>XML</acronym> file, applies a stylesheet and saves the resulting output. This is not a program you would want to create yourself. <application>xsltproc</application>, which is included with the <application>libxslt</application> package, does the same thing and is more robust and full-featured. The program written for this tutorial is a stripped-down version of <application>xsltproc</application> designed to illustrate the functionality of <application>libxslt</application>. </para> <para>The full code for <application>xsltproc</application> is in <filename>xsltproc.c</filename> in the <application>libxslt</application> distribution. It also is available <ulink url="http://cvs.gnome.org/lxr/source/libxslt/libxslt/xsltproc.c">on the web</ulink>. </para> <para>References: <itemizedlist> <listitem> <para><ulink url="http://www.w3.org/XML/">W3C <acronym>XML</acronym> page</ulink></para> </listitem> <listitem> <para><ulink url="http://www.w3.org/Style/XSL/">W3C <acronym>XSL</acronym> page.</ulink></para> </listitem> <listitem> <para><ulink url="http://xmlsoft.org/XSLT/">libxslt</ulink></para> </listitem> </itemizedlist> </para> </sect1> <sect1 id="functions"> <title>Primary Functions</title> <para>To transform an <acronym>XML</acronym> file, you must perform three functions: <orderedlist> <listitem> <para>parse the input file</para> </listitem> <listitem> <para>parse the stylesheet</para> </listitem> <listitem> <para>apply the stylesheet</para> </listitem> </orderedlist> </para> <sect2 id="preparing"> <title>Preparing to Parse</title> <para>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 <application>libxslt</application>. Any <application>libxml2</application> program that parses <acronym>XML</acronym> files would need to take similar steps. </para> <para>First, you need set up some <application>libxml</application> housekeeping. Pass the integer value <parameter>1</parameter> to the <function>xmlSubstituteEntitiesDefault</function> function, which tells the <application>libxml2</application> parser to substitute entities as it parses your file. (Passing <parameter>0</parameter> causes <application>libxml2</application> to not perform entity substitution.) </para> <para>Second, set <varname>xmlLoadExtDtdDefaultValue</varname> equal to <parameter>1</parameter>. This tells <application>libxml</application> to load external entity subsets. If you do not do this and your input file includes entities through external subsets, you will get errors.</para> </sect2> <sect2 id="parsethestylesheet"> <title>Parse the Stylesheet</title> <para>Parsing the stylesheet takes a single function call, which takes a variable of type <type>xmlChar</type>: <programlisting> <varname>cur</varname> = xsltParseStylesheetFile((const xmlChar *)argv[i]); </programlisting> In this case, I cast the stylesheet file name, passed in as a command line argument, to <emphasis>xmlChar</emphasis>. The return value is of type <emphasis>xsltStylesheetPtr</emphasis>, 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. </para> </sect2> <sect2 id="parseinputfile"> <title>Parse the Input File</title> <para>Parsing the input file takes a single function call: <programlisting> doc = xmlParseFile(argv[i]); </programlisting> It returns an <emphasis>xmlDocPtr</emphasis>, a struct in memory that contains the document tree. It can be manipulated directly, but for this example you will not need to. </para> </sect2> <sect2 id="applyingstylesheet"> <title>Applying the Stylesheet</title> <para>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 <function>xsltApplyStylesheet</function>: <programlisting> res = xsltApplyStylesheet(cur, doc, params); </programlisting> The function takes an xsltStylesheetPtr and an xmlDocPtr, the values returned by the previous two functions. The third variable, <varname>params</varname> can be used to pass <acronym>XSLT</acronym> parameters to the stylesheet. It is a NULL-terminated array of name/value pairs of const char's. </para> </sect2> <sect2 id="saveresult"> <title>Saving the result</title> <para><application>libxslt</application> includes a family of functions to use in saving the resulting output. For this example, <function>xsltSaveResultToFile</function> is used, and the results are saved to stdout: <programlisting> xsltSaveResultToFile(stdout, res, cur); </programlisting> <note> <para><application>libxml</application> also contains output functions, such as <function>xmlSaveFile</function>, which can be used here. However, output-related information contained in the stylesheet, such as a declaration of the encoding to be used, will be lost if one of the <application>libxslt</application> save functions is not used.</para> </note> </para> </sect2> <sect2 id="parameters"> <title>Parameters</title> <para> In <acronym>XSLT</acronym>, parameters may be used as a way to pass additional information to a stylesheet. <application>libxslt</application> accepts <acronym>XSLT</acronym> parameters as one of the values passed to <function>xsltApplyStylesheet</function>. </para> <para> In the tutorial example and in <application>xsltproc</application>, on which the tutorial example is based, parameters to be passed take the form of key-value pairs. The program collects them from command line arguments, inserting them in the array <varname>params</varname>, then passes them to the function. The final element in the array is set to <parameter>NULL</parameter>. <note> <para> If a parameter being passed is a string rather than an <acronym>XSLT</acronym> node, it must be escaped. For the tutorial program, that would be done as follows: <command>tutorial]$ ./libxslt_tutorial --param rootid "'asect1'" stylesheet.xsl filename.xml</command> </para> </note> </para> </sect2> <sect2 id="cleanup"> <title>Cleanup</title> <para>After you are finished, <application>libxslt</application> and <application>libxml</application> provide functions for deallocating memory. </para> <para> <programlisting> xsltFreeStylesheet(cur);<co id="cleanupstylesheet" /> xmlFreeDoc(res);<co id="cleanupresults" /> xmlFreeDoc(doc);<co id="cleanupdoc" /> xsltCleanupGlobals();<co id="cleanupglobals" /> xmlCleanupParser();<co id="cleanupparser" /> </programlisting> <calloutlist> <callout arearefs="cleanupstylesheet"> <para>Free the memory used by your stylesheet.</para> </callout> <callout arearefs="cleanupresults"> <para>Free the memory used by the results document.</para> </callout> <callout arearefs="cleanupdoc"> <para>Free the memory used by your original document.</para> </callout> <callout arearefs="cleanupglobals"> <para>Free memory used by <application>libxslt</application> global variables</para> </callout> <callout arearefs="cleanupparser"> <para>Free memory used by the <acronym>XML</acronym> parser</para> </callout> </calloutlist> </para> </sect2> </sect1> <appendix id="thecode"> <title>The Code</title> <para><filename>libxslt_tutorial.c</filename> <programlisting>&CODE;</programlisting> </para> </appendix> </article>