Introduce the Mustache AOT compiler #2651
Conversation
|
This is a big PR. I can break it up into a few smaller if desired, like moving |
lib/src/mustachio/annotations.dart
Outdated
|
|
||
| /// Specifies information for generating both a runtime-interpreted Mustache | ||
| /// renderer and a pre-compiled Mustache renderer for a [context] object, using | ||
| /// a Mustache template at [templateUri] |
There was a problem hiding this comment.
period at end of sentence?
lib/src/mustachio/annotations.dart
Outdated
| /// The unparsed, string form of the URI of the _standard_ Markdown template. | ||
| /// | ||
| /// This represents the Mustache template that dartdoc uses out-of-the-box to | ||
| /// render the [context] object while generating documentation in HTML. |
| import 'package:analyzer/dart/element/element.dart'; | ||
|
|
||
| /// The build package Asset for a copy of the Renderer annotation for tests. | ||
| const annotationsAsset = { |
There was a problem hiding this comment.
a bit more explanation as to why this is needed (and possibly, some cross linking saying to update this when the Renderer annotation gets modified) seems prudent. I had forgotten about this bit.
| writeln('buffer.writeln();'); | ||
| } else { | ||
| content = content.replaceAll("'", "\\'").replaceAll(r'$', r'\\$'); | ||
| if (RegExp('^[ \\n]+\$').hasMatch(content)) { |
There was a problem hiding this comment.
Suggest using a private static for the RegExp instead of constructing it each time, depending on how Dart handles it these constructions could be expensive.
| // Blank lines happen a lot; just indicate them as such. | ||
| writeln('buffer.writeln();'); | ||
| } else { | ||
| content = content.replaceAll("'", "\\'").replaceAll(r'$', r'\\$'); |
There was a problem hiding this comment.
Escaping single quotes does not work in multi-line dart strings. It won't break your program because they're no longer three literal single quotes in a row, but the output will be mangled. To handle this correctly you'll need to split content on a triple-single-quote separator and write the separators out in between the sections. I might also suggest that you use raw strings for your multi-liners, thus eliminating the need for substitutions.
There was a problem hiding this comment.
Well, it will eliminate some of the need for substitutions, depending on how you want to handle the whitespace writes you might still need them there.
There was a problem hiding this comment.
Can you elaborate with an example? I'm not sure I follow what input would not be properly escaped...
There was a problem hiding this comment.
Went back to my test code and for some reason I thought you were using raw multiline strings but you were not, so my original comment was wrong.
However, not using raw multiline strings means you will need to escape any backslashes in the output or otherwise a literal \f in the template, for example, will not translate across. So one or the other will need to be handled I think?
| _VariableLookup(this.type, this.name); | ||
| } | ||
|
|
||
| extension<T> on List<T> { |
There was a problem hiding this comment.
Had no idea you could do extension<T> but I guess it makes sense!
| import 'package:dartdoc/src/generator/template_data.dart'; | ||
| import 'foo.dart'; | ||
|
|
||
| String renderFoo(Foo context0) { |
There was a problem hiding this comment.
Random one-off: could/would we pass in a StringSink here instead of creating a buffer.
Then you have the option of doing streaming writes later? Maybe?
|
Oh shwew and CI is good. Thanks! |
When the context types and the templates are known ahead-of-time, we can do much better than Mustachio's runtime renderers, and instead compile exceedingly straightforward render code.
This PR includes the code generator for AOT renderers, but does not wire it up to dartdoc yet.
This PR includes a README which describes the design of the generated files, but does not yet describe the design of the generator. 😄
*.runtime_renderers.dartinstead of.renderers.dart, to distinguish. These renderers are still in use for all cases of rendering into templates.*.aot_renderers_for_html.dartand*.aot_renderers_for_md.dart.@Rendererannotations need a new argument: the (approximate) base file name of the template file. Again, we don't use the AOT renderers yet, but the annotations still need to be legal, and still generate the renderers.RendererSpecfromtool/tolib/src/mustachio/annotations.dart, so it can be shared between builders.