xmlwrapp Lightweight C++ XML parsing library

stylesheet.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2001-2003 Peter J Jones (pjones@pmade.org)
3 * Copyright (C) 2013 Vaclav Slavik <vslavik@gmail.com>
4 * All Rights Reserved
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 *
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in
14 * the documentation and/or other materials provided with the
15 * distribution.
16 * 3. Neither the name of the Author nor the names of its contributors
17 * may be used to endorse or promote products derived from this software
18 * without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
23 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
24 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
27 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 * SUCH DAMAGE.
32 */
33
34 /**
35 @file
36
37 This file contains the definition of the xslt::stylesheet class.
38 */
39
40 #ifndef _xsltwrapp_stylesheet_h_
41 #define _xsltwrapp_stylesheet_h_
42
43 // xmlwrapp includes
44 #include "xsltwrapp/init.h"
45 #include "xmlwrapp/document.h"
46 #include "xmlwrapp/export.h"
47 #include "xmlwrapp/errors.h"
48
49 // standard includes
50 #include <map>
51 #include <string>
52
53 namespace xslt
54 {
55
56 /**
57 The xslt::stylesheet class is used to hold information about an XSLT
58 stylesheet. You can use it to load in a stylesheet and then use that
59 stylesheet to transform an XML document to something else.
60 */
61 class XSLTWRAPP_API stylesheet
62 {
63 public:
64 struct pimpl;
65
66 /// Type for passing parameters to the stylesheet
67 typedef std::map<std::string, std::string> param_type;
68
69 /**
70 Create a new xslt::stylesheet object and load and parse the
71 stylesheet in the given filename.
72
73 Errors are handled by @a on_error handler; by default, xml::exception
74 is thrown on errors. If there's a fatal error that prevents the
75 stylesheet from being loaded and the error handler doesn't throw an
76 exception, the constructor will throw xml::exception anyway.
77
78 @param filename The name of the file that contains the stylesheet.
79 @param on_error Handler called to process errors and warnings (since 0.7.0).
80 */
81 explicit stylesheet(const char *filename,
82 xml::error_handler& on_error = xml::throw_on_error);
83
84 /**
85 Create a new xslt::stylesheet object from an xml::document object
86 that contains the parsed stylesheet. The given xml::document is
87 passed by value. This is needed because the stylesheet will own the
88 document and free it.
89
90 Errors are handled by @a on_error handler; by default, xml::exception
91 is thrown on errors. If there's a fatal error that prevents the
92 stylesheet from being loaded and the error handler doesn't throw an
93 exception, the constructor will throw xml::exception anyway.
94
95 @param doc The parsed stylesheet.
96 @param on_error Handler called to process errors and warnings (since 0.7.0).
97 */
98 explicit stylesheet(xml::document doc,
99 xml::error_handler& on_error = xml::throw_on_error);
100
101 /**
102 Clean up after an xslt::stylesheet.
103 */
104 ~stylesheet();
105
106 /**
107 Apply this stylesheet to the given XML document. The result document
108 is placed in the second document parameter.
109
110 @param doc The XML document to transform.
111 @param result The result tree after applying this stylesheet.
112
113 @return True if the transformation was successful and the results placed in result.
114 @return False if there was an error, result is not modified.
115
116 @deprecated Use the form that takes xml::error_handler argument.
117 */
118 XMLWRAPP_DEPRECATED("use the form that takes error_handler argument")
119 bool apply(const xml::document& doc, xml::document& result);
120
121 /**
122 Apply this stylesheet to the given XML document. The result document
123 is placed in the second document parameter.
124
125 @param doc The XML document to transform.
126 @param result The result tree after applying this stylesheet.
127 @param with_params Override xsl:param elements using the given key/value map
128
129 @return True if the transformation was successful and the results placed in result.
130 @return False if there was an error, result is not modified.
131
132 @deprecated Use the form that takes xml::error_handler argument.
133 */
134 XMLWRAPP_DEPRECATED("use the form that takes error_handler argument")
135 bool apply(const xml::document& doc, xml::document& result, const param_type& with_params);
136
137 /**
138 Apply this stylesheet to the given XML document. The result document
139 is placed in the second document parameter.
140
141 @param doc The XML document to transform.
142 @param result The result tree after applying this stylesheet.
143 @param on_error Handler called to process errors and warnings (since 0.7.0).
144
145 @return True if the transformation was successful and the results placed in result.
146 @return False if there was an error, result is not modified.
147 */
148 bool apply(const xml::document& doc,
149 xml::document& result,
150 xml::error_handler& on_error);
151
152 /**
153 Apply this stylesheet to the given XML document. The result document
154 is placed in the second document parameter.
155
156 @param doc The XML document to transform.
157 @param result The result tree after applying this stylesheet.
158 @param with_params Override xsl:param elements using the given key/value map
159 @param on_error Handler called to process errors and warnings (since 0.7.0).
160
161 @return True if the transformation was successful and the results placed in result.
162 @return False if there was an error, result is not modified.
163 */
164 bool apply(const xml::document& doc,
165 xml::document& result,
166 const param_type& with_params,
167 xml::error_handler& on_error);
168
169 /**
170 Apply this stylesheet to the given XML document. The results document
171 is returned. If there is an error during transformation, this
172 function will throw a xml::exception exception.
173
174 Each time you call this member function, the xml::document object
175 that was returned from the last call becomes invalid. That is, of
176 course, unless you copied it first.
177
178 @param doc The XML document to transform.
179 @param on_error Handler called to process errors and warnings (since 0.7.0).
180
181 @return A reference to the result tree.
182 */
183 xml::document& apply(const xml::document& doc,
184 xml::error_handler& on_error = xml::throw_on_error);
185
186 /**
187 Apply this stylesheet to the given XML document. The results document
188 is returned. If there is an error during transformation, this
189 function will throw a xml::exception exception.
190
191 Each time you call this member function, the xml::document object
192 that was returned from the last call becomes invalid. That is, of
193 course, unless you copied it first.
194
195 @param doc The XML document to transform.
196 @param with_params Override xsl:param elements using the given key/value map
197 @param on_error Handler called to process errors and warnings (since 0.7.0).
198
199 @return A reference to the result tree.
200 */
201 xml::document& apply(const xml::document& doc,
202 const param_type& with_params,
203 xml::error_handler& on_error = xml::throw_on_error);
204
205 /**
206 If you used one of the xslt::stylesheet::apply member functions that
207 return a bool, you can use this function to get the text message for
208 the transformation error.
209
210 If you are using one of the apply member functions that throws
211 exceptions, this function should not be used. The text message for
212 the transformation error will be given to the xml::exception
213 constructor.
214
215 @return The last error message.
216
217 @deprecated Use apply() variants that take xml::error_handler argument.
218 */
219 XMLWRAPP_DEPRECATED("use apply() variants that take error_handler argument")
220 const std::string& get_error_message() const;
221
222 private:
223 void init(xml::document& doc, xml::error_handler& on_error);
224
225 private:
226 pimpl *pimpl_;
227
228 // an xslt::stylesheet cannot yet be copied or assigned to.
229 stylesheet(const stylesheet&);
230 stylesheet& operator=(const stylesheet&);
231 }; // end xslt::stylesheet class
232
233 } // end xslt namespace
234
235 #endif // _xsltwrapp_stylesheet_h_
xslt::init
The xslt::init class is used to configure the XSLT engine.
Definition: init.h:64
xslt::stylesheet
The xslt::stylesheet class is used to hold information about an XSLT stylesheet.
Definition: stylesheet.h:62
document.h
xslt::stylesheet::stylesheet
stylesheet(const char *filename, xml::error_handler &on_error=xml::throw_on_error)
Create a new xslt::stylesheet object and load and parse the stylesheet in the given filename.
xslt
XSLT library namespace.
Definition: document.h:56
errors.h
xslt::stylesheet::param_type
std::map< std::string, std::string > param_type
Type for passing parameters to the stylesheet.
Definition: stylesheet.h:64
xml::error_handler
The xml::error_handler class is used to handle libxml2 errors and warnings emitted during parsing,...
Definition: errors.h:85
xml::document
The xml::document class is used to hold the XML tree and various bits of information about it.
Definition: document.h:85
xml::throw_on_error
error_handler_throw_on_error throw_on_error
Error handler object that throws on any error.
init.h
xml
XML library namespace.
Definition: attributes.h:52
xslt::stylesheet::~stylesheet
~stylesheet()
Clean up after an xslt::stylesheet.
xslt::stylesheet::stylesheet
stylesheet(xml::document doc, xml::error_handler &on_error=xml::throw_on_error)
Create a new xslt::stylesheet object from an xml::document object that contains the parsed stylesheet...