1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
/*
* This file is part of KDevelop
* Copyright 2012 Miha Čančula <miha@noughmad.eu>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library 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
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this library; see the file COPYING.LIB. If not, write to
* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
*/
#ifndef KDEVPLATFORM_TEMPLATERENDERER_H
#define KDEVPLATFORM_TEMPLATERENDERER_H
#include <QVariantHash>
#include <language/languageexport.h>
class QUrl;
namespace KDevelop {
class SourceFileTemplate;
class DocumentChangeSet;
class TemplateRendererPrivate;
/**
* @brief Convenience class for rendering multiple templates with the same context
*
* The TemplateRenderer provides easy access to common template operations.
* Internally, it encapsulates a Grantlee::Engine and a Grantlee::Context.
*
* It is used by adding a set of variables, and then renderering a template string
* @code
* TemplateRenderer renderer;
* renderer.addVariable("greeting", "Hello");
* renderer.addVariable("target", "World");
* QString text = renderer.render("{{ greeting }}, {{ target }}!");
* // text == "Hello, World!"
* @endcode
*
* If you wish to include other templates using the Grantlee {% include %} tag,
* make sure TemplateRenderer can find those template by using
* addTemplateDirectories() and addArchive(). This adds everything in the specified
* directories or archive files to the list of files search for inclusion.
*
* Directories named "kdevcodegen/templates" in the "data" resource type are always included in the search path,
* there is no need to add them explicitly. Additionally, TemplateRenderer adds the "lib" resource directories
* to the Grantlee plugin search path, so plugins installed there will be available to templates.
*
**/
class KDEVPLATFORMLANGUAGE_EXPORT TemplateRenderer
{
public:
/**
* Policy for working with empty lines
**/
enum EmptyLinesPolicy
{
/**
* Keep empty lines as they are in the rendered output.
* The output from the template is returned unmodified.
*/
KeepEmptyLines,
/**
* If the template output has more than one line, the renderer
* performs a smart trim on the rendered output.
* @li single empty lines are removed
* @li two or more consecutive empty lines are compressed into a single empty line
* @li a single empty line is kept at the end
*/
TrimEmptyLines,
/**
* Removes all empty lines from the template output, and appends a newline at the end if needed.
*/
RemoveEmptyLines
};
TemplateRenderer();
virtual ~TemplateRenderer();
/**
* Adds @p variables to the Grantlee::Context passed to each template.
*
* If the context already contains a variables with the same name as a key in @p variables,
* it is overwritten.
*
**/
void addVariables(const QVariantHash& variables);
/**
* Adds variable with name @p name and value @p value to the Grantlee::Context passed to each template.
*
* If the context already contains a variables with the same @p name, it is overwritten.
*
**/
void addVariable(const QString& name, const QVariant& value);
/**
* Returns the current variables defined for this renderer
*
* @sa addVariable(), addVariables()
*/
QVariantHash variables() const;
/**
* @brief Renders a single template
*
* Any rendering errors are reported by errorString().
* If there were no errors, errorString() will return an empty string.
*
* @param content the template content
* @param name (optional) the name of this template
* @return the rendered template
**/
QString render(const QString& content, const QString& name = QString());
/**
* @brief Renders a single template from a file
*
* Any rendering errors are reported by errorString().
* If there were no errors, errorString() will return an empty string.
*
* @param url the URL of the file from which to load the template
* @param name (optional) the name of this template
* @return the rendered template
**/
QString renderFile(const QUrl& url, const QString& name = QString());
/**
* @brief Renders a list of templates
*
* This is a convenience method, suitable if you have to render a large number of templates
* with the same context.
*
* @param contents the template contents
* @return the rendered templates
**/
QStringList render(const QStringList& contents);
/**
* @brief Sets the policy for empty lines in the rendered output
*
* The default is KeepEmptyLines, where the template output is return unmodified.
*
* @param policy policy for empty lines in the rendered output
* @sa EmptyLinesPolicy
*/
void setEmptyLinesPolicy(EmptyLinesPolicy policy);
/**
* Returns the currently set policy for empty lines in the rendered output
* @sa EmptyLinesPolicy, setEmptyLinesPolicy()
*/
EmptyLinesPolicy emptyLinesPolicy() const;
/**
* @brief Renders all templates in the archive represented by @p fileTemplate
*
* Output files are saved to corresponding URLs in @p fileUrls
*
* For each output file, TemplateRenderer add two variables named @c output_file_x
* and @c output_file_x_absolute, where @c x is replaced
* with the file name specified in the template description file.
* The variable name is entirely lowercase and cleaned by replacing
* all non-alphanumerical characters with underscores.
* For example, if the file is named "Public Header" in
* the description file, the variable will be @c output_file_public_heder.
*
* As their name suggests, @c output_file_x contains the relative path from baseUrl() to the URL of the
* x's output location, while @c output_file_x_absolute contains x's absolute output URL.
* Both are available to templates as strings.
*
* @param fileTemplate the source file template to render
* @param baseUrl the base URL used for calculating relative output file URLs
* @param fileUrls maps output file identifiers to desired destination URLs
* @return KDevelop::DocumentChangeSet
*/
DocumentChangeSet renderFileTemplate(const KDevelop::SourceFileTemplate& fileTemplate,
const QUrl& baseUrl, const QHash<QString, QUrl>& fileUrls);
/**
* Returns the error string from the last call to render(), renderFile() or renderFileTemplate().
* If the last render was successful and produced no errors, this function returns an empty string.
*
* @return the last error string
**/
QString errorString() const;
private:
const QScopedPointer<class TemplateRendererPrivate> d_ptr;
Q_DECLARE_PRIVATE(TemplateRenderer)
};
}
#endif // KDEVPLATFORM_TEMPLATERENDERER_H
|
