mustache 1.1.1

  • Readme
  • Changelog
  • Installing
  • 82

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'}
	]});

	print(output);
}

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('{{ author.name }}');
  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

CHANGELOG #

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:


dependencies:
  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';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
94
Health:
Code health derived from static analysis. [more]
75
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
65
Overall:
Weighted score of the above. [more]
82
Learn more about scoring.

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

  • Dart: 2.7.1
  • pana: 0.13.6

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

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.

Package is getting outdated. (-15.34 points)

The package was last published 60 weeks ago.

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/README.md.

For more information see the pub package layout conventions.

Dependencies

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