Add readme and example files

3 files changed, 116 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..48d0afc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,108 @@
+# template
+
+This is an extremely simple, general-purpose templating script written in awk.
+
+To get started, define a list of variables in a file:
+
+    food = pizza
+    beverage = coffee
+
+    # Comments look like this, and you can reference previously defined
+    # variables like this:
+    dinner = {{ food }}
+
+Then reference those variables in your template file by enclosing them in
+double braces:
+
+    My favorite food is {{ food }}, and my favorite beverage is {{ coffee }}.
+
+Then pass your variable file and template file, in that order, as arguments to
+the `template` script:
+
+    ./template vars favorite-foods.tpl
+
+The result will be written to stdout.
+
+## Example
+
+The `example` directory provides concise sample files that can be processed by
+running the following command from the project directory:
+
+	./template examples/vars examples/text.tpl
+
+## Specification
+
+This section describes the behavior of the program in excruciating detail and
+will be of little interest to most users.
+
+The program may be invoked as follows:
+
+    `template [variable file] [template file...]`
+
+The variable file will be parsed, the variables defined within will be
+substituted for all apperances of corresponding template variables that appear
+in the given template file(s), and the processed text will be printed to
+stdout. If multiple template files are specified, their contents will be
+concatenated in the output.
+
+The following subsections specify the behavior of the program in detail.
+Illegal inputs proscribed below will not necessarily produce an error message
+but may result in undefined behavior.
+
+### Template Variable Format
+
+A template variable consists of a variable name enclosed in double braces,
+with zero or more whitespace characters separating the variable name and
+the braces. The following examples are all legal:
+
+    {{ my_var }}
+    {{my_var}}
+    {{  my_var  }}
+    {{      my_var}}
+
+### Variable File
+
+Variables are defined as key-value pairs separated by the character `=`.
+The `=` character may be surrounded by an arbitrary number of whitespace
+characters on either side. The following examples are all legal:
+
+    my_var = foo
+    my_var=foo
+    my_var      = foo
+
+Lines beginning with the character `#` are ignored. Note that text following
+`#` is *not* otherwise ignored, so trailing inline comments are not supported.
+
+Variable names may contain any character supported by the version of awk usd to
+execute this script except for the `=` character or any of the regular
+expression metacharacters:
+
+    \ ^ $ . [ ] | ( ) * + ? { }
+
+There is one exception to this rule: Variable values may reference variables
+defined earlier in the file, in which case they must use the brace- delimited
+variable format described above. Any other use of braces or any other
+prohibited character remains illegal when referencing a previously defined
+variable. The specified variable name must reference an actual variable
+previously defined in the file.
+
+When a value references a previously defined variable, the most recent value of
+that variable is used. If a variable name appears more than once, the previous
+value is overwritten on each occurence; previous assignments are not affected.
+
+For example, suppose a variable file contained the following lines:
+
+    food = pizza
+    favorite_food = {{ food }}
+    food = apple
+
+After the value was parsed, the value of `favorite_food` would be `pizza` and
+the value of `food` would be `apple`.
+
+### Template File
+
+A template consists of arbitrary content containing zero or more template
+variables in the brace-delimited format described above. A variable may
+appear any number of times within a file or a line. A template variable that
+does not reference a valid variable defined in the variable file will be
+ignored.
diff --git a/example/text.tpl b/example/text.tpl
new file mode 100644
index 0000000..4b6b5a4
--- /dev/null
+++ b/example/text.tpl
@@ -0,0 +1,3 @@
+The numbers before 3 are {{ one }} and {{two}}. The first number is {{ one }}.
+
+My favorite color is {{ favorite_color }}. My car is {{ car_color }}.
diff --git a/example/vars b/example/vars
new file mode 100644
index 0000000..b8182ba
--- /dev/null
+++ b/example/vars
@@ -0,0 +1,5 @@
+# This is a comment.
+one	= 1
+two	= 2
+favorite_color=bluish gray
+car_color = {{ favorite_color }}