mustache 1.1.1

  • Readme
  • Changelog
  • Installing
  • 79

Mustache templates #

A Dart library to parse and render mustache templates.

Build Status Coverage Status

See the mustache manual for detailed usage information.

This library passes all mustache specification tests.

Example usage #

import 'package:mustache/mustache.dart';

main() {
	var source = '''
	  {{# names }}
            <div>{{ lastname }}, {{ firstname }}</div>
	  {{/ names }}
	  {{^ names }}
	    <div>No names.</div>
	  {{/ names }}
	  {{! I am a comment. }}

	var template = new Template(source, name: 'template-filename.html');

	var output = template.renderString({'names': [
		{'firstname': 'Greg', 'lastname': 'Lowe'},
		{'firstname': 'Bob', 'lastname': 'Johnson'}


A template is parsed when it is created, after parsing it can be rendered any number of times with different values. A TemplateException is thrown if there is a problem parsing or rendering the template.

The Template contstructor allows passing a name, this name will be used in error messages. When working with a number of templates, it is important to pass a name so that the error messages specify which template caused the error.

By default all output from {{variable}} tags is html escaped, this behaviour can be changed by passing htmlEscapeValues : false to the Template constructor. You can also use a {{{triple mustache}}} tag, or a unescaped variable tag {{&unescaped}}, the output from these tags is not escaped.

Dart2js #

This library uses mirrors. When compiling with dart2js you will need to pass the experimental mirrors flag. You also need to mark any objects which will be rendered with the @mustache annotation. There is also another version of this library available which doesn't use mirrors.

Differences between strict mode and lenient mode. #

Strict mode (default) #

  • Tag names may only contain the characters a-z, A-Z, 0-9, underscore, period and minus. Other characters in tags will cause a TemplateException to be thrown during parsing.

  • During rendering, if no map key or object member which matches the tag name is found, then a TemplateException will be thrown.

Lenient mode #

  • Tag names may use any characters.
  • During rendering, if no map key or object member which matches the tag name is found, then silently ignore and output nothing.

Nested paths #

  var t = new Template('{{ }}');
  var output = template.renderString({'author': {'name': 'Greg Lowe'}});

Partials - example usage #

var partial = new Template('{{ foo }}', name: 'partial');

var resolver = (String name) {
   if (name == 'partial-name') { // Name of partial tag.
     return partial;

var t = new Template('{{> partial-name }}', partialResolver: resolver);

var output = t.renderString({'foo': 'bar'}); // bar

Lambdas - example usage #

var t = new Template('{{# foo }}');
var lambda = (_) => 'bar';
t.renderString({'foo': lambda}); // bar
var t = new Template('{{# foo }}hidden{{/ foo }}');
var lambda = (_) => 'shown'};
t.renderString({'foo': lambda); // shown
var t = new Template('{{# foo }}oi{{/ foo }}');
var lambda = (LambdaContext ctx) => '<b>${ctx.renderString().toUpperCase()}</b>';
t.renderString({'foo': lambda}); // <b>OI</b>
var t = new Template('{{# foo }}{{bar}}{{/ foo }}');
var lambda = (LambdaContext ctx) => '<b>${ctx.renderString().toUpperCase()}</b>';
t.renderString({'foo': lambda, 'bar': 'pub'}); // <b>PUB</b>
var t = new Template('{{# foo }}{{bar}}{{/ foo }}');
var lambda = (LambdaContext ctx) => '<b>${ctx.renderString().toUpperCase()}</b>';
t.renderString({'foo': lambda, 'bar': 'pub'}); // <b>PUB</b>

In the following example LambdaContext.renderSource(source) re-parses the source string in the current context, this is the default behaviour in many mustache implementations. Since re-parsing the content is slow, and often not required, this library makes this step optional.

var t = new Template('{{# foo }}{{bar}}{{/ foo }}');
var lambda = (LambdaContext ctx) => ctx.renderSource(ctx.source + ' {{cmd}}')};
t.renderString({'foo': lambda, 'bar': 'pub', 'cmd': 'build'}); // pub build


1.1.1 #

  • Fixed error "boolean expression must not be null". Thanks Nico.

1.1.0 #

  • Better support for class members in sections. Thanks to Janice Collins.
  • Set the SDK constraint to Dart 2+.

1.0.2 #

Set the max SDK constraint to <3.0.0.

0.2.5 #

  • Remove MustacheFormatException
  • Allow templates to specify default delimiters. Thanks to Joris Hermans.
  • Fix #24: renderString shrinks multiple newlines to just one (Thanks to John Ryan for the repro).

0.2.4 #

  • Fix #23 failure if tag or comment contains "="

0.2.3 #

  • Change handling of lenient sections to match python mustache implementation.

0.2.2 #

  • Fix MirrorsUsed tag for using mirrors on dart2js.
  • Clean up dead code.

0.2.1 #

  • Added new methods to LambdaContext.

0.2 #

  • Deprecated parse() function - please update your code to use new Template(source).
  • Deprecated MustacheFormatException - please update your code to use TemplateException.
  • Breaking change: Template.render and Template.renderString methods no longer take the optional lenient and htmlEscapeValues. These should now be passed to the Template constructor.
  • Fully passing all mustache spec tests.
  • Added support for MirrorsUsed.
  • Implemented partials. #11
  • Implemented lambdas. #4
  • Implemented change delimiter tag.
  • Add template name parameter, and show this in error messages.
  • Allow whitespace at begining of tags. #10

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  mustache: ^1.1.1

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:mustache/mustache.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on May 23, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.1
  • pana: 0.13.8-dev

Health suggestions

Fix lib/src/parser.dart. (-15.25 points)

Analysis of lib/src/parser.dart reported 33 hints, including:

line 10 col 16: Unnecessary new keyword.

line 26 col 38: Avoid const keyword.

line 27 col 45: Avoid const keyword.

line 28 col 39: Avoid const keyword.

line 29 col 35: Avoid const keyword.

Fix lib/src/scanner.dart. (-11.78 points)

Analysis of lib/src/scanner.dart reported 25 hints, including:

line 29 col 13: Unnecessary new keyword.

line 41 col 31: Unnecessary new keyword.

line 64 col 21: Unnecessary new keyword.

line 89 col 23: Unnecessary new keyword.

line 128 col 13: Unnecessary new keyword.

Fix lib/src/renderer.dart. (-9.99 points)

Analysis of lib/src/renderer.dart reported 21 hints, including:

line 3 col 2: 'MirrorsUsed' is deprecated and shouldn't be used. No longer has any effect. Will be removed in a later release..

line 3 col 27: Avoid const keyword.

line 11 col 26: Unnecessary new keyword.

line 12 col 28: Unnecessary new keyword.

line 14 col 31: Avoid const keyword.

Fix additional 5 files with analysis or formatting issues. (-12.83 points)

Additional issues in the following files:

  • lib/src/token.dart (9 hints)
  • lib/src/lambda_context.dart (7 hints)
  • lib/src/template.dart (5 hints)
  • lib/mustache.dart (3 hints)
  • lib/src/node.dart (2 hints)

Maintenance suggestions

Package is getting outdated. (-30.14 points)

The package was last published 67 weeks ago.

The package description is too short. (-20 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Maintain an example.

None of the files in the package's example/ directory matches known example patterns.

Common filename patterns include main.dart, example.dart, and mustache.dart. Packages with multiple examples should provide example/

For more information see the pub package layout conventions.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
Dev dependencies
test >=0.12.0 <2.0.0