Skip to content

Commit dc93a75

Browse files
srawlinssrawlins
authored
Replace mustache usage with mustachio (#2564)
Replace mustache package with mustachio.
1 parent e2d010e commit dc93a75

File tree

15 files changed

+13289
-965
lines changed

15 files changed

+13289
-965
lines changed

‎lib/src/generator/dartdoc_generator_backend.dart

Lines changed: 45 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,12 @@ import 'package:dartdoc/src/generator/generator_frontend.dart';
88
import 'package:dartdoc/src/generator/generator_utils.dart' as generator_util;
99
import 'package:dartdoc/src/generator/template_data.dart';
1010
import 'package:dartdoc/src/generator/templates.dart';
11+
import 'package:dartdoc/src/generator/templates.renderers.dart';
1112
import 'package:dartdoc/src/model/model.dart';
1213
import 'package:dartdoc/src/model/package.dart';
1314
import 'package:dartdoc/src/model/package_graph.dart';
15+
import 'package:dartdoc/src/mustachio/renderer_base.dart';
1416
import 'package:dartdoc/src/warnings.dart';
15-
import 'package:mustache/mustache.dart';
1617
import 'package:path/path.dart' as path show Context;
1718

1819
/// Configuration options for the Dartdoc's default backend.
@@ -61,38 +62,41 @@ class DartdocGeneratorBackendOptions implements TemplateOptions {
6162
customInnerFooterText = '';
6263
}
6364

64-
class SidebarGenerator<T extends Documentable> {
65+
class SidebarGenerator<T extends TemplateData> {
6566
final Template template;
66-
final Map<T, String> _renderCache = {};
67+
final RenderFunction<T> renderFunction;
68+
final Map<Documentable, String> _renderCache = {};
6769

68-
SidebarGenerator(this.template);
70+
SidebarGenerator(this.template, this.renderFunction);
6971

7072
// Retrieve the render for a specific key, or generate it using the given
7173
// template data if you need.
72-
String getRenderFor(T key, TemplateData templateData) {
73-
return _renderCache[key] ??= template.renderString(templateData);
74+
String getRenderFor(Documentable key, T templateData) {
75+
return _renderCache[key] ??= renderFunction(templateData, template);
7476
}
7577
}
7678

7779
/// Base GeneratorBackend for Dartdoc's supported formats.
7880
abstract class DartdocGeneratorBackend implements GeneratorBackend {
7981
final DartdocGeneratorBackendOptions options;
8082
final Templates templates;
81-
final SidebarGenerator<Library> sidebarForLibrary;
82-
final SidebarGenerator<Container> sidebarForContainer;
83+
final SidebarGenerator<TemplateDataWithLibrary<Documentable>>
84+
sidebarForLibrary;
85+
final SidebarGenerator<TemplateDataWithContainer<Documentable>>
86+
sidebarForContainer;
8387
final path.Context _pathContext;
8488

8589
DartdocGeneratorBackend(
8690
DartdocGeneratorBackendOptions options, this.templates, this._pathContext)
8791
: options = options ?? DartdocGeneratorBackendOptions._defaults(),
88-
sidebarForContainer =
89-
SidebarGenerator(templates.sidebarContainerTemplate),
90-
sidebarForLibrary = SidebarGenerator(templates.sidebarLibraryTemplate);
92+
sidebarForLibrary = SidebarGenerator(
93+
templates.sidebarLibraryTemplate, renderSidebarForLibrary),
94+
sidebarForContainer = SidebarGenerator(
95+
templates.sidebarContainerTemplate, renderSidebarForContainer);
9196

9297
/// Helper method to bind template data and emit the content to the writer.
93-
void render(FileWriter writer, String filename, Template template,
94-
TemplateData data) {
95-
var content = template.renderString(data);
98+
void write(
99+
FileWriter writer, String filename, TemplateData data, String content) {
96100
if (!options.useBaseHref) {
97101
content = content.replaceAll(htmlBasePlaceholder, data.htmlBase);
98102
}
@@ -128,30 +132,34 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
128132
@override
129133
void generatePackage(FileWriter writer, PackageGraph graph, Package package) {
130134
TemplateData data = PackageTemplateData(options, graph, package);
131-
render(writer, package.filePath, templates.indexTemplate, data);
135+
var content = renderIndex(data, templates.indexTemplate);
136+
write(writer, package.filePath, data, content);
132137
}
133138

134139
@override
135140
void generateCategory(
136141
FileWriter writer, PackageGraph packageGraph, Category category) {
137142
TemplateData data = CategoryTemplateData(options, packageGraph, category);
138-
render(writer, category.filePath, templates.categoryTemplate, data);
143+
var content = renderCategory(data, templates.categoryTemplate);
144+
write(writer, category.filePath, data, content);
139145
}
140146

141147
@override
142148
void generateLibrary(
143149
FileWriter writer, PackageGraph packageGraph, Library lib) {
144150
TemplateData data = LibraryTemplateData(
145151
options, packageGraph, lib, sidebarForLibrary.getRenderFor);
146-
render(writer, lib.filePath, templates.libraryTemplate, data);
152+
var content = renderLibrary(data, templates.libraryTemplate);
153+
write(writer, lib.filePath, data, content);
147154
}
148155

149156
@override
150157
void generateClass(
151158
FileWriter writer, PackageGraph packageGraph, Library lib, Class clazz) {
152159
TemplateData data = ClassTemplateData(options, packageGraph, lib, clazz,
153160
sidebarForLibrary.getRenderFor, sidebarForContainer.getRenderFor);
154-
render(writer, clazz.filePath, templates.classTemplate, data);
161+
var content = renderClass(data, templates.classTemplate);
162+
write(writer, clazz.filePath, data, content);
155163
}
156164

157165
@override
@@ -164,51 +172,53 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
164172
extension,
165173
sidebarForLibrary.getRenderFor,
166174
sidebarForContainer.getRenderFor);
167-
render(writer, extension.filePath, templates.extensionTemplate, data);
175+
var content = renderExtension(data, templates.extensionTemplate);
176+
write(writer, extension.filePath, data, content);
168177
}
169178

170179
@override
171180
void generateMixin(
172181
FileWriter writer, PackageGraph packageGraph, Library lib, Mixin mixin) {
173182
TemplateData data = MixinTemplateData(options, packageGraph, lib, mixin,
174183
sidebarForLibrary.getRenderFor, sidebarForContainer.getRenderFor);
175-
render(writer, mixin.filePath, templates.mixinTemplate, data);
184+
var content = renderMixin(data, templates.mixinTemplate);
185+
write(writer, mixin.filePath, data, content);
176186
}
177187

178188
@override
179189
void generateConstructor(FileWriter writer, PackageGraph packageGraph,
180190
Library lib, Class clazz, Constructor constructor) {
181191
TemplateData data = ConstructorTemplateData(options, packageGraph, lib,
182192
clazz, constructor, sidebarForContainer.getRenderFor);
183-
184-
render(writer, constructor.filePath, templates.constructorTemplate, data);
193+
var content = renderConstructor(data, templates.constructorTemplate);
194+
write(writer, constructor.filePath, data, content);
185195
}
186196

187197
@override
188198
void generateEnum(
189199
FileWriter writer, PackageGraph packageGraph, Library lib, Enum eNum) {
190200
TemplateData data = EnumTemplateData(options, packageGraph, lib, eNum,
191201
sidebarForLibrary.getRenderFor, sidebarForContainer.getRenderFor);
192-
193-
render(writer, eNum.filePath, templates.enumTemplate, data);
202+
var content = renderEnum(data, templates.enumTemplate);
203+
write(writer, eNum.filePath, data, content);
194204
}
195205

196206
@override
197207
void generateFunction(FileWriter writer, PackageGraph packageGraph,
198208
Library lib, ModelFunction function) {
199209
TemplateData data = FunctionTemplateData(
200210
options, packageGraph, lib, function, sidebarForLibrary.getRenderFor);
201-
202-
render(writer, function.filePath, templates.functionTemplate, data);
211+
var content = renderFunction(data, templates.functionTemplate);
212+
write(writer, function.filePath, data, content);
203213
}
204214

205215
@override
206216
void generateMethod(FileWriter writer, PackageGraph packageGraph, Library lib,
207217
Container clazz, Method method) {
208218
TemplateData data = MethodTemplateData(options, packageGraph, lib, clazz,
209219
method, sidebarForContainer.getRenderFor);
210-
211-
render(writer, method.filePath, templates.methodTemplate, data);
220+
var content = renderMethod(data, templates.methodTemplate);
221+
write(writer, method.filePath, data, content);
212222
}
213223

214224
@override
@@ -221,17 +231,18 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
221231
Library lib, Container clazz, Field property) {
222232
TemplateData data = PropertyTemplateData(options, packageGraph, lib, clazz,
223233
property, sidebarForContainer.getRenderFor);
224-
225-
render(writer, property.filePath, templates.propertyTemplate, data);
234+
var content = renderProperty(data, templates.propertyTemplate);
235+
write(writer, property.filePath, data, content);
226236
}
227237

228238
@override
229239
void generateTopLevelProperty(FileWriter writer, PackageGraph packageGraph,
230240
Library lib, TopLevelVariable property) {
231241
TemplateData data = TopLevelPropertyTemplateData(
232242
options, packageGraph, lib, property, sidebarForLibrary.getRenderFor);
233-
234-
render(writer, property.filePath, templates.topLevelPropertyTemplate, data);
243+
var content =
244+
renderTopLevelProperty(data, templates.topLevelPropertyTemplate);
245+
write(writer, property.filePath, data, content);
235246
}
236247

237248
@override
@@ -244,8 +255,8 @@ abstract class DartdocGeneratorBackend implements GeneratorBackend {
244255
Library lib, Typedef typeDef) {
245256
TemplateData data = TypedefTemplateData(
246257
options, packageGraph, lib, typeDef, sidebarForLibrary.getRenderFor);
247-
248-
render(writer, typeDef.filePath, templates.typeDefTemplate, data);
258+
var content = renderTypedef(data, templates.typeDefTemplate);
259+
write(writer, typeDef.filePath, data, content);
249260
}
250261

251262
@override

‎lib/src/generator/html_generator.dart

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import 'package:dartdoc/src/generator/html_resources.g.dart' as resources;
1212
import 'package:dartdoc/src/generator/resource_loader.dart';
1313
import 'package:dartdoc/src/generator/template_data.dart';
1414
import 'package:dartdoc/src/generator/templates.dart';
15+
import 'package:dartdoc/src/generator/templates.renderers.dart';
1516
import 'package:dartdoc/src/model/package.dart';
1617
import 'package:dartdoc/src/model/package_graph.dart';
1718
import 'package:path/path.dart' as path show Context;
@@ -36,7 +37,8 @@ class HtmlGeneratorBackend extends DartdocGeneratorBackend {
3637
super.generatePackage(writer, graph, package);
3738
// We have to construct the data again. This only happens once per package.
3839
TemplateData data = PackageTemplateData(options, graph, package);
39-
render(writer, '__404error.html', templates.errorTemplate, data);
40+
var content = renderError(data, templates.errorTemplate);
41+
write(writer, '__404error.html', data, content);
4042
}
4143

4244
@override

‎lib/src/generator/markdown_generator.dart

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import 'package:dartdoc/src/generator/generator.dart';
88
import 'package:dartdoc/src/generator/generator_frontend.dart';
99
import 'package:dartdoc/src/generator/template_data.dart';
1010
import 'package:dartdoc/src/generator/templates.dart';
11+
import 'package:dartdoc/src/generator/templates.renderers.dart';
1112
import 'package:dartdoc/src/model/package.dart';
1213
import 'package:dartdoc/src/model/package_graph.dart';
1314
import 'package:path/path.dart' as path show Context;
@@ -32,6 +33,7 @@ class MarkdownGeneratorBackend extends DartdocGeneratorBackend {
3233
super.generatePackage(writer, graph, package);
3334
// We have to construct the data again. This only happens once per package.
3435
TemplateData data = PackageTemplateData(options, graph, package);
35-
render(writer, '__404error.md', templates.errorTemplate, data);
36+
var content = renderError(data, templates.errorTemplate);
37+
write(writer, '__404error.md', data, content);
3638
}
3739
}

‎lib/src/generator/resource_loader.dart

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,12 @@ extension ResourceLoader on ResourceProvider {
2424
throw ArgumentError('path must begin with package:');
2525
}
2626

27+
return (await getResourceFile(path)).readAsBytesSync();
28+
}
29+
30+
Future<File> getResourceFile(String path) async {
2731
var uri = await resolveResourceUri(Uri.parse(path));
28-
return getFile(uri.toFilePath()).readAsBytesSync();
32+
return getFile(uri.toFilePath());
2933
}
3034

3135
/// Helper function for resolving to a non-relative, non-package URI.

‎lib/src/generator/templates.dart

Lines changed: 59 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,60 @@
22
// for details. All rights reserved. Use of this source code is governed by a
33
// BSD-style license that can be found in the LICENSE file.
44

5-
// TODO(srawlins): Add Renderer annotations for more types as the mustachio
6-
// implementation matures.
7-
@Renderer(#renderIndex, Context<PackageTemplateData>(), visibleTypes: {Package})
5+
@Renderer(#renderCategory, Context<CategoryTemplateData>(),
6+
visibleTypes: _visibleTypes)
7+
@Renderer(#renderClass, Context<ClassTemplateData>())
8+
@Renderer(#renderConstructor, Context<ConstructorTemplateData>())
9+
@Renderer(#renderEnum, Context<EnumTemplateData>())
10+
@Renderer(#renderError, Context<PackageTemplateData>())
11+
@Renderer(#renderExtension, Context<ExtensionTemplateData>())
12+
@Renderer(#renderFunction, Context<FunctionTemplateData>())
13+
@Renderer(#renderIndex, Context<PackageTemplateData>())
14+
@Renderer(#renderLibrary, Context<LibraryTemplateData>())
15+
@Renderer(#renderMethod, Context<MethodTemplateData>())
16+
@Renderer(#renderMixin, Context<MixinTemplateData>())
17+
@Renderer(#renderProperty, Context<PropertyTemplateData>())
18+
@Renderer(#renderSidebarForContainer,
19+
Context<TemplateDataWithContainer<Documentable>>())
20+
@Renderer(
21+
#renderSidebarForLibrary, Context<TemplateDataWithLibrary<Documentable>>())
22+
@Renderer(#renderTopLevelProperty, Context<TopLevelPropertyTemplateData>())
23+
@Renderer(#renderTypedef, Context<TypedefTemplateData>())
824
library dartdoc.templates;
925

1026
import 'package:analyzer/file_system/file_system.dart';
1127
import 'package:dartdoc/dartdoc.dart';
1228
import 'package:dartdoc/options.dart';
1329
import 'package:dartdoc/src/generator/resource_loader.dart';
1430
import 'package:dartdoc/src/generator/template_data.dart';
31+
import 'package:dartdoc/src/model/feature_set.dart';
32+
import 'package:dartdoc/src/model/language_feature.dart';
1533
import 'package:dartdoc/src/mustachio/annotations.dart';
34+
import 'package:dartdoc/src/mustachio/renderer_base.dart';
1635
import 'package:meta/meta.dart';
17-
import 'package:mustache/mustache.dart';
1836
import 'package:path/path.dart' as path show Context;
1937

38+
const _visibleTypes = {
39+
CallableElementTypeMixin,
40+
Category,
41+
Class,
42+
Constructor,
43+
DefinedElementType,
44+
Documentable,
45+
Enum,
46+
Extension,
47+
FeatureSet,
48+
LanguageFeature,
49+
Library,
50+
Method,
51+
ModelElement,
52+
Package,
53+
// For getters like `isNotEmpty`; perhaps a smell, but currently in use.
54+
String,
55+
TopLevelVariable,
56+
TypeParameter,
57+
};
58+
2059
// resource_loader and the Resource API doesn't support viewing resources like
2160
// a directory listing, so we have to explicitly list the partials.
2261
const _partials_html = <String>[
@@ -81,7 +120,7 @@ abstract class _TemplatesLoader {
81120

82121
Future<Map<String, String>> loadPartials();
83122

84-
Future<String> loadTemplate(String name);
123+
Future<Template> loadTemplate(String name);
85124
}
86125

87126
/// Loads default templates included in the Dartdoc program.
@@ -121,9 +160,14 @@ class _DefaultTemplatesLoader extends _TemplatesLoader {
121160
}
122161

123162
@override
124-
Future<String> loadTemplate(String name) =>
125-
resourceProvider.loadResourceAsString(
126-
'package:dartdoc/templates/$_format/$name.$_format');
163+
Future<Template> loadTemplate(String name) async {
164+
var templateFile = await resourceProvider
165+
.getResourceFile('package:dartdoc/templates/$_format/$name.$_format');
166+
return Template.parse(templateFile,
167+
partialResolver: (String partialName) =>
168+
resourceProvider.getResourceFile(
169+
'package:dartdoc/templates/$_format/_$partialName.$_format'));
170+
}
127171
}
128172

129173
/// Loads templates from a specified Directory.
@@ -155,12 +199,14 @@ class _DirectoryTemplatesLoader extends _TemplatesLoader {
155199
}
156200

157201
@override
158-
Future<String> loadTemplate(String name) async {
159-
var file = _directory.getChildAssumingFile('$name.$_format');
160-
if (!file.exists) {
202+
Future<Template> loadTemplate(String name) async {
203+
var templateFile = _directory.getChildAssumingFile('$name.$_format');
204+
if (!templateFile.exists) {
161205
throw DartdocFailure('Missing required template file: $name.$_format');
162206
}
163-
return file.readAsStringSync();
207+
return Template.parse(templateFile,
208+
partialResolver: (String partialName) async =>
209+
_directory.getChildAssumingFile('_$partialName.$_format'));
164210
}
165211
}
166212

@@ -208,19 +254,8 @@ class Templates {
208254
}
209255

210256
static Future<Templates> _create(_TemplatesLoader templatesLoader) async {
211-
var partials = await templatesLoader.loadPartials();
212-
213-
Template _partial(String name) {
214-
var partial = partials[name];
215-
if (partial == null || partial.isEmpty) {
216-
throw StateError('Did not find partial "$name"');
217-
}
218-
return Template(partial);
219-
}
220-
221257
Future<Template> _loadTemplate(String templatePath) async {
222-
var templateContents = await templatesLoader.loadTemplate(templatePath);
223-
return Template(templateContents, partialResolver: _partial);
258+
return templatesLoader.loadTemplate(templatePath);
224259
}
225260

226261
var indexTemplate = await _loadTemplate('index');

0 commit comments

Comments
 (0)