kde-extraapps/kdevplatform/language/codegen/templaterenderer.h

209 lines
7.4 KiB
C
Raw Normal View History

/*
* 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 "../languageexport.h"
class KUrl;
namespace KDevelop
{
class TemplateEngine;
class SourceFileTemplate;
class DocumentChangeSet;
/**
* @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()) const;
/**
* @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 KUrl& url, const QString& name = QString()) const;
/**
* @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 content the template contents
* @return the rendered templates
**/
QStringList render(const QStringList& contents) const;
/**
* @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 KUrl& baseUrl, const QHash<QString, KUrl>& 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:
class TemplateRendererPrivate* const d;
};
}
#endif // KDEVPLATFORM_TEMPLATERENDERER_H