diff --git a/third_party/packages/mustache_template/CHANGELOG.md b/third_party/packages/mustache_template/CHANGELOG.md index ed2daa26..a8668535 100644 --- a/third_party/packages/mustache_template/CHANGELOG.md +++ b/third_party/packages/mustache_template/CHANGELOG.md @@ -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. diff --git a/third_party/packages/mustache_template/README.md b/third_party/packages/mustache_template/README.md index cf4dab61..5c78450d 100644 --- a/third_party/packages/mustache_template/README.md +++ b/third_party/packages/mustache_template/README.md @@ -1,3 +1,5 @@ + + # Mustache templates A Dart library to parse and render [mustache templates](https://mustache.github.io/). @@ -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 + + ```dart -import 'package:mustache_template/mustache_template.dart'; - -main() { - var source = ''' - {{# names }} -
{{ lastname }}, {{ firstname }}
- {{/ names }} - {{^ names }} -
No names.
- {{/ 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 }} +
{{ lastname }}, {{ firstname }}
+{{/ names }} +{{^ names }} +
No names.
+{{/ names }} +{{! I am a comment. }} +'''; + + final template = Template(source, name: 'template-filename.html'); + + final 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. @@ -53,65 +53,72 @@ By default all output from `{{variable}}` tags is html escaped, this behaviour c ## Nested paths + ```dart - var t = Template('{{ author.name }}'); - var output = template.renderString({'author': {'name': 'Greg Lowe'}}); +final template = Template('{{ author.name }}'); +final output = template.renderString({ + 'author': {'name': 'Greg Lowe'}, +}); ``` ## Partials - example usage + ```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({'foo': 'bar'}); // bar ``` ## Lambdas - example usage + ```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({'foo': lambda}); // bar ``` + ```dart -var t = Template('{{# foo }}oi{{/ foo }}'); -var lambda = (LambdaContext ctx) => '${ctx.renderString().toUpperCase()}'; -t.renderString({'foo': lambda}); // OI +final template = Template('{{# foo }}hidden{{/ foo }}'); +Object lambda(Object? _) => 'shown'; +final output = template.renderString({'foo': lambda}); // shown ``` + ```dart -var t = Template('{{# foo }}{{bar}}{{/ foo }}'); -var lambda = (LambdaContext ctx) => '${ctx.renderString().toUpperCase()}'; -t.renderString({'foo': lambda, 'bar': 'pub'}); // PUB +final template = Template('{{# foo }}oi{{/ foo }}'); +Object lambda(LambdaContext ctx) => '${ctx.renderString().toUpperCase()}'; +final output = template.renderString({'foo': lambda}); // OI ``` + ```dart -var t = Template('{{# foo }}{{bar}}{{/ foo }}'); -var lambda = (LambdaContext ctx) => '${ctx.renderString().toUpperCase()}'; -t.renderString({'foo': lambda, 'bar': 'pub'}); // PUB +final template = Template('{{# foo }}{{bar}}{{/ foo }}'); +Object lambda(LambdaContext ctx) => '${ctx.renderString().toUpperCase()}'; +final output = template.renderString({'foo': lambda, 'bar': 'pub'}); // PUB ``` 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. + ```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({ + 'foo': lambda, + 'bar': 'pub', + 'cmd': 'build', +}); // pub build ``` diff --git a/third_party/packages/mustache_template/ci_config.yaml b/third_party/packages/mustache_template/ci_config.yaml deleted file mode 100644 index b352e13e..00000000 --- a/third_party/packages/mustache_template/ci_config.yaml +++ /dev/null @@ -1,2 +0,0 @@ -# TODO(stuartmorgan): Remove this; see https://github.com/flutter/flutter/issues/102679 -exempt_from_excerpts: true diff --git a/third_party/packages/mustache_template/example/lib/readme_excerpts.dart b/third_party/packages/mustache_template/example/lib/readme_excerpts.dart new file mode 100644 index 00000000..488ab3ea --- /dev/null +++ b/third_party/packages/mustache_template/example/lib/readme_excerpts.dart @@ -0,0 +1,116 @@ +// ignore_for_file: avoid_print + +import 'package:mustache_template/mustache_template.dart'; + +void basicUsage() { + // #docregion BasicUsage + final source = ''' +{{# names }} +
{{ lastname }}, {{ firstname }}
+{{/ names }} +{{^ names }} +
No names.
+{{/ names }} +{{! I am a comment. }} +'''; + + final template = Template(source, name: 'template-filename.html'); + + final output = template.renderString({ + 'names': >[ + {'firstname': 'Greg', 'lastname': 'Lowe'}, + {'firstname': 'Bob', 'lastname': 'Johnson'}, + ], + }); + // #enddocregion BasicUsage + print(output); +} + +void nestedPaths() { + // #docregion NestedPaths + final template = Template('{{ author.name }}'); + final output = template.renderString({ + 'author': {'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({'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({'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({'foo': lambda}); // shown + // #enddocregion LambdaHidingSection + print(output); +} + +void lambdaWithContext() { + // #docregion LambdaWithContext + final template = Template('{{# foo }}oi{{/ foo }}'); + Object lambda(LambdaContext ctx) => '${ctx.renderString().toUpperCase()}'; + final output = template.renderString({'foo': lambda}); // OI + // #enddocregion LambdaWithContext + print(output); +} + +void lambdaWithContextAndVariables() { + // #docregion LambdaWithContextAndVariables + final template = Template('{{# foo }}{{bar}}{{/ foo }}'); + Object lambda(LambdaContext ctx) => '${ctx.renderString().toUpperCase()}'; + final output = template.renderString({'foo': lambda, 'bar': 'pub'}); // PUB + // #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({ + 'foo': lambda, + 'bar': 'pub', + 'cmd': 'build', + }); // pub build + // #enddocregion LambdaReparsingSource + print(output); +} + +void main() { + basicUsage(); + nestedPaths(); + partials(); + lambdaReturningValue(); + lambdaHidingSection(); + lambdaWithContext(); + lambdaWithContextAndVariables(); + lambdaReparsingSource(); +} diff --git a/third_party/packages/mustache_template/example/pubspec.yaml b/third_party/packages/mustache_template/example/pubspec.yaml new file mode 100644 index 00000000..7c44f40a --- /dev/null +++ b/third_party/packages/mustache_template/example/pubspec.yaml @@ -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: ../ diff --git a/third_party/packages/mustache_template/pubspec.yaml b/third_party/packages/mustache_template/pubspec.yaml index ebc4ca9d..f73bbfd5 100644 --- a/third_party/packages/mustache_template/pubspec.yaml +++ b/third_party/packages/mustache_template/pubspec.yaml @@ -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