Main Page | Class Hierarchy | Class List | File List | Class Members

stylesheet.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2001-2003 Peter J Jones (pjones@pmade.org)
00003  * All Rights Reserved
00004  * 
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions
00007  * are met:
00008  * 
00009  * 1. Redistributions of source code must retain the above copyright
00010  *    notice, this list of conditions and the following disclaimer.
00011  * 2. Redistributions in binary form must reproduce the above copyright
00012  *    notice, this list of conditions and the following disclaimer in
00013  *    the documentation and/or other materials provided with the
00014  *    distribution.
00015  * 3. Neither the name of the Author nor the names of its contributors
00016  *    may be used to endorse or promote products derived from this software
00017  *    without specific prior written permission.
00018  * 
00019  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
00020  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
00021  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
00022  * PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR
00023  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00024  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00025  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
00026  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
00027  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00028  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
00029  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00030  * SUCH DAMAGE.
00031  */
00032 
00033 /** @file
00034  * This file contains the definition of the xslt::stylesheet class.
00035 **/
00036 
00037 #ifndef _xsltwrapp_stylesheet_h_
00038 #define _xsltwrapp_stylesheet_h_
00039 
00040 // xmlwrapp includes
00041 #include <xmlwrapp/document.h>
00042 
00043 // standard includes
00044 #include <map>
00045 #include <string>
00046 
00047 namespace xslt {
00048 
00049 /**
00050  * The xslt::stylesheet class is used to hold information about an XSLT
00051  * stylesheet. You can use it to load in a stylesheet and then use that
00052  * stylesheet to transform an XML document to something else.
00053 **/
00054 class stylesheet {
00055 public:
00056     /// Type for passing parameters to the stylesheet
00057     typedef std::map<std::string, std::string> param_type;
00058 
00059     //####################################################################
00060     /** 
00061      * Create a new xslt::stylesheet object and load and parse the
00062      * stylesheet in the given filename.
00063      *
00064      * @param filename The name of the file that contains the stylesheet.
00065      * @author Peter Jones
00066     **/
00067     //####################################################################
00068     explicit stylesheet (const char *filename);
00069 
00070     //####################################################################
00071     /** 
00072      * Create a new xslt::stylesheet object from an xml::document object
00073      * that contains the parsed stylesheet. The given xml::document is
00074      * passed by value. This is needed because the stylesheet will own the
00075      * document and free it.
00076      *
00077      * @param doc The parsed stylesheet.
00078      * @author Peter Jones
00079     **/
00080     //####################################################################
00081     explicit stylesheet (xml::document doc);
00082 
00083     //####################################################################
00084     /** 
00085      * Clean up after an xslt::stylesheet.
00086      *
00087      * @author Peter Jones
00088     **/
00089     //####################################################################
00090     ~stylesheet (void);
00091 
00092     //####################################################################
00093     /** 
00094      * Apply this stylesheet to the given XML document. The result document
00095      * is placed in the second document parameter.
00096      *
00097      * @param doc The XML document to transform.
00098      * @param result The result tree after applying this stylesheet.
00099      * @return True if the transformation was successful and the results placed in result.
00100      * @return False if there was an error, result is not modified.
00101      * @author Peter Jones
00102     **/
00103     //####################################################################
00104     bool apply (xml::document &doc, xml::document &result);
00105 
00106     //####################################################################
00107     /** 
00108      * Apply this stylesheet to the given XML document. The result document
00109      * is placed in the second document parameter.
00110 
00111      * @param doc The XML document to transform.
00112      * @param result The result tree after applying this stylesheet.
00113      * @param with_params Override xsl:param elements using the given key/value map
00114      * @return True if the transformation was successful and the results placed in result.
00115      * @return False if there was an error, result is not modified.
00116      * @author Peter Jones
00117     **/
00118     //####################################################################
00119     bool apply (xml::document &doc, xml::document &result, const param_type &with_params);
00120 
00121     //####################################################################
00122     /** 
00123      * Apply this stylesheet to the given XML document. The results document
00124      * is returned. If there is an error during transformation, this
00125      * function will throw a std::runtime_error exception.
00126      *
00127      * Each time you call this member function, the xml::document object
00128      * that was returned from the last call becomes invalid. That is, of
00129      * course, unless you copied it first.
00130      *
00131      * @param doc The XML document to transform.
00132      * @return A reference to the result tree.
00133      * @author Peter Jones
00134     **/
00135     //####################################################################
00136     xml::document& apply (xml::document &doc);
00137 
00138     //####################################################################
00139     /** 
00140      * Apply this stylesheet to the given XML document. The results document
00141      * is returned. If there is an error during transformation, this
00142      * function will throw a std::runtime_error exception.
00143      *
00144      * Each time you call this member function, the xml::document object
00145      * that was returned from the last call becomes invalid. That is, of
00146      * course, unless you copied it first.
00147      *
00148      * @param doc The XML document to transform.
00149      * @param with_params Override xsl:param elements using the given key/value map
00150      * @return A reference to the result tree.
00151      * @author Peter Jones
00152     **/
00153     //####################################################################
00154     xml::document& apply (xml::document &doc, const param_type &with_params);
00155 
00156     //####################################################################
00157     /** 
00158      * If you used one of the xslt::stylesheet::apply member functions that
00159      * return a bool, you can use this function to get the text message for
00160      * the transformation error.
00161      *
00162      * If you are using one of the apply member functions that throws
00163      * exceptions, this function should not be used. The text message for
00164      * the transformation error will be given to the std::runtime_error
00165      * constructor.
00166      *
00167      * @return The last error message.
00168      * @author Peter Jones
00169     **/
00170     //####################################################################
00171     const std::string& get_error_message (void) const;
00172 
00173 private:
00174     struct pimpl; pimpl *pimpl_;
00175 
00176     // an xslt::stylesheet cannot yet be copied or assigned to.
00177     stylesheet (const stylesheet&);
00178     stylesheet& operator= (const stylesheet&);
00179 }; // end xslt::stylesheet class
00180     
00181 } // end xslt namespace
00182 #endif

Generated on Tue Oct 19 12:26:03 2004 for xmlwrapp by doxygen 1.3.6