Repository files navigation

mstch is a complete implementation of{{mustache}}templates using modern C++. It's compliant withspecificationsv1.1.3, including the lambda module.

mstch supports the complete feature set described in themustache(5)manpage:

• JSON-like data structure usingBoost.Variant
• variables, sections, inverted sections
• partials
• changing the delimiter
• C++11 lambdas
• C++ objects as view models

#include<iostream>#include<mstch/mstch.hpp>intmain() {  std::string view{"{{#names}}Hi {{name}}!\n{{/names}}"};  mstch::map context{    {"names", mstch::array{      mstch::map{{"name", std::string{"Chris"}}},      mstch::map{{"name", std::string{"Mark"}}},      mstch::map{{"name", std::string{"Scott"}}},    }}  };    std::cout <<mstch::render(view, context) << std::endl;return0;}

The output of this example will be:

Hi Chris!Hi Mark!Hi Scott!

The types in the example above,mstch::array andmstch::map are actuallyaliases for standard types:

using map = std::map<const std::string, node>;using array = std::vector<node>;

mstch::node is aboost::variant that can hold astd::string,int,double,bool,mstch::lambda or astd::shared_ptr<mstch::object>(see below), also a map or an array recursively. Essentially it works just likea JSON object.

Note that when using astd::string as value you must explicitly specify thetype, since aconst char* literal like"foobar" would be implicitlyconverted tobool. Alternatively you can useC++14 string_literalsif your compiler supports it.

Partials can be passed in astd::map as the third parameter of themstch::render function:

std::string view{"{{#names}}{{> user}}{{/names}}"};std::string user_view{"<strong>{{name}}\n</strong>"};mstch::map context{  {"names", mstch::array{    mstch::map{{"name", std::string{"Chris"}}},    mstch::map{{"name", std::string{"Mark"}}},    mstch::map{{"name", std::string{"Scott"}}},  }}};  std::cout << mstch::render(view, context, {{"user", user_view}}) << std::endl;

Output:

<strong>Chris</strong><strong>Mark</strong><strong>Scott</strong>

C++11 lambda expressions can be used to add logic to your templates. Like aconst char* literal, lambdas can be implicitly converted tobool, so theymust be wrapped in amstch::lambda object when used in amstch::node. Thelambda expression passed tomstch::lambda must itself return amstch::node.The returned node will be rendered to a string, then it will be parsed as atemplate.

The lambda expression accepts either no parameters:

std::string view{"Hello {{lambda}}!"};mstch::map context{  {"lambda", mstch::lambda{[]() -> mstch::node {return std::string{"World"};  }}}};std::cout << mstch::render(view, context) << std::endl;

Output:

Hello World!

Or it accepts aconst std::string& that gets the unrendered literal block:

std::string view{"{{#bold}}{{yay}} :){{/bold}}"};mstch::map context{  {"yay", std::string{"Yay!"}},  {"bold", mstch::lambda{[](const std::string& text) -> mstch::node {return"<b>" + text +"</b>";  }}}};std::cout << mstch::render(view, context) << std::endl;

Output:

<b>Yay! :)</b>

Custom objects can also be used as context for rendering templates. The classmust inherit frommstch::object, and register it's exported methods withregister_methods. Exported methods must have the return type ofmstch::node.Objects must be created as astd::shared_ptr.

classexample:publicmstch::object {public:example(): m_value(1) {register_methods(this, {      {"count", &example::count},      {"names", &example::names}      });  }    mstch::nodecount() {return m_value++;  }    mstch::nodenames() {return mstch::array{      std::string{"Chris"}, std::string{"Mark"}, std::string{"Scott"}};  }private:int m_value;};std::string view{"{{#names}}<b>{{count}}</b>: {{.}}\n{{/names}}"};constauto context = std::make_shared<example>();std::cout << mstch::render(view, context) << std::endl;

Output:

<b>1</b>: Chris<b>2</b>: Mark<b>3</b>: Scott

By default, mstch uses HTML escaping on the output, as per specification. Thisis not useful if your output is not HTML, so mstch provides a way to supplyyour own escape implementation. Just assign any callable object to the staticmstch::config::escape, which is an initially emptystd::function<std::string(const std::string&)>.

For example you can turn off escaping entirely with a lambda:

mstch::config::escape = [](const std::string& str) -> std::string {return str;};

• A C++ compiler with decent C++11 support. Currently tested with:
  • GCC 4.7, 4.8, 4.9, 5.1
  • clang 3.5, 3.6, 3.7 (both libstdc++ and libc++ are supported)
  • MSVC 2013, 2015
• Boost 1.54+ forBoost.Variant
• CMake 3.0+ for building

If you are using CMake, the easiest way to include mstch in your project is tocopy the whole directory to your source tree, and useadd_subdirectory in yourCMakeLists.txt. This will set a variable namedmstch_INCLUDE_DIR that containsits include path, and add a static library target namedmstch. For example:

add_subdirectory(external/mstch)include_directories(${mstch_INCLUDE_DIR})target_link_libraries(your_project mstch)

If you prefer to install the library globally, you can simply do the followingfrom the root of the source tree:

 $ mkdir build $cd build $ cmake .. $ make $ make install

The install command may require root privileges. This will also install CMakeconfig files, so you can use usefind_package in your CMakeLists.txt:

find_package(mstch)target_link_libraries(your_project mstch::mstch)

Unit tests are using theCatch frameworkandrapidjson to parse theMustache specifications, all of which areincluded in the repository as git submodules. VariousBoost libraries are also required to build them.

Don't forget to initialize submodules:

 $ git submodule init $ git submodule update

To build and run the unit tests:

 $ mkdir build $cd build $ cmake -DWITH_UNIT_TESTS=ON .. $ make $ maketest

mstch is licensed under theMIT license.