Home

Awesome

Synth

A Powerful Templating Framework in C++, with a command-line tool and Python module, written by Alvaro J. Genial.

PyPI Version Build Status

Synopsis

Synth is a template framework—a set of components that can be mixed and matched to build the right functionality; furthermore, components are loosely-coupled, designed to be both extensible and replaceable.

Status

Version 1 is released and stable.

Motivation

Synth blurs the line between compile-time and runtime, and it does so by blending three worlds: (a) the static C++ type system; (b) the dynamic values that need to be manipulated and formatted, including those from other languages; and (c) the templates to do so. The name is an allusion to this synthesis process, which combines values to generate new ones (streams, files, strings, numbers, etc.)

Examples

Command-line

echo '{"user": "Dolph Lundgren"}' > context.json
echo 'Howdy, {{ user }}!' > template.txt
cat template.txt | synth -e django -c context.json

Or on Windows:

echo {"user":"Dolph Lundgren"} > context.json
echo Howdy, {{ user }}! > template.txt
type template.txt | synth -e django -c context.json

Python

import synth, sys

def simple_tmpl_example():
    t = synth.Template('Howdy, <TMPL_VAR user>!', 'tmpl')
    c = {'user': 'Dolph Lundgren'}

    # Render to different destinations:
    t.render_to_path("greeting.txt", c)
    t.render_to_file(sys.stdout, c)
    print(t.render_to_string(c))

C++

#include <map>
#include <string>
#include <iostream>
#include <ajg/synth.hpp>

typedef ajg::synth::default_traits<char>                    traits_type;
typedef ajg::synth::engines::ssi::engine<traits_type>       engine_type;
typedef ajg::synth::templates::string_template<engine_type> template_type;

int main() {
    // Parse the template.
    template_type const t(
        "Howdy, <!--#echo var='user' -->! "
        "Your balance is <!--#echo var='points' -->.");

    // Create some data.
    std::map<std::string, engine_type::value_type> m;
    m["user"] = "Dolph Lundgren";
    m["points"] = 42;

    // Render to different destinations:
    t.render_to_stream(std::cout, m);
    t.render_to_path("greeting.txt", m);
    std::cout << t.render_to_string(m);
    return 0;
}

Reference

Command-line

USAGE: synth [OPTIONS...]
Options:
  -h,      --help              print help message
  -v,      --version           print library version
  -c file, --context=file      contextual data             *.{ini,json,xml}
  -e name, --engine=name       template engine             {django,ssi,tmpl}
  -d path, --directory=path    template location(s)        (default: '.')

Installation

Via System Package Manager

Using Homebrew:

brew install https://raw.github.com/ajg/synth/master/synth.rb
# Note that you must append `--with-python` to install the Python module.

Using Chocolatey:

choco install synth

Support for other system package managers like Apt or Yum is welcome.

Via Python Package Manager

Note that these will only install the Python module.

Using Pip:

pip install pip --upgrade # Ensure wheel support
pip install synth # Prefix with `sudo` if needed.

Using Easy Install:

easy_install synth # Prefix with `sudo` if needed.

If possible, use Pip instead.

From Source:

  1. Ensure you have the following:

  1. Get the source (e.g. the latest, as shown here):

    git clone --depth 1 --recursive https://github.com/ajg/synth.git && cd synth

  2. Optionally, build the command-line tool:

    scons synth # Add debug=1 to generate debugging symbols & disable optimizations.

    (Note that if you are hell bent on it, you can use a different version of Boost; see Infrequently Asked Questions.)

  3. Optionally, build (and install) the Python module:

    python setup.py install # Prefix with `sudo` if needed.
<!-- TODO: Figure out how to include submodules in tarballs & zipballs. 2. Get the source (pick your poison): - With Git: git clone --depth 1 --recursive https://github.com/ajg/synth.git && cd synth - With Curl: curl -L https://github.com/ajg/synth/archive/master.tar.gz | tar xz && cd synth-master - Otherwise, try using https://github.com/ajg/synth/archive/master.zip -->

Components

Engines

Bindings

Templates

Adapters

Base Components

Other Components

Version

Configuration

Context Data Input Formats

Django Engine

Tags

Filters

Formats

(Note: Django's TEMPLATE_DEBUG and TEMPLATE_DIRS are handled through options::debug and options::directories, respectively.)

SSI Engine

Tags

Formats

TMPL Engine

Tags

Options

Future Work

Infrequently Asked Questions

License

This library is distributed under the Boost LICENSE.