Merge pull request #18 from jg-rp/analyze-tags

feat: analyse tags and filters
jg-rp · Aug 8, 2023 · 622a8c1 · 622a8c1
2 parents 26d07a1 + 98b646b
commit 622a8c1
Show file tree

Hide file tree

Showing 5 changed files with 843 additions and 130 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 - Added the standard `sum` filter, which returns the sum of any numeric values in its input array.
 - Added optional `{% extends %}` and `{% block %}` tags that add template inheritance features to Liquid templates.
+- Added `filter` and `tag` properties to the result of `Template.analyze()`, containing the locations of filters and tags found during static analysis. 
 
 ## Version 1.7.0
 

diff --git a/docs/docs/guides/static-analysis.md b/docs/docs/guides/static-analysis.md
@@ -73,7 +73,7 @@ const template = Template.fromString(`\
 
 const analysis = template.analyzeSync();
 
-for (const [name, locations] of Object.entries(a.globalVariables)) {
+for (const [name, locations] of Object.entries(analysis.globalVariables)) {
   for (const { templateName, lineNumber } of locations) {
     console.log(
       `'${name}' is out of scope in '${templateName}' on line ${lineNumber}`
@@ -99,7 +99,7 @@ const template = Template.fromString(`\
 
 const analysis = template.analyzeSync();
 
-for (const [name, locations] of Object.entries(a.localVariables)) {
+for (const [name, locations] of Object.entries(analysis.localVariables)) {
   for (const { templateName, lineNumber } of locations) {
     console.log(
       `'${name}' assigned in '${templateName}' on line ${lineNumber}`
@@ -113,6 +113,71 @@ for (const [name, locations] of Object.entries(a.localVariables)) {
 'people' assigned in '<string>' on line 2
 ```
 
+## Filters
+
+**_New in version 1.8.0_**
+
+The `filters` property of [`TemplateAnalysis`](../api/modules.md#templateanalysis) is an object mapping filter names to their locations.
+
+
+```javascript
+import { Template } from "liquidscript";
+
+const template = Template.fromString(`\
+{% assign people = "Sally, John, Brian, Sue" | split: ", " %}
+{% for person in people %}
+  - {{ person | upcase | prepend: 'Hello, ' }}
+{% endfor %}`);
+
+const analysis = template.analyzeSync();
+
+for (const [filterName, locations] of Object.entries(analysis.filters)) {
+  for (const { templateName, lineNumber } of locations) {
+    console.log(
+      `'${filterName}' found in '${templateName}' on line ${lineNumber}`
+    );
+  }
+}
+```
+
+```plain title="output"
+'split' found in '<string>' on line 1
+'upcase' found in '<string>' on line 3
+'prepend' found in '<string>' on line 3
+```
+
+## Tags
+
+**_New in version 1.8.0_**
+
+The `tags` property of [`TemplateAnalysis`](../api/modules.md#templateanalysis) is an object mapping tag names to their locations. Note that, for block tags, we only report the locations of the opening tag, and `{% raw %}` tags will never be included.
+
+
+```javascript
+import { Template } from "liquidscript";
+
+const template = Template.fromString(`\
+{% assign people = "Sally, John, Brian, Sue" | split: ", " %}
+{% for person in people %}
+  - {{ person | upcase | prepend: 'Hello, ' }}
+{% endfor %}`);
+
+const analysis = template.analyzeSync();
+
+for (const [tagName, locations] of Object.entries(analysis.tags)) {
+  for (const { templateName, lineNumber } of locations) {
+    console.log(
+      `'${tagName}' found in '${templateName}' on line ${lineNumber}`
+    );
+  }
+}
+```
+
+```plain title="output"
+'assign' found in '<string>' on line 1
+'for' found in '<string>' on line 2
+```
+
 ## Analyzing Partial Templates
 
 When the `followPartials` option to [`Template.analyze()`](../api/classes/Template.md#analyze) is `true` (the default), LiquidScript will attempt to load and analyze templates from `include` and `render` tags. In the case of `include`, this is only possible when the template name is a string literal.