Crustache, an embeddable templating engine

Hubot mustache me C

CRUSTACHE! Shout it loud when you read it. With anger. It is an (experimental) implementation of the {{Mustache}} templating engine, in C, with the goal of improving the speed of other Mustache implementations in higher level languages.

You should totally try it out. It may blow up your computer. Or it may increase the rendering speed of your native Crustache implementation by up to 40 times. WHO KNOWS WHATS GONNA HAPPEN. DO IT FOR SCIENCE.

Features

Currently Crustache supports all the features available in the original Mustache. Yes, even partials. Ain't that awesome?

• Variables
• Sections (including lambdas, lists, inverted sections)
• Comments
• Partials
• Set tag delimiters

About

Crustache has been written by Vicent Martí (@tanoku). You'll find that following him on Twitter is a Zen-like, enlightening experience.

Try out Crustache.rb!

You probably don't have the time to write a Crustache wrapper for a high level language (even though it's super easy and quick and fun and you should do it anyway), so I've written Crustache.rb as a reference implementation, and to let you try the library out.

Crustache.rb is a simple wrapper that implements a Crustache::Template class, in Ruby. It has the same API as the Mustache::Template class in the original Mustache, so you can use it standalone (works very nicely):

require 'crustache'

Crustache::Template.new(
    'This was rendered with {{mustache}}.').render("mustache" => "crustache")

Or you can do SCIENCE:

# dangerous science ahead -- don't try at home
require 'mustache'
require 'crustache'

# Monkeypatch from hell
Mustache::Template = Crustache::Template

class MyView < Mustache
    ... # Powerman 9000 - When worlds collide
end

# How is this thing even working?

Get your own Crustache!

The main goal of Crustache is acting as a backend for other Mustache implementations. Here's a rough overview on the Crustache API and how to use it.

Note from the author: when you start getting a mild headache and/or a skin rash from this technical documentation, I suggest you check out the reference implementation, Crustache.rb.

Defining the Crustache API

Crustache is data-model-agnostic. That's a fancy way of saying it doesn't really understand about hash tables, lists and so on -- which is a reasonable thing for a C library, given that C doesn't even have strings for shit's sake.

Before rendering a Crustache template, you must define a Crustache API to stablish how the renderer interacts with the different data types in the rendering context.

The Crustache API is defined as a series of callbacks, which the library uses while rendering to gather the relevant variable data.

typedef struct {
	int (*context_find)(crustache_var *, void *context, const char *key, size_t key_size);
	int (*list_get)(crustache_var *, void *list, size_t i);
	int (*lambda)(crustache_var *, void *lambda, const char *raw_template, size_t raw_size);
	void (*var_free)(crustache_var_t type, void *var);

	int (*partial)(crustache_template **partial, const char *partial_name, size_t name_size);
	int free_partials;
} crustache_api;

• int context_find(crustache_var *, void*, const char *, size_t):

  The context_find callback is issued everytime the renderer needs to fetch a variable from the context. You can think of it as a a hash table loookup -- but of course, you can pass anything as a context (a hash table, a class instance...)

  The context will be passed as a void pointer, so you should cast it back to its original type. You can then query it for the variable key.

  The queried variable must be made opaque again and stored in the var pointer so the library can process it.

  The method must return 0 if the variable was found and stored, or a negative value if it was not found or there was an error.

  Here's an example on how to implement context lookups using the Ruby C API:

  static int
  rb_crustache__context_get(crustache_var *var, void *ctx,
      const char *key, size_t key_size)
  {
      VALUE rb_hash = (VALUE)ctx;
      VALUE rb_key, rb_val;
  
      rb_key = rb_str_new(key, (long)key_size);
      rb_val = rb_hash_lookup(rb_ctx, rb_key);
  
      if (NIL_P(rb_val)) /* not found */
          return -1;
  
      rb_crustache__setvar(var, rb_val);
      return 0;
  }

• int (*list_get)(crustache_var *, void *list, size_t i):

  The list_get callback is issued when Crustache needs to access a variable which you have previously defined as a list.

  The list will be passed as a void pointer, which you can cast to whatever your native type is.

  You are then expected to lookup the variable in position i inside the list, and store it in the var pointer so the library can process it.

  The method must return 0 if the variable was found and stored, or a negative value if it was not found or there was an error.

• int (*lambda)(crustache_var *, void *, const char *, size_t):

  The lambda callback is issued when Crustache finds a Section whose tag resolved to a lambda ("callable") object.

  Like in the original Mustache, the lambda callback will receive a string containing part of the original template, which must be processed (or not) by the callback and returned also as a string.

  The returned string will be replaced in the template.

  The method must return 0 if the template fragment was successfully processed, or a negative number otherwise.

• int (*partial)(crustache_template **, const char *, size_t)

  The partial callback is issued when Crustache encounters a partial tag in the original template.

  The name of the template will be passed in the template_name variable, and this name must be resolved to an actual template string (using whatever method you deem reasonable, e.g. look on the filesystem for a file called template_name.mustache).

  The string must then be instantiated as a crustache_template, which will be automatically rendered using the parent template's active context.

  Here's an example implementation:

  static int
  int partial(crustache_template **template,
          const char *tmpl_name, size_t size)
  {
      const char *template_string;
  
      template_string = lookup_template(tmpl_name, size);
      if (template_string == NULL)
          return -1;
  
      return crustache_new(template, &DEFAULT_API,
          template_string, strlen(template_string));
  }

  If the free_templates variable is set to 1, the new template will be freed by the library once it has been rendered.

• void (*var_free)(crustache_var_t type, void *var)

  If this optional callback is not NULL, it will be called everytime Crustache no longer needs a variable for rendering, so it can be freed by whatever means you want.

Using Crustache

Once the interaction API has been defined, using crustache is *sooo* easy:

• int crustache_new(crustache_template **output, crustache_api *api, const char *raw_template, size_t raw_length):

  Create a new Crustache template. The api paremeter is a pointer to your defined API for context interaction. raw_template points to the raw text of the template. A copy of this text will be stored internally by the template.

  The raw template text will be parsed and compiled internally, ready for rendering. The new template will be stored in the output pointer.

  If the compilation or parsing fails, a negative value (error code) will be returned, but the template object will be created anyway. The template object can then be queried for the syntax error(s) in the raw text.

• void crustache_free(crustache_template *template):

  Free an existing Crustache template, once it's no longer needed. Crustache templates must be free'd even if their compilation with crustache_new failed.

• int crustache_render(struct buf *ob, crustache_template *template, crustache_var *context):

  Render a compiled template, and write the rendered output to the ob buffer.

  template is a pointer to a previously compiled template. context is an opaque pointer to the initial context for the template, which will be accessed through the Crustache API.

  The method will return 0 on success, or a negative value (error code) if the rendering failed for whatever reason.

• const char * crustache_error_syntaxline( size_t *line_n, size_t *col_n, size_t *line_len, crustache_template *template):

  Query the detailed information about the last compilation error in the template. The returned value is the exact position in the raw text of the template where the compilation failed. This information will only be available if crustache_new returned an error code.

• void crustache_error_rendernode(char *buffer, size_t size, crustache_template *template):

  Query the detailed information about the last rendering error in the template. The returned value is a textual representation of the Mustache node in the compiled template that could not be rendered with the given context. This information will only be available if crustache_render returned an error code.

• const char * crustache_strerror(int error)

  Get a representative error message from a given error code.