Skip to content

[mustache_template] Adopt code-excerpts for README #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
DaNiELChIoRo wants to merge 1 commit into from
Closed

[mustache_template] Adopt code-excerpts for README #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions third_party/packages/mustache_template/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
## 2.0.6

* Adopts `code-excerpt` for the README's Dart snippets so they're validated
against compilable, analyzed source (fixes an invalid snippet and a
copy-pasted duplicate example that had gone unnoticed).
* Removes the `exempt_from_excerpts` CI opt-out now that the README is
excerpt-backed.

## 2.0.5

* Updates metadata for move to https://github.com/flutter/core-packages.
Expand Down
119 changes: 63 additions & 56 deletions third_party/packages/mustache_template/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
<?code-excerpt path-base="example/lib"?>

# Mustache templates

A Dart library to parse and render [mustache templates](https://mustache.github.io/).
Expand All @@ -7,29 +9,27 @@ See the [mustache manual](https://mustache.github.io/mustache.5.html) for detail
This library passes all [mustache specification](https://github.com/mustache/spec/tree/master/specs) tests.

## Example usage

<?code-excerpt "readme_excerpts.dart (BasicUsage)"?>
```dart
import 'package:mustache_template/mustache_template.dart';

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

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

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

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

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

final output = template.renderString(<String, Object>{
'names': <Map<String, String>>[
<String, String>{'firstname': 'Greg', 'lastname': 'Lowe'},
<String, String>{'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.
Expand All @@ -53,65 +53,72 @@ By default all output from `{{variable}}` tags is html escaped, this behaviour c

## Nested paths

<?code-excerpt "readme_excerpts.dart (NestedPaths)"?>
```dart
var t = Template('{{ author.name }}');
var output = template.renderString({'author': {'name': 'Greg Lowe'}});
final template = Template('{{ author.name }}');
final output = template.renderString(<String, Object>{
'author': <String, String>{'name': 'Greg Lowe'},
});
```

## Partials - example usage

<?code-excerpt "readme_excerpts.dart (Partials)"?>
```dart
final partial = Template('{{ foo }}', name: 'partial');

Template? resolver(String name) {
if (name == 'partial-name') {
// Name of partial tag.
return partial;
}
return null;
}

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

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

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

var output = t.renderString({'foo': 'bar'}); // bar
final template = Template('{{> partial-name }}', partialResolver: resolver);

final output = template.renderString(<String, String>{'foo': 'bar'}); // bar
```

## Lambdas - example usage

<?code-excerpt "readme_excerpts.dart (LambdaReturningValue)"?>
```dart
var t = Template('{{# foo }}');
var lambda = (_) => 'bar';
t.renderString({'foo': lambda}); // bar
```

```dart
var t = Template('{{# foo }}hidden{{/ foo }}');
var lambda = (_) => 'shown';
t.renderString('foo': lambda); // shown
final template = Template('{{# foo }}inner{{/ foo }}');
Object lambda(Object? _) => 'bar';
final output = template.renderString(<String, Object>{'foo': lambda}); // bar
```

<?code-excerpt "readme_excerpts.dart (LambdaHidingSection)"?>
```dart
var t = Template('{{# foo }}oi{{/ foo }}');
var lambda = (LambdaContext ctx) => '<b>${ctx.renderString().toUpperCase()}</b>';
t.renderString({'foo': lambda}); // <b>OI</b>
final template = Template('{{# foo }}hidden{{/ foo }}');
Object lambda(Object? _) => 'shown';
final output = template.renderString(<String, Object>{'foo': lambda}); // shown
```

<?code-excerpt "readme_excerpts.dart (LambdaWithContext)"?>
```dart
var t = Template('{{# foo }}{{bar}}{{/ foo }}');
var lambda = (LambdaContext ctx) => '<b>${ctx.renderString().toUpperCase()}</b>';
t.renderString({'foo': lambda, 'bar': 'pub'}); // <b>PUB</b>
final template = Template('{{# foo }}oi{{/ foo }}');
Object lambda(LambdaContext ctx) => '<b>${ctx.renderString().toUpperCase()}</b>';
final output = template.renderString(<String, Object>{'foo': lambda}); // <b>OI</b>
```

<?code-excerpt "readme_excerpts.dart (LambdaWithContextAndVariables)"?>
```dart
var t = Template('{{# foo }}{{bar}}{{/ foo }}');
var lambda = (LambdaContext ctx) => '<b>${ctx.renderString().toUpperCase()}</b>';
t.renderString({'foo': lambda, 'bar': 'pub'}); // <b>PUB</b>
final template = Template('{{# foo }}{{bar}}{{/ foo }}');
Object lambda(LambdaContext ctx) => '<b>${ctx.renderString().toUpperCase()}</b>';
final output = template.renderString(<String, Object>{'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.

<?code-excerpt "readme_excerpts.dart (LambdaReparsingSource)"?>
```dart
var t = Template('{{# foo }}{{bar}}{{/ foo }}');
var lambda = (LambdaContext ctx) => ctx.renderSource(ctx.source + ' {{cmd}}');
t.renderString({'foo': lambda, 'bar': 'pub', 'cmd': 'build'}); // pub build
final template = Template('{{# foo }}{{bar}}{{/ foo }}');
Object lambda(LambdaContext ctx) => ctx.renderSource('${ctx.source} {{cmd}}');
final output = template.renderString(<String, Object>{
'foo': lambda,
'bar': 'pub',
'cmd': 'build',
}); // pub build
```
2 changes: 0 additions & 2 deletions third_party/packages/mustache_template/ci_config.yaml
View file
Open in desktop

This file was deleted.

116 changes: 116 additions & 0 deletions third_party/packages/mustache_template/example/lib/readme_excerpts.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
// ignore_for_file: avoid_print

import 'package:mustache_template/mustache_template.dart';

void basicUsage() {
// #docregion BasicUsage
final source = '''
{{# names }}
<div>{{ lastname }}, {{ firstname }}</div>
{{/ names }}
{{^ names }}
<div>No names.</div>
{{/ names }}
{{! I am a comment. }}
''';

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

final output = template.renderString(<String, Object>{
'names': <Map<String, String>>[
<String, String>{'firstname': 'Greg', 'lastname': 'Lowe'},
<String, String>{'firstname': 'Bob', 'lastname': 'Johnson'},
],
});
// #enddocregion BasicUsage
print(output);
}

void nestedPaths() {
// #docregion NestedPaths
final template = Template('{{ author.name }}');
final output = template.renderString(<String, Object>{
'author': <String, String>{'name': 'Greg Lowe'},
});
// #enddocregion NestedPaths
print(output);
}

void partials() {
// #docregion Partials
final partial = Template('{{ foo }}', name: 'partial');

Template? resolver(String name) {
if (name == 'partial-name') {
// Name of partial tag.
return partial;
}
return null;
}

final template = Template('{{> partial-name }}', partialResolver: resolver);

final output = template.renderString(<String, String>{'foo': 'bar'}); // bar
// #enddocregion Partials
print(output);
}

void lambdaReturningValue() {
// #docregion LambdaReturningValue
final template = Template('{{# foo }}inner{{/ foo }}');
Object lambda(Object? _) => 'bar';
final output = template.renderString(<String, Object>{'foo': lambda}); // bar
// #enddocregion LambdaReturningValue
print(output);
}

void lambdaHidingSection() {
// #docregion LambdaHidingSection
final template = Template('{{# foo }}hidden{{/ foo }}');
Object lambda(Object? _) => 'shown';
final output = template.renderString(<String, Object>{'foo': lambda}); // shown
// #enddocregion LambdaHidingSection
print(output);
}

void lambdaWithContext() {
// #docregion LambdaWithContext
final template = Template('{{# foo }}oi{{/ foo }}');
Object lambda(LambdaContext ctx) => '<b>${ctx.renderString().toUpperCase()}</b>';
final output = template.renderString(<String, Object>{'foo': lambda}); // <b>OI</b>
// #enddocregion LambdaWithContext
print(output);
}

void lambdaWithContextAndVariables() {
// #docregion LambdaWithContextAndVariables
final template = Template('{{# foo }}{{bar}}{{/ foo }}');
Object lambda(LambdaContext ctx) => '<b>${ctx.renderString().toUpperCase()}</b>';
final output = template.renderString(<String, Object>{'foo': lambda, 'bar': 'pub'}); // <b>PUB</b>
// #enddocregion LambdaWithContextAndVariables
print(output);
}

void lambdaReparsingSource() {
// #docregion LambdaReparsingSource
final template = Template('{{# foo }}{{bar}}{{/ foo }}');
Object lambda(LambdaContext ctx) => ctx.renderSource('${ctx.source} {{cmd}}');
final output = template.renderString(<String, Object>{
'foo': lambda,
'bar': 'pub',
'cmd': 'build',
}); // pub build
// #enddocregion LambdaReparsingSource
print(output);
}

void main() {
basicUsage();
nestedPaths();
partials();
lambdaReturningValue();
lambdaHidingSection();
lambdaWithContext();
lambdaWithContextAndVariables();
lambdaReparsingSource();
}
10 changes: 10 additions & 0 deletions third_party/packages/mustache_template/example/pubspec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
name: mustache_template_example
description: Example code for the mustache_template package.
publish_to: none

environment:
sdk: ^3.10.0

dependencies:
mustache_template:
path: ../
2 changes: 1 addition & 1 deletion third_party/packages/mustache_template/pubspec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: mustache_template
description: A templating library that implements the Mustache template specification
repository: https://github.com/flutter/core-packages/tree/main/third_party/packages/mustache_template
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+mustache_template%22
version: 2.0.5
version: 2.0.6

environment:
sdk: ^3.10.0
Expand Down