From 200db01b138fa8897e2f7992b00b593589063856 Mon Sep 17 00:00:00 2001
From: Jeremy Wall <jeremy@marzhillstudios.com>
Date: Sun, 30 Jul 2017 08:48:18 -0500
Subject: [PATCH] Add documentation for the base types and simple expressions.

---
 README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 58 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 67007a4..94aecac 100644
--- a/README.md
+++ b/README.md
@@ -16,23 +16,69 @@ preferred format.
 
 ## Examples
 
+#### Base Types
+
+UCG has 3 simple types Integer, Float, and String as well as Tuple for complex
+types.
+
+    1;
+    
+    1.0;
+    
+    "string";
+    
+    {
+        field1 = 1,
+        field2 = "strawberry",
+    };
+
+To specify that a number is a Float you must include a decimal point. Otherwise
+the number will be an integer. UCG does type inference for tuple fields based
+off of the value assigned.
+
+### Simple Expressions
+
+UCG supports simple math expressions using `+`, `-`, `*`, `/`) and string
+concatenation using `+`. The expressions enforce the same type between operands.
+
+    1 + 1;
+    
+    1.0 + 1.0;
+    
+    "foo" + "bar";
+
 ### Bindings and Tuples.
-Let statements introduce a new name in a ucg file. Most configurations
+
+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.
 
     let mysql_conn_base = {
       host = "db1.local.net",
-      port = 3306,  // knows the difference between strings and numbers.
+      port = 3306,
       database = "place-holder",
     };
 
-Tuple fields have no ordering guarantees.
+Tuple fields have no ordering guarantees. All bindings are immutable and
+can not be reassigned to once defined.
+
+### Variables
+
+UCG can reference a binding using variables. Any named value using
+a let statement can be referred to with that name within the file it
+is introduced. You can descend into a tuple using a dotted syntax.
+
+    let var = "My value";
+    let tplvar = {
+        field = var,
+    }
+    let field_var = tplvar.field;
 
 ### 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
+Even though all bindings are immutable, Tuples have a copy on modify syntax.
+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.
 
     let mysql_app_conn = mysql_conn_base{
@@ -40,11 +86,9 @@ 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.
+overriding a field in a base tuple. The port field below expects an
+Integer not a String so you will get a TypeFail error.
 
 
     let bad_mysql_conn = mysql_conn_base{
@@ -55,17 +99,17 @@ number not a string so you will get a TypeFail error.
 
 The grammar has limited support for conditionals using the select expression.
 
-
     let my_sql_app_conn = mysql_conn_base{
-      port = select prod, 33007 {
+      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.
+The first argument to the select call is the key you wish to
+select. This argument must be a string or an expression that outputs a
+string. 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