xmlwrapp
xsltwrapp/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 /**
00034     @file
00035 
00036    This file contains the definition of the xslt::stylesheet class.
00037  */
00038 
00039 #ifndef _xsltwrapp_stylesheet_h_
00040 #define _xsltwrapp_stylesheet_h_
00041 
00042 // xmlwrapp includes
00043 #include "xsltwrapp/init.h"
00044 #include "xmlwrapp/document.h"
00045 
00046 // standard includes
00047 #include <map>
00048 #include <string>
00049 
00050 namespace xslt
00051 {
00052 
00053 /**
00054     The xslt::stylesheet class is used to hold information about an XSLT
00055     stylesheet. You can use it to load in a stylesheet and then use that
00056     stylesheet to transform an XML document to something else.
00057  */
00058 class stylesheet
00059 {
00060 public:
00061     struct pimpl;
00062 
00063     /// Type for passing parameters to the stylesheet
00064     typedef std::map<std::string, std::string> param_type;
00065 
00066     /**
00067         Create a new xslt::stylesheet object and load and parse the
00068         stylesheet in the given filename.
00069 
00070         @param filename The name of the file that contains the stylesheet.
00071      */
00072     explicit stylesheet(const char *filename);
00073 
00074     /**
00075         Create a new xslt::stylesheet object from an xml::document object
00076         that contains the parsed stylesheet. The given xml::document is
00077         passed by value. This is needed because the stylesheet will own the
00078         document and free it.
00079 
00080         @param doc The parsed stylesheet.
00081      */
00082     explicit stylesheet(xml::document doc);
00083 
00084     /**
00085         Clean up after an xslt::stylesheet.
00086      */
00087     ~stylesheet();
00088 
00089     /**
00090         Apply this stylesheet to the given XML document. The result document
00091         is placed in the second document parameter.
00092 
00093         @param doc The XML document to transform.
00094         @param result The result tree after applying this stylesheet.
00095         @return True if the transformation was successful and the results placed in result.
00096         @return False if there was an error, result is not modified.
00097      */
00098     bool apply(const xml::document& doc, xml::document& result);
00099 
00100     /**
00101         Apply this stylesheet to the given XML document. The result document
00102         is placed in the second document parameter.
00103 
00104         @param doc The XML document to transform.
00105         @param result The result tree after applying this stylesheet.
00106         @param with_params Override xsl:param elements using the given key/value map
00107         @return True if the transformation was successful and the results placed in result.
00108         @return False if there was an error, result is not modified.
00109      */
00110     bool apply(const xml::document& doc, xml::document& result, const param_type& with_params);
00111 
00112     /**
00113         Apply this stylesheet to the given XML document. The results document
00114         is returned. If there is an error during transformation, this
00115         function will throw a std::runtime_error exception.
00116 
00117         Each time you call this member function, the xml::document object
00118         that was returned from the last call becomes invalid. That is, of
00119         course, unless you copied it first.
00120 
00121         @param doc The XML document to transform.
00122         @return A reference to the result tree.
00123      */
00124     xml::document& apply(const xml::document& doc);
00125 
00126     /**
00127         Apply this stylesheet to the given XML document. The results document
00128         is returned. If there is an error during transformation, this
00129         function will throw a std::runtime_error exception.
00130 
00131         Each time you call this member function, the xml::document object
00132         that was returned from the last call becomes invalid. That is, of
00133         course, unless you copied it first.
00134 
00135         @param doc The XML document to transform.
00136         @param with_params Override xsl:param elements using the given key/value map
00137         @return A reference to the result tree.
00138      */
00139     xml::document& apply(const xml::document& doc, const param_type& with_params);
00140 
00141     /**
00142         If you used one of the xslt::stylesheet::apply member functions that
00143         return a bool, you can use this function to get the text message for
00144         the transformation error.
00145 
00146         If you are using one of the apply member functions that throws
00147         exceptions, this function should not be used. The text message for
00148         the transformation error will be given to the std::runtime_error
00149         constructor.
00150 
00151         @return The last error message.
00152      */
00153     const std::string& get_error_message() const;
00154 
00155 private:
00156     pimpl *pimpl_;
00157 
00158     // an xslt::stylesheet cannot yet be copied or assigned to.
00159     stylesheet(const stylesheet&);
00160     stylesheet& operator=(const stylesheet&);
00161 }; // end xslt::stylesheet class
00162 
00163 } // end xslt namespace
00164 
00165 #endif // _xsltwrapp_stylesheet_h_