Merge branch 'master' into nested-partials

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010-2022 Mustache Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Rakefile

@@ -2,10 +2,15 @@ require 'json'
 require 'yaml'
 
 # Our custom YAML tags must retain their magic.
-%w[ code ].each do |tag|
-  YAML::add_builtin_type(tag) { |_,val| val.merge(:__tag__ => tag) }
+class TaggedMap < Hash
+  yaml_tag '!code'
+  def init_with(psych_coder)
+    self.replace({:__tag__ => 'code'}.merge(psych_coder.map))
+  end
 end
 
+YAML::add_tag('code', TaggedMap)
+
 desc 'Build all alternate versions of the specs.'
 multitask :build => [ 'build:json' ]
 
@@ -19,8 +24,12 @@ namespace :build do
       json_file = filename.gsub('.yml', '.json')
 
       File.open(json_file, 'w') do |file|
-        doc = YAML.load_file(filename)
-        file << doc.merge(:__ATTN__ => note).to_json()
+        warning = {:__ATTN__ => note}
+        doc = YAML.load_file(
+            filename,
+            permitted_classes: [TaggedMap]
+        )
+        file << JSON.pretty_generate(warning.merge(doc)) << "\n"
       end
     end
   end

TESTING.md

@@ -6,41 +6,40 @@ In general, the process for each `.yml` file is as follows:
 
 1. Use a YAML parser to load the file.
 
-2. For each test in the 'tests' array:
+2. For each test in the `tests` array:
 
-  1. Ensure that each element of the 'partials' hash (if it exists) is
-     stored in a place where the interpreter will look for it.
+    1. Ensure that each element of the `partials` hash (if it exists) is
+       stored in a place where the interpreter will look for it.
 
-  2. If your implementation will not support lambdas, feel free to skip over
-     the optional '~lambdas.yml' file.
+    2. If your implementation will not support lambdas, feel free to skip
+       over the optional `~lambdas.yml` file.
 
-  2.1. If your implementation will support lambdas, ensure that each member of
-       'data' tagged with '!code' is properly processed into a language-
-       specific lambda reference.
+       Otherwise, ensure that each member of `data` tagged with `!code` is
+       properly processed into a language-specific lambda reference.
 
-      *   e.g. Given this YAML data hash:
+       * e.g. Given this YAML data hash:
 
-          `{ x: !code { ruby: 'proc { "x" }', perl: 'sub { "x" }' } }`
+         `{ x: !code { ruby: 'proc { "x" }', perl: 'sub { "x" }' } }`
 
-          a Ruby-based Mustache implementation would process it such that it
-          was equivalent to this Ruby hash:
+         a Ruby-based Mustache implementation would process it such that it
+         was equivalent to this Ruby hash:
 
-          `{ 'x' => proc { "x" } }`
+         `{ 'x' => proc { "x" } }`
 
-      *   If your implementation language does not currently have lambda
-          examples in the spec, feel free to implement them and send a pull
-          request.
+       * If your implementation language does not currently have lambda
+         examples in the spec, feel free to implement them and send a pull
+         request.
 
-      *   The JSON version of the spec represents these tagged values as a hash
-          with a '`__tag__`' key of 'code'.
+       * The JSON version of the spec represents these tagged values as a
+         hash with a `__tag__` key of `code`.
 
-  3. Render the template (stored in the 'template' key) with the given 'data'
-     hash.
+    3. Render the template (stored in the `template` key) with the given
+       `data` hash.
 
-  4. Compare the results of your rendering against the 'expected' value; any
-     differences should be reported, along with any useful debugging
-     information.
+    4. Compare the results of your rendering against the `expected` value;
+       any differences should be reported, along with any useful debugging
+       information.
 
-     *  Of note, the 'desc' key contains a rough one-line description of the
-        behavior being tested -- this is most useful in conjunction with the
-        file name and test 'name'.
+       * Of note, the `desc` key contains a rough one-line description of
+         the behavior being tested – this is most useful in conjunction with
+         the file name and test `name`.

