From 42b5b8f656b1306ef95fb7d5082ad6fc38b48f68 Mon Sep 17 00:00:00 2001
From: Jeremy Wall <jeremy@marzhillstudios.com>
Date: Sat, 29 Jul 2017 13:20:57 -0500
Subject: [PATCH] Expand the examples section of the README.

---
 README.md | 44 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 8f059e9..67007a4 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
-# Universal Configuration Generator. - A working title.
+# Universal Configuration Grammar - Working Title.
 
-This is an experiment in configuration management. The approach is not
+This is an experiment in configuration management. The approach is **not**
 to create a "parsable" config file format.  We have plenty of
 those. Instead we try to specify a grammar for describing
 configuration values that can then target various configuration
@@ -10,12 +10,13 @@ In theory this could support anything from command line flags to json
 to yaml or toml or even xml.
 
 The goal is to allow a global shared configuration repository that can
-be version controlled, enforce some typesafety, and output
+be version controlled, enforce _some_ typesafety, and output
 configuration for any application regardless of that applications
 preferred format.
 
 ## Examples
 
+### Bindings and Tuples.
 Let statements introduce a new name in a ucg file. Most configurations
 will be a tuple like below. Tuples are delimited by braces and have a list
 of named fields in them.
@@ -26,6 +27,10 @@ of named fields in them.
       database = "place-holder",
     };
 
+Tuple fields have no ordering guarantees.
+
+### Copying and modifying Tuples.
+
 You can use a previously defined tuple as the basis for a new tuple. Doing
 this will make a copy of the source tuple and allow you to add new fields
 or override an already existing field.
@@ -35,6 +40,8 @@ or override an already existing field.
        timeout = 30,
     };
 
+### Limited Types safety
+
 Types are inferred for tuple fields. We enforce type consistency when
 overriding a field in a base tuple. The port field below expects a
 number not a string so you will get a TypeFail error.
@@ -43,3 +50,34 @@ number not a string so you will get a TypeFail error.
     let bad_mysql_conn = mysql_conn_base{
        port = "3307",
      }
+
+### Conditional Values
+
+The grammar has limited support for conditionals using the select expression.
+
+
+    let my_sql_app_conn = mysql_conn_base{
+      port = select prod, 33007 {
+          prod = 3307,
+          qa = 3308,
+      }
+    };
+
+The first argument to the select call is the key you wish to select. The second
+argument is a default value to use if the key doesn't exist. The third is a set
+of fields to choose from.
+
+### Macros
+
+We also support a limited macro facility with the macro expression.
+
+    let conn_string_macro = macro (host, port) {
+      conn_str = "mysql://" + host + ":" + port,
+    }
+    
+    let web_conn = conn_string_macro ("proddb", "3307");
+    let conn_string = web_conn.conn_str;
+
+Macro's always output a tuple whose fields are evaluated at the location they
+are called from. You can acccess the generated fields from the resulting tuple
+like usual.