From 315fbabc3d1c8f0eed59f7715cdc2ee65e9ee9b1 Mon Sep 17 00:00:00 2001
From: Jeremy Wall <jeremy@marzhillstudios.com>
Date: Mon, 28 Jan 2019 21:29:31 -0600
Subject: [PATCH] DOCS: update the grammar and expression docs.

Adds the new form of format expressions using tuples.

Regarding Issue #23
---
 docsite/site/content/reference/expressions.md | 21 +++++++++++++++++--
 docsite/site/content/reference/grammar.md     |  4 +++-
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/docsite/site/content/reference/expressions.md b/docsite/site/content/reference/expressions.md
index c972c89..cd9a637 100644
--- a/docsite/site/content/reference/expressions.md
+++ b/docsite/site/content/reference/expressions.md
@@ -258,8 +258,9 @@ let imported_val = (import "some_file.ucg").val;
 Format Expressions
 ----------
 
-UCG has a format expression that has a limited form of string templating. A
-format expression starts with a string followed by the `%` operator and a list
+UCG has a format expression that has a limited form of string templating. Format expressions come in two forms.
+
+The simplest form starts with a string followed by the `%` operator and a list
 of arguments in parentheses separated by commas. Trailing commas are allowed.
 The format string should have `@` characters in each location where a value
 should be placed. Any primitive value can be used as an argument.
@@ -268,6 +269,22 @@ should be placed. Any primitive value can be used as an argument.
 "https://@:@/" % (host, port)
 ```
 
+A slightly more complex form starts with a string followed by the `%` operator and
+an expression. the template string can then reference the result of the expression
+in expressions embedded within the format string. The expressions result can be referenced using the special name `item` in the embedded expression. The result
+of the expression will be rendered as the default string representation in the
+resulting string.
+
+```
+let tpl = {
+    foo = {
+        bar = [0, 1, 2],
+    },
+};
+
+"foo.bar.1 == @{item.foo.bar.1}" % tpl;
+```
+
 Range Expression
 ----------------
 
diff --git a/docsite/site/content/reference/grammar.md b/docsite/site/content/reference/grammar.md
index fcc8f8b..ecee246 100644
--- a/docsite/site/content/reference/grammar.md
+++ b/docsite/site/content/reference/grammar.md
@@ -132,7 +132,9 @@ call_expr: bareword, lparen, [arglist], rparen ;
 #### Format Expression
 
 ```
-format_expr: str, percent, lparen, [arglist], rparen ;
+format_arg_list: lparen, [arglist], rparen ;
+foramt_expr_arg: expression ;
+format_expr: str, percent, (format_arg_list | format_expr_arg) ;
 ```
 
 ### Functional processing expressions