specs/comments.json

@@ -1 +1,106 @@
-{"__ATTN__":"Do not edit this file; changes belong in the appropriate YAML file.","overview":"Comment tags represent content that should never appear in the resulting\noutput.\n\nThe tag's content may contain any substring (including newlines) EXCEPT the\nclosing delimiter.\n\nComment tags SHOULD be treated as standalone when appropriate.\n","tests":[{"name":"Inline","data":{},"expected":"1234567890","template":"12345{{! Comment Block! }}67890","desc":"Comment blocks should be removed from the template."},{"name":"Multiline","data":{},"expected":"1234567890\n","template":"12345{{!\n  This is a\n  multi-line comment...\n}}67890\n","desc":"Multiline comments should be permitted."},{"name":"Standalone","data":{},"expected":"Begin.\nEnd.\n","template":"Begin.\n{{! Comment Block! }}\nEnd.\n","desc":"All standalone comment lines should be removed."},{"name":"Indented Standalone","data":{},"expected":"Begin.\nEnd.\n","template":"Begin.\n  {{! Indented Comment Block! }}\nEnd.\n","desc":"All standalone comment lines should be removed."},{"name":"Standalone Line Endings","data":{},"expected":"|\r\n|","template":"|\r\n{{! Standalone Comment }}\r\n|","desc":"\"\\r\\n\" should be considered a newline for standalone tags."},{"name":"Standalone Without Previous Line","data":{},"expected":"!","template":"  {{! I'm Still Standalone }}\n!","desc":"Standalone tags should not require a newline to precede them."},{"name":"Standalone Without Newline","data":{},"expected":"!\n","template":"!\n  {{! I'm Still Standalone }}","desc":"Standalone tags should not require a newline to follow them."},{"name":"Multiline Standalone","data":{},"expected":"Begin.\nEnd.\n","template":"Begin.\n{{!\nSomething's going on here...\n}}\nEnd.\n","desc":"All standalone comment lines should be removed."},{"name":"Indented Multiline Standalone","data":{},"expected":"Begin.\nEnd.\n","template":"Begin.\n  {{!\n    Something's going on here...\n  }}\nEnd.\n","desc":"All standalone comment lines should be removed."},{"name":"Indented Inline","data":{},"expected":"  12 \n","template":"  12 {{! 34 }}\n","desc":"Inline comments should not strip whitespace"},{"name":"Surrounding Whitespace","data":{},"expected":"12345  67890","template":"12345 {{! Comment Block! }} 67890","desc":"Comment removal should preserve surrounding whitespace."}]}
+{
+  "__ATTN__": "Do not edit this file; changes belong in the appropriate YAML file.",
+  "overview": "Comment tags represent content that should never appear in the resulting\noutput.\n\nThe tag's content may contain any substring (including newlines) EXCEPT the\nclosing delimiter.\n\nComment tags SHOULD be treated as standalone when appropriate.\n",
+  "tests": [
+    {
+      "name": "Inline",
+      "desc": "Comment blocks should be removed from the template.",
+      "data": {
+      },
+      "template": "12345{{! Comment Block! }}67890",
+      "expected": "1234567890"
+    },
+    {
+      "name": "Multiline",
+      "desc": "Multiline comments should be permitted.",
+      "data": {
+      },
+      "template": "12345{{!\n  This is a\n  multi-line comment...\n}}67890\n",
+      "expected": "1234567890\n"
+    },
+    {
+      "name": "Standalone",
+      "desc": "All standalone comment lines should be removed.",
+      "data": {
+      },
+      "template": "Begin.\n{{! Comment Block! }}\nEnd.\n",
+      "expected": "Begin.\nEnd.\n"
+    },
+    {
+      "name": "Indented Standalone",
+      "desc": "All standalone comment lines should be removed.",
+      "data": {
+      },
+      "template": "Begin.\n  {{! Indented Comment Block! }}\nEnd.\n",
+      "expected": "Begin.\nEnd.\n"
+    },
+    {
+      "name": "Standalone Line Endings",
+      "desc": "\"\\r\\n\" should be considered a newline for standalone tags.",
+      "data": {
+      },
+      "template": "|\r\n{{! Standalone Comment }}\r\n|",
+      "expected": "|\r\n|"
+    },
+    {
+      "name": "Standalone Without Previous Line",
+      "desc": "Standalone tags should not require a newline to precede them.",
+      "data": {
+      },
+      "template": "  {{! I'm Still Standalone }}\n!",
+      "expected": "!"
+    },
+    {
+      "name": "Standalone Without Newline",
+      "desc": "Standalone tags should not require a newline to follow them.",
+      "data": {
+      },
+      "template": "!\n  {{! I'm Still Standalone }}",
+      "expected": "!\n"
+    },
+    {
+      "name": "Multiline Standalone",
+      "desc": "All standalone comment lines should be removed.",
+      "data": {
+      },
+      "template": "Begin.\n{{!\nSomething's going on here...\n}}\nEnd.\n",
+      "expected": "Begin.\nEnd.\n"
+    },
+    {
+      "name": "Indented Multiline Standalone",
+      "desc": "All standalone comment lines should be removed.",
+      "data": {
+      },
+      "template": "Begin.\n  {{!\n    Something's going on here...\n  }}\nEnd.\n",
+      "expected": "Begin.\nEnd.\n"
+    },
+    {
+      "name": "Indented Inline",
+      "desc": "Inline comments should not strip whitespace",
+      "data": {
+      },
+      "template": "  12 {{! 34 }}\n",
+      "expected": "  12 \n"
+    },
+    {
+      "name": "Surrounding Whitespace",
+      "desc": "Comment removal should preserve surrounding whitespace.",
+      "data": {
+      },
+      "template": "12345 {{! Comment Block! }} 67890",
+      "expected": "12345  67890"
+    },
+    {
+      "name": "Variable Name Collision",
+      "desc": "Comments must never render, even if variable with same name exists.",
+      "data": {
+        "! comment": 1,
+        "! comment ": 2,
+        "!comment": 3,
+        "comment": 4
+      },
+      "template": "comments never show: >{{! comment }}<",
+      "expected": "comments never show: ><"
+    }
+  ]
+}

