tobys / vmustache

Mustache template system for VIMScript

vmustache - Mustache template system for VIMScript

vmustache is an implementation of the Mustache template system in VIMScript.

Usage

There are two essential functions in vmustache meant to be used directly:

vmustache#RenderString(text, data)

This function parses the template given as the string text and renders it with the data provided in the hashmap data. The result of the rendering is returned as a string. The pedant function

vmustache#RenderFile(file, data)

accepts a file name instead of a string template.

Template syntax

Mustache is a very very simple template language, which has only very few concepts. Basically you can use variables:

This is a text with a {{insert_fancy_data}}

Variables are marked with {{ and }} and can be identified by arbitrary strings. The second concept are blocks:

{{#some_block}}
    Block content with {{some_variable}}
{{/some_block}}

Start of the block is indicated by a #, the end tag is marked with a /. A block can be used to make output optional or repeated for a number of values.

Blocks can also be invered, which is indicated as follows:

{{^inverted_block}}
    Block rendered without data.
{{/inverted_block}}

While normal blocks are only rendered, if data is available, inverted blocks are rendered if there's none.

Providing data

vmustache accepts data in form of a hashmap. The structure of this hashmap must correspond to the structure of the template. For example, if you have the following template:

Hello {{name}}

The provided data map should look like this:

let l:data = {"name": "Luke Skywalker"}

For blocks, you typically provide a list of values. Take the following template:

{{#list}}
  - {{topic}}
{{/list}}

Providing this with the following data:

let l:data = {"list": [ {"topic": "Tokenize"}, {"topic": "Parse"},
    \ {"topic": "Render"} ]}

Will return in the following output:

- Tokenize

- Parse

- Render

Instead of a list with child data for the block, you can also provide just a plain value to make a block optional. For example:

This text will {{#optional}}optionally{{/optional}} appear.

With the data:

let l:data = {"optional": 1}

Will produce:

This text will optionally appear.

While with:

let l:data = {}

It will result in:

This text will appear.

Inverted sections

Inverted sections behave the other way around. So, changing the example from above to

This text will {{^optional}}optionally{{/optional}} appear.

(note the ^ instead of the /), and using the data:

let l:data = {"optional": 1}

will result in

This text will  appear.

while providing no value for "optional"

let l:data = {}

will make the section content be rendered

This text will optionally appear.

Missing features

vmustache does not implement some mustache features (yet?). As there are:

• Unescaped variables
• Partials

The first does not make sense at all, since the output of vmustache is not escaped at all. How should that work without knowing the context. Partials would be nice. If somebody wants them: Feel free to send a pull request. :)

vmustache's Issues

Ideas

This is super-cool. I'm a js/php mustache user for years, love it. Surprised to see an implementation for Vim! How cool! I was wondering what are your use-cases for it, trying to get inspired of how to use it 😄

Add to Travis.CI

Mustache variables from buffer special dictionary

This issue was originally filed by @rafi on PDV: tobyS/pdv#13

It'll be really cool if pdv can load a dictionary from buffer and use it for rendering mustache templates.

Example:

" User can set a viewmodel for pdv per-buffer.
" It's optional, so the user decides how and when this is set.
let b:pdv_mustache_viewmodel = {
    'package': 'Foo',
    'author': 'Bar',
    'copyright': 'Baz',
    ...
}

pdv.vim

" pdv
if exists('b:pdv_mustache_helpers')
    " Merge with current viewmodel
    " ...
endif

templates/class.tpl

/**
 * Class: {{name}}
 * @package    {{package}}
 * @author     {{author}}
 * @copyright  {{copyright}}
 * @license    {{license}}
 * @link       {{link}}
 *{{#interfaces}}
 * @see {{name}}{{/interfaces}}{{#parent}}
 * @see {{name}}{{/parent}}{{#abstract}}
 * @abstract{{/abstract}}{{#final}}
 * @final{{/final}}
 */

Allow access to data in conditional sections

In a conditional section

{{conditional}}Displayed! \o/{{/conditional}}

with data {"conditional": 1}, the value of conditional is not available inside the section.

So

{{not_empty}}{{not_empty}} \o/{{/not_empty}}

would give an error with {"not_empty": "Horay!"}, but it would be desirable to have it.