docs/reference: add template string section

2 files changed, 43 insertions, 0 deletions

diff --git a/docs/reference/01_syntax.md b/docs/reference/01_syntax.md
index 445725c..4db70f9 100644
--- a/docs/reference/01_syntax.md
+++ b/docs/reference/01_syntax.md
@@ -71,10 +71,41 @@ immediately after the opening parenthesis. Whitespace between the opening
 parenthesis and the first subexpression or the closing parenthesis and the last
 subexpression is optional.
 
+The first subexpression is considered the head of the cell and determines the
+behaviour of the cell.
+
 ## tags
 Tags consist of one or more digits (`0`-`9`) enclosed in square brackets (`[`
 and `]`). `[1]` and `[255]` are examples of valid tags.
 
+## template strings
+Template Strings are a different syntax for cells that allows embedding alv
+expressions inside of a string literal. They can be used to perform string
+substitution, especially within code of other languages.
+
+Template strings start with the character `$` followed by an optional tag and
+a symbol that functions as the head of the cell and finally a `"`-delimited
+string literal. Within the string literal, a `$` character begins an
+interpolation expression unless escaped by a single preceding blackslash.
+
+The following are example template strings:
+
+    $empty""
+    $hello"world"
+    $fmt"three is $3 and four is $"four""
+    $[99]fmt"five is $(+ 3 2)"
+    $fmt"there is \$no substitution here"
+
+Template strings are syntactic sugar that transforms into an array of string
+pieces and the values to substitute, the following cell expressions are
+semantically identical to the previous examples respectively:
+
+    (empty [""])
+    (hello ["world"])
+    (fmt ["three is " " and four is " ""] 3 "four")
+    ([99]fmt ["five is" ""] (+ 3 2))
+    (fmt ["there is $no substitution here"])
+
 # whitespace
 The space, tab, newline, and line-feed special characters constitute whitespace
 and may be repeated any number of times to form a chunk. A chunk of whitespace
diff --git a/spec/internal/parsing_spec.moon b/spec/internal/parsing_spec.moon
index 47de338..8f9b79e 100644
--- a/spec/internal/parsing_spec.moon
+++ b/spec/internal/parsing_spec.moon
@@ -134,6 +134,18 @@ describe 'TemplateString parsing', ->
     node = verify_parse tplstr, '$hi"\\$(this would\\${3}be invalid!"'
     assert.is.same {'$(this would${3}be invalid!'}, node.children[2]\eval!.result!
 
+  test 'can contain quotes', ->
+    node = verify_parse tplstr, '$hi"$"this" is a string"'
+    assert.is.same {'', ' is a string'}, node.children[2]\eval!.result!
+    assert.is.same 'this', node.children[3]\eval!.result!
+
+    node = verify_parse tplstr, '$hi"a string is $"this""'
+    assert.is.same {'a string is ', ''}, node.children[2]\eval!.result!
+    assert.is.same 'this', node.children[3]\eval!.result!
+
+    node = verify_parse tplstr, '$hi"uh $(= "a" "b") huh"'
+    assert.is.same {'uh ', ' huh'}, node.children[2]\eval!.result!
+
   test 'can be applied', ->
     node = verify_parse tplstr, '$[123]hi" string with $3$5 some $(= "contents") "'
     substituted = node.__class.subst node.children[2]\eval!.result!, {123, "foot", " where "}