mirror of https://github.com/CrowCpp/Crow.git
Merge 342fa45108
into 1b6a4f4301
This commit is contained in:
commit
106ed42563
|
@ -1,3 +1,9 @@
|
|||
/**
|
||||
* \file crow/mustache.h
|
||||
* \brief This file includes the definition of the crow::mustache
|
||||
* namespace and its members.
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
#include <string>
|
||||
#include <vector>
|
||||
|
@ -9,14 +15,39 @@
|
|||
#include "crow/returnable.h"
|
||||
#include "crow/utility.h"
|
||||
|
||||
namespace crow
|
||||
namespace crow // NOTE: Already documented in "crow/app.h"
|
||||
{
|
||||
/**
|
||||
* \namespace crow::mustache
|
||||
* \brief In this namespace is defined most of the functions and
|
||||
* classes related to template rendering.
|
||||
*
|
||||
* If you are here you might want to read these functions and
|
||||
* classes:
|
||||
*
|
||||
* - \ref template_t
|
||||
* - \ref load_text
|
||||
* - \ref load_text_unsafe
|
||||
* - \ref load
|
||||
* - \ref load_unsafe
|
||||
*
|
||||
* As name suggest, crow uses [mustache](https://en.wikipedia.org/wiki/Mustache_(template_system))
|
||||
* as main template rendering system.
|
||||
*
|
||||
* You may be interested in taking a look at the [Templating guide
|
||||
* page](https://crowcpp.org/master/guides/templating/).
|
||||
*/
|
||||
namespace mustache
|
||||
{
|
||||
using context = json::wvalue;
|
||||
|
||||
template_t load(const std::string& filename);
|
||||
|
||||
/**
|
||||
* \class invalid_template_exception
|
||||
* \brief Represents compilation error of an template. Throwed
|
||||
* specially at mustache compile time.
|
||||
*/
|
||||
class invalid_template_exception : public std::exception
|
||||
{
|
||||
public:
|
||||
|
@ -30,6 +61,15 @@ namespace crow
|
|||
std::string msg;
|
||||
};
|
||||
|
||||
/**
|
||||
* \struct rendered_template
|
||||
* \brief Returned object after call the
|
||||
* \ref template_t::render() method. Its intended to be
|
||||
* returned during a **rule declaration**.
|
||||
*
|
||||
* \see \ref CROW_ROUTE
|
||||
* \see \ref CROW_BP_ROUTE
|
||||
*/
|
||||
struct rendered_template : returnable
|
||||
{
|
||||
rendered_template():
|
||||
|
@ -46,6 +86,13 @@ namespace crow
|
|||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* \enum ActionType
|
||||
* \brief Used in \ref Action to represent different parsing
|
||||
* behaviors.
|
||||
*
|
||||
* \see \ref Action
|
||||
*/
|
||||
enum class ActionType
|
||||
{
|
||||
Ignore,
|
||||
|
@ -57,6 +104,14 @@ namespace crow
|
|||
Partial,
|
||||
};
|
||||
|
||||
/**
|
||||
* \struct Action
|
||||
* \brief Used during mustache template compilation to
|
||||
* represent parsing actions.
|
||||
*
|
||||
* \see \ref compile
|
||||
* \see \ref template_t
|
||||
*/
|
||||
struct Action
|
||||
{
|
||||
int start;
|
||||
|
@ -69,7 +124,12 @@ namespace crow
|
|||
}
|
||||
};
|
||||
|
||||
/// A mustache template object.
|
||||
/**
|
||||
* \class template_t
|
||||
* \brief Compiled mustache template object.
|
||||
*
|
||||
* \warning Use \ref compile instead.
|
||||
*/
|
||||
class template_t
|
||||
{
|
||||
public:
|
||||
|
@ -626,10 +686,13 @@ namespace crow
|
|||
std::string body_;
|
||||
};
|
||||
|
||||
/// \brief The function that compiles a source into a mustache
|
||||
/// template.
|
||||
inline template_t compile(const std::string& body)
|
||||
{
|
||||
return template_t(body);
|
||||
}
|
||||
|
||||
namespace detail
|
||||
{
|
||||
inline std::string& get_template_base_directory_ref()
|
||||
|
@ -646,6 +709,9 @@ namespace crow
|
|||
}
|
||||
} // namespace detail
|
||||
|
||||
/// \brief The default way that \ref load, \ref load_unsafe,
|
||||
/// \ref load_text and \ref load_text_unsafe use to read the
|
||||
/// contents of a file.
|
||||
inline std::string default_loader(const std::string& filename)
|
||||
{
|
||||
std::string path = detail::get_template_base_directory_ref();
|
||||
|
@ -667,6 +733,8 @@ namespace crow
|
|||
}
|
||||
} // namespace detail
|
||||
|
||||
/// \brief Defines the templates directory path at **route
|
||||
/// level**. By default is `templates/`.
|
||||
inline void set_base(const std::string& path)
|
||||
{
|
||||
auto& base = detail::get_template_base_directory_ref();
|
||||
|
@ -678,6 +746,8 @@ namespace crow
|
|||
}
|
||||
}
|
||||
|
||||
/// \brief Defines the templates directory path at **global
|
||||
/// level**. By default is `templates/`.
|
||||
inline void set_global_base(const std::string& path)
|
||||
{
|
||||
auto& base = detail::get_global_template_base_directory_ref();
|
||||
|
@ -689,11 +759,22 @@ namespace crow
|
|||
}
|
||||
}
|
||||
|
||||
/// \brief Change the way that \ref load, \ref load_unsafe,
|
||||
/// \ref load_text and \ref load_text_unsafe reads a file.
|
||||
///
|
||||
/// By default, the previously mentioned functions load files
|
||||
/// using \ref default_loader, that only reads a file and
|
||||
/// returns a std::string.
|
||||
inline void set_loader(std::function<std::string(std::string)> loader)
|
||||
{
|
||||
detail::get_loader_ref() = std::move(loader);
|
||||
}
|
||||
|
||||
/// \brief Open, read and sanitize a file but returns a
|
||||
/// std::string without a previous rendering process.
|
||||
///
|
||||
/// Except for the **sanitize process** this function does the
|
||||
/// almost the same thing that \ref load_text_unsafe.
|
||||
inline std::string load_text(const std::string& filename)
|
||||
{
|
||||
std::string filename_sanitized(filename);
|
||||
|
@ -701,11 +782,33 @@ namespace crow
|
|||
return detail::get_loader_ref()(filename_sanitized);
|
||||
}
|
||||
|
||||
/// \brief Open and read a file but returns a std::string
|
||||
/// without a previous rendering process.
|
||||
///
|
||||
/// This function is more like a helper to reduce code like
|
||||
/// this...
|
||||
///
|
||||
/// ```cpp
|
||||
/// std::ifstream file("home.html");
|
||||
/// return std::string({std::istreambuf_iterator<char>(file), std::istreambuf_iterator<char>()});
|
||||
/// ```
|
||||
///
|
||||
/// ... Into this...
|
||||
///
|
||||
/// ```cpp
|
||||
/// return load("home.html");
|
||||
/// ```
|
||||
///
|
||||
/// \warning Usually \ref load_text is more recommended to use
|
||||
/// instead because it may prevent some [XSS Attacks](https://en.wikipedia.org/wiki/Cross-site_scripting).
|
||||
/// **Never blindly trust your users!**
|
||||
inline std::string load_text_unsafe(const std::string& filename)
|
||||
{
|
||||
return detail::get_loader_ref()(filename);
|
||||
}
|
||||
|
||||
/// \brief Open, read and renders a file using a mustache
|
||||
/// compiler. It also sanitize the input before compilation.
|
||||
inline template_t load(const std::string& filename)
|
||||
{
|
||||
std::string filename_sanitized(filename);
|
||||
|
@ -713,6 +816,13 @@ namespace crow
|
|||
return compile(detail::get_loader_ref()(filename_sanitized));
|
||||
}
|
||||
|
||||
/// \brief Open, read and renders a file using a mustache
|
||||
/// compiler. But it **do not** sanitize the input before
|
||||
/// compilation.
|
||||
///
|
||||
/// \warning Usually \ref load is more recommended to use
|
||||
/// instead because it may prevent some [XSS Attacks](https://en.wikipedia.org/wiki/Cross-site_scripting).
|
||||
/// **Never blindly trust your users!**
|
||||
inline template_t load_unsafe(const std::string& filename)
|
||||
{
|
||||
return compile(detail::get_loader_ref()(filename));
|
||||
|
|
Loading…
Reference in New Issue