Add real mustachio annotation, and check in in-progress renderers. (#2430)

Add real mustachio annotation, and check in in-progress renderers.

* Add mustachio to build.yaml
* Add a class Renderer, meant to be used as an annotation
* Add one @Renderer annotation to templates.dart
* Add the generated templates.renderers.dart file. While in-progress, this
  library is valid Dart, and passes static analysis. Checking it in ensures
  that it will continue to be valid Dart, and pass static analysis.
* Remove the abstract `getFields` method; the generated code doesn't implement
  it yet; this was checked in prematurely.
* Remove the templateUri field from the mock Renderer class in the tests; this
  field won't be needed; template URIs are provided at runtime.

Author: srawlins

build.yaml

@@ -5,16 +5,28 @@ builders:
     build_extensions: {'$lib$': ['src/generator/html_resources.g.dart']}
     build_to: "source"
     auto_apply: none
+  mustachio_builder:
+    import: "tool/mustachio/builder.dart"
+    builder_factories: ["mustachioBuilder"]
+    build_extensions: {".dart": [".renderers.dart"]}
+    build_to: "source"
 
 targets:
   builder:
-    sources: ["tool/builder.dart"]
+    sources:
+      - tool/builder.dart
+      - tool/mustachio/builder.dart
 
   $default:
     sources:
-      exclude: ["tool/builder.dart"]
+      exclude:
+        - tool/builder.dart
+        - tool/mustachio/builder.dart
     builders:
       build_version:
         enabled: true
       dartdoc|resource_builder:
         enabled: true
+      dartdoc|mustachio_builder:
+        enabled: true
+        generate_for: ["lib/src/generator/templates.dart"]

lib/src/generator/templates.dart

@@ -2,12 +2,17 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+// TODO(srawlins): Add Renderer annotations for more types as the mustachio
+// implementation matures.
+@Renderer(#renderIndex, Context<PackageTemplateData>())
 library dartdoc.templates;
 
 import 'dart:io' show File, Directory;
 
 import 'package:dartdoc/dartdoc.dart';
 import 'package:dartdoc/src/generator/resource_loader.dart' as loader;
+import 'package:dartdoc/src/generator/template_data.dart';
+import 'package:dartdoc/src/mustachio/annotations.dart';
 import 'package:mustache/mustache.dart';
 import 'package:path/path.dart' as path;
 

lib/src/generator/templates.renderers.dart

@@ -0,0 +1,154 @@
+// GENERATED CODE. DO NOT EDIT.
+//
+// To change the contents of this library, make changes to the builder source
+// files in the tool/mustachio/ directory.
+
+// ignore_for_file: camel_case_types, unused_element
+import 'package:dartdoc/src/generator/template_data.dart';
+import 'package:dartdoc/dartdoc.dart';
+import 'package:dartdoc/src/mustachio/renderer_base.dart';
+import 'package:dartdoc/src/mustachio/parser.dart';
+
+String renderIndex(PackageTemplateData context, List<MustachioNode> ast) {
+  var renderer = _Renderer_PackageTemplateData(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_PackageTemplateData extends RendererBase<PackageTemplateData> {
+  _Renderer_PackageTemplateData(PackageTemplateData context) : super(context);
+}
+
+String _render_Package(Package context, List<MustachioNode> ast) {
+  var renderer = _Renderer_Package(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_Package extends RendererBase<Package> {
+  _Renderer_Package(Package context) : super(context);
+}
+
+String _render_LibraryContainer(
+    LibraryContainer context, List<MustachioNode> ast) {
+  var renderer = _Renderer_LibraryContainer(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_LibraryContainer extends RendererBase<LibraryContainer> {
+  _Renderer_LibraryContainer(LibraryContainer context) : super(context);
+}
+
+String _render_Object(Object context, List<MustachioNode> ast) {
+  var renderer = _Renderer_Object(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_Object extends RendererBase<Object> {
+  _Renderer_Object(Object context) : super(context);
+}
+
+String _render_bool(bool context, List<MustachioNode> ast) {
+  var renderer = _Renderer_bool(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_bool extends RendererBase<bool> {
+  _Renderer_bool(bool context) : super(context);
+}
+
+String _render_List<E>(List<E> context, List<MustachioNode> ast) {
+  var renderer = _Renderer_List(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_List<E> extends RendererBase<List<E>> {
+  _Renderer_List(List<E> context) : super(context);
+}
+
+String _render_String(String context, List<MustachioNode> ast) {
+  var renderer = _Renderer_String(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_String extends RendererBase<String> {
+  _Renderer_String(String context) : super(context);
+}
+
+String _render_TemplateData<T extends Documentable>(
+    TemplateData<T> context, List<MustachioNode> ast) {
+  var renderer = _Renderer_TemplateData(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_TemplateData<T extends Documentable>
+    extends RendererBase<TemplateData<T>> {
+  _Renderer_TemplateData(TemplateData<T> context) : super(context);
+}
+
+String _render_TemplateOptions(
+    TemplateOptions context, List<MustachioNode> ast) {
+  var renderer = _Renderer_TemplateOptions(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_TemplateOptions extends RendererBase<TemplateOptions> {
+  _Renderer_TemplateOptions(TemplateOptions context) : super(context);
+}
+
+String _render_Documentable(Documentable context, List<MustachioNode> ast) {
+  var renderer = _Renderer_Documentable(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_Documentable extends RendererBase<Documentable> {
+  _Renderer_Documentable(Documentable context) : super(context);
+}
+
+String _render_Nameable(Nameable context, List<MustachioNode> ast) {
+  var renderer = _Renderer_Nameable(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_Nameable extends RendererBase<Nameable> {
+  _Renderer_Nameable(Nameable context) : super(context);
+}
+
+String _render_int(int context, List<MustachioNode> ast) {
+  var renderer = _Renderer_int(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_int extends RendererBase<int> {
+  _Renderer_int(int context) : super(context);
+}
+
+String _render_num(num context, List<MustachioNode> ast) {
+  var renderer = _Renderer_num(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_num extends RendererBase<num> {
+  _Renderer_num(num context) : super(context);
+}
+
+String _render_Type(Type context, List<MustachioNode> ast) {
+  var renderer = _Renderer_Type(context);
+  renderer.renderBlock(ast);
+  return renderer.buffer.toString();
+}
+
+class _Renderer_Type extends RendererBase<Type> {
+  _Renderer_Type(Type context) : super(context);
+}

lib/src/mustachio/annotations.dart

@@ -0,0 +1,19 @@
+/// Specifies information for generating a Mustache renderer for a [context]
+/// object, using a Mustache template at [templateUri]
+class Renderer {
+  /// The name of the render function to generate.
+  final Symbol name;
+
+  /// The type of the context type, specified as the [Context] type argument.
+  final Context context;
+
+  const Renderer(this.name, this.context);
+}
+
+/// A container for a type, [T], which is the type of a context object,
+/// referenced in a `@Renderer` annotation.
+///
+/// An instance of this class holds zero information, except for [T], a type.
+class Context<T> {
+  const Context();
+}

lib/src/mustachio/renderer_base.dart

@@ -22,8 +22,7 @@ abstract class RendererBase<T> {
       if (node is Text) {
         write(node.content);
       } else if (node is Variable) {
-        var content = getFields(node.key);
-        write(content);
+        // TODO(srawlins): Implement.
       } else if (node is Section) {
         section(node);
       } else if (node is Partial) {
@@ -39,12 +38,4 @@ abstract class RendererBase<T> {
   void partial(Partial node) {
     // TODO(srawlins): Implement.
   }
-
-  /// Resolves [key] into one or more field accesses, returning the result as a
-  /// String.
-  ///
-  /// [key] may have multiple dot-separate names, and [key] may not be a valid
-  /// property of _this_ context type, in which the [parent] renderer is
-  /// referenced.
-  String getFields(List<String> names);
 }

test/mustachio/builder_test.dart

@@ -13,9 +13,7 @@ class Renderer {
 
   final Context context;
 
-  final String templateUri;
-
-  const Renderer(this.name, this.context, this.templateUri);
+  const Renderer(this.name, this.context);
 }
 
 class Context<T> {
@@ -25,7 +23,7 @@ class Context<T> {
 };
 
 const _libraryFrontMatter = '''
-@Renderer(#renderFoo, Context<Foo>(), 'foo.html.mustache')
+@Renderer(#renderFoo, Context<Foo>())
 library foo;
 import 'package:mustachio/annotations.dart';
 ''';
@@ -118,8 +116,8 @@ class _Renderer_Object extends RendererBase<Object> {
 class Foo {}
 class Bar {}
 ''', libraryFrontMatter: '''
-@Renderer(#renderFoo, Context<Foo>(), 'foo.html.mustache')
-@Renderer(#renderBar, Context<Bar>(), 'bar.html.mustache')
+@Renderer(#renderFoo, Context<Foo>())
+@Renderer(#renderBar, Context<Bar>())
 library foo;
 import 'package:mustachio/annotations.dart';
 ''');

tool/grind.dart

@@ -940,6 +940,7 @@ Future<void> build() async {
 final _generated_files_list = <String>[
   '../dartdoc_options.yaml',
   'src/generator/html_resources.g.dart',
+  'src/generator/templates.renderers.dart',
   'src/version.dart',
 ].map((s) => path.joinAll(path.posix.split(s)));
 

tool/mustachio/builder.dart

@@ -80,10 +80,6 @@ class _RendererGatherer {
     var contextFieldType = contextField.type;
     assert(contextFieldType.typeArguments.length == 1);
     var contextType = contextFieldType.typeArguments.single;
-    var templateUriField = constantValue.getField('templateUri');
-    if (templateUriField.isNull) {
-      throw StateError('@Renderer templateUri must not be null');
-    }
 
     return RendererSpec(nameField.toSymbolValue(), contextType);
   }

tool/mustachio/codegen_runtime_renderer.dart

@@ -43,8 +43,20 @@ class RuntimeRenderersBuilder {
   RuntimeRenderersBuilder();
 
   String _buildTemplateRenderers(Set<RendererSpec> specs) {
+    // TODO(srawlins): There are some private renderer functions that are
+    // unused. Figure out if we can detect these statically, and then not
+    // generate them.
+    // TODO(srawlins): To really get the correct list of imports, we need to use
+    // the code_builder package.
     _buffer.writeln('''
-// ignore_for_file: camel_case_types
+// GENERATED CODE. DO NOT EDIT.
+//
+// To change the contents of this library, make changes to the builder source
+// files in the tool/mustachio/ directory.
+
+// ignore_for_file: camel_case_types, unused_element
+import 'package:dartdoc/src/generator/template_data.dart';
+import 'package:dartdoc/dartdoc.dart';
 import 'package:dartdoc/src/mustachio/renderer_base.dart';
 import 'package:dartdoc/src/mustachio/parser.dart';
 ''');