specs/comments.yml

@@ -101,3 +101,9 @@ tests:
     data: { }
     template: '12345 {{! Comment Block! }} 67890'
     expected: '12345  67890'
+
+  - name: Variable Name Collision
+    desc: Comments must never render, even if variable with same name exists.
+    data: { '! comment': 1, '! comment ': 2, '!comment': 3, 'comment': 4}
+    template: 'comments never show: >{{! comment }}<'
+    expected: 'comments never show: ><'

specs/delimiters.json

@@ -1 +1,132 @@
-{"__ATTN__":"Do not edit this file; changes belong in the appropriate YAML file.","overview":"Set Delimiter tags are used to change the tag delimiters for all content\nfollowing the tag in the current compilation unit.\n\nThe tag's content MUST be any two non-whitespace sequences (separated by\nwhitespace) EXCEPT an equals sign ('=') followed by the current closing\ndelimiter.\n\nSet Delimiter tags SHOULD be treated as standalone when appropriate.\n","tests":[{"name":"Pair Behavior","data":{"text":"Hey!"},"expected":"(Hey!)","template":"{{=<% %>=}}(<%text%>)","desc":"The equals sign (used on both sides) should permit delimiter changes."},{"name":"Special Characters","data":{"text":"It worked!"},"expected":"(It worked!)","template":"({{=[ ]=}}[text])","desc":"Characters with special meaning regexen should be valid delimiters."},{"name":"Sections","data":{"section":true,"data":"I got interpolated."},"expected":"[\n  I got interpolated.\n  |data|\n\n  {{data}}\n  I got interpolated.\n]\n","template":"[\n{{#section}}\n  {{data}}\n  |data|\n{{/section}}\n\n{{= | | =}}\n|#section|\n  {{data}}\n  |data|\n|/section|\n]\n","desc":"Delimiters set outside sections should persist."},{"name":"Inverted Sections","data":{"section":false,"data":"I got interpolated."},"expected":"[\n  I got interpolated.\n  |data|\n\n  {{data}}\n  I got interpolated.\n]\n","template":"[\n{{^section}}\n  {{data}}\n  |data|\n{{/section}}\n\n{{= | | =}}\n|^section|\n  {{data}}\n  |data|\n|/section|\n]\n","desc":"Delimiters set outside inverted sections should persist."},{"name":"Partial Inheritence","data":{"value":"yes"},"expected":"[ .yes. ]\n[ .yes. ]\n","template":"[ {{>include}} ]\n{{= | | =}}\n[ |>include| ]\n","desc":"Delimiters set in a parent template should not affect a partial.","partials":{"include":".{{value}}."}},{"name":"Post-Partial Behavior","data":{"value":"yes"},"expected":"[ .yes.  .yes. ]\n[ .yes.  .|value|. ]\n","template":"[ {{>include}} ]\n[ .{{value}}.  .|value|. ]\n","desc":"Delimiters set in a partial should not affect the parent template.","partials":{"include":".{{value}}. {{= | | =}} .|value|."}},{"name":"Surrounding Whitespace","data":{},"expected":"|  |","template":"| {{=@ @=}} |","desc":"Surrounding whitespace should be left untouched."},{"name":"Outlying Whitespace (Inline)","data":{},"expected":" | \n","template":" | {{=@ @=}}\n","desc":"Whitespace should be left untouched."},{"name":"Standalone Tag","data":{},"expected":"Begin.\nEnd.\n","template":"Begin.\n{{=@ @=}}\nEnd.\n","desc":"Standalone lines should be removed from the template."},{"name":"Indented Standalone Tag","data":{},"expected":"Begin.\nEnd.\n","template":"Begin.\n  {{=@ @=}}\nEnd.\n","desc":"Indented standalone lines should be removed from the template."},{"name":"Standalone Line Endings","data":{},"expected":"|\r\n|","template":"|\r\n{{= @ @ =}}\r\n|","desc":"\"\\r\\n\" should be considered a newline for standalone tags."},{"name":"Standalone Without Previous Line","data":{},"expected":"=","template":"  {{=@ @=}}\n=","desc":"Standalone tags should not require a newline to precede them."},{"name":"Standalone Without Newline","data":{},"expected":"=\n","template":"=\n  {{=@ @=}}","desc":"Standalone tags should not require a newline to follow them."},{"name":"Pair with Padding","data":{},"expected":"||","template":"|{{= @   @ =}}|","desc":"Superfluous in-tag whitespace should be ignored."}]}
+{
+  "__ATTN__": "Do not edit this file; changes belong in the appropriate YAML file.",
+  "overview": "Set Delimiter tags are used to change the tag delimiters for all content\nfollowing the tag in the current compilation unit.\n\nThe tag's content MUST be any two non-whitespace sequences (separated by\nwhitespace) EXCEPT an equals sign ('=') followed by the current closing\ndelimiter.\n\nSet Delimiter tags SHOULD be treated as standalone when appropriate.\n",
+  "tests": [
+    {
+      "name": "Pair Behavior",
+      "desc": "The equals sign (used on both sides) should permit delimiter changes.",
+      "data": {
+        "text": "Hey!"
+      },
+      "template": "{{=<% %>=}}(<%text%>)",
+      "expected": "(Hey!)"
+    },
+    {
+      "name": "Special Characters",
+      "desc": "Characters with special meaning regexen should be valid delimiters.",
+      "data": {
+        "text": "It worked!"
+      },
+      "template": "({{=[ ]=}}[text])",
+      "expected": "(It worked!)"
+    },
+    {
+      "name": "Sections",
+      "desc": "Delimiters set outside sections should persist.",
+      "data": {
+        "section": true,
+        "data": "I got interpolated."
+      },
+      "template": "[\n{{#section}}\n  {{data}}\n  |data|\n{{/section}}\n\n{{= | | =}}\n|#section|\n  {{data}}\n  |data|\n|/section|\n]\n",
+      "expected": "[\n  I got interpolated.\n  |data|\n\n  {{data}}\n  I got interpolated.\n]\n"
+    },
+    {
+      "name": "Inverted Sections",
+      "desc": "Delimiters set outside inverted sections should persist.",
+      "data": {
+        "section": false,
+        "data": "I got interpolated."
+      },
+      "template": "[\n{{^section}}\n  {{data}}\n  |data|\n{{/section}}\n\n{{= | | =}}\n|^section|\n  {{data}}\n  |data|\n|/section|\n]\n",
+      "expected": "[\n  I got interpolated.\n  |data|\n\n  {{data}}\n  I got interpolated.\n]\n"
+    },
+    {
+      "name": "Partial Inheritence",
+      "desc": "Delimiters set in a parent template should not affect a partial.",
+      "data": {
+        "value": "yes"
+      },
+      "partials": {
+        "include": ".{{value}}."
+      },
+      "template": "[ {{>include}} ]\n{{= | | =}}\n[ |>include| ]\n",
+      "expected": "[ .yes. ]\n[ .yes. ]\n"
+    },
+    {
+      "name": "Post-Partial Behavior",
+      "desc": "Delimiters set in a partial should not affect the parent template.",
+      "data": {
+        "value": "yes"
+      },
+      "partials": {
+        "include": ".{{value}}. {{= | | =}} .|value|."
+      },
+      "template": "[ {{>include}} ]\n[ .{{value}}.  .|value|. ]\n",
+      "expected": "[ .yes.  .yes. ]\n[ .yes.  .|value|. ]\n"
+    },
+    {
+      "name": "Surrounding Whitespace",
+      "desc": "Surrounding whitespace should be left untouched.",
+      "data": {
+      },
+      "template": "| {{=@ @=}} |",
+      "expected": "|  |"
+    },
+    {
+      "name": "Outlying Whitespace (Inline)",
+      "desc": "Whitespace should be left untouched.",
+      "data": {
+      },
+      "template": " | {{=@ @=}}\n",
+      "expected": " | \n"
+    },
+    {
+      "name": "Standalone Tag",
+      "desc": "Standalone lines should be removed from the template.",
+      "data": {
+      },
+      "template": "Begin.\n{{=@ @=}}\nEnd.\n",
+      "expected": "Begin.\nEnd.\n"
+    },
+    {
+      "name": "Indented Standalone Tag",
+      "desc": "Indented standalone lines should be removed from the template.",
+      "data": {
+      },
+      "template": "Begin.\n  {{=@ @=}}\nEnd.\n",
+      "expected": "Begin.\nEnd.\n"
+    },
+    {
+      "name": "Standalone Line Endings",
+      "desc": "\"\\r\\n\" should be considered a newline for standalone tags.",
+      "data": {
+      },
+      "template": "|\r\n{{= @ @ =}}\r\n|",
+      "expected": "|\r\n|"
+    },
+    {
+      "name": "Standalone Without Previous Line",
+      "desc": "Standalone tags should not require a newline to precede them.",
+      "data": {
+      },
+      "template": "  {{=@ @=}}\n=",
+      "expected": "="
+    },
+    {
+      "name": "Standalone Without Newline",
+      "desc": "Standalone tags should not require a newline to follow them.",
+      "data": {
+      },
+      "template": "=\n  {{=@ @=}}",
+      "expected": "=\n"
+    },
+    {
+      "name": "Pair with Padding",
+      "desc": "Superfluous in-tag whitespace should be ignored.",
+      "data": {
+      },
+      "template": "|{{= @   @ =}}|",
+      "expected": "||"
+    }
+  ]
+}