(docs): Add template documentation to README

README.md

@@ -9,6 +9,7 @@ For questions join the [#fakedata](https://gophers.slack.com/messages/fakedata/)
 - [Overview](#overview)
 - [Generators](#generators)
 - [Formatters](#formatters)
+- [Templates](#templates)
 - [How to install](#how-to-install)
 - [How to contribute](#how-to-contribute)
 - [Code of conduct](#code-of-conduct)
@@ -150,6 +151,135 @@ fakedata --format=sql --limit=1 --table=users login=email referral=domain
 INSERT INTO users (login,referral) VALUES ('[email protected]' 'test.us');
 ```
 
+# Templates
+
+`fakedata` supports parsing and executing template files for generating customized output formats. `fakedata` executes the provided template a number of times based on the limit flag (`-l`, `--limit`) and writes the output to `stdout`, exactly like using inline generators.
+
+The template functionality can be used in one of two ways:
+
+### Template file
+
+To read an parse an actual template file from disk, run `fakedata --template template.tmpl` which will read in the file `template.tmpl` and execute it 10 times (default of `--limit`). If there's an error reading, `fakedata` exits with status code 1 and prints the error.
+
+### Shell Pipes
+
+You can also pipe a template to `fakedata`. For example you can run the following `echo` command with a pile to pass a template to fakedata.
+
+```sh
+$ echo "#{{ Int 0 100}} {{ Name }} <{{ Email }}>" | fakedata
+```
+
+`fakedata` will read the template from `stdout` and execute it.
+
+### Loops
+
+By default the templates loop based on the `--limit` flag. If you want to execute your template 50 times, add `--limit 50` to the command. When using the Template function `Loop` (see below), you should specify `--limit 1` to avoid running you template multiple times.
+
+Each generator is available as a named function. The generator function names are as follows:
+
+```
+Date
+DomainTld
+DomainName
+Country
+CountryCode
+State
+Timezone
+Username
+NameFirst
+NameLast
+Color
+ProductCategory
+ProductName
+EventAction
+HTTPMethod
+Name
+Email
+Domain
+IPv4
+IPv6
+MacAddress
+Latitude
+Longitude
+Double
+Int
+Enum
+File
+```
+
+All the generators return a string and take no arguments, expect for:`Enum`, `File` and `Int`. Parameters for these functions are described below.
+
+### `Enum`
+
+Enum takes one or more strings and returns a random string on each run. Strings are passed to Enum like so:
+
+```html
+{{ Enum "feature" "bug" "documentation" }}
+```
+
+This Enum will return either the string `feature`, `bug`, or `documentation` for each run.
+
+### `File`
+
+File reads a file from disk and returns a random line on each run. It takes one parameter which is the path to the file on disk.
+
+```html
+{{ File "/var/data/dummy/dummy.txt" }}
+```
+
+### `Int`
+
+Int takes one or two integer values and returns a number within this range. By default it returns a number between 0 and 1000.
+
+```html
+{{ Int 15 20 }}
+```
+
+The above function call returns a number between 15 and 20 for each run.
+
+### Additional template helpers
+
+Beside the generator functions, the `fakedata` template implementation provides a set of helper functions:
+
+- `Loop`
+- `Odd`
+- `Even`
+
+When using a custom loop make sure to use `--limit 1`, otherwise the loop will run multiple times! Running a template with `{{ range Loop 5}}` and `--limit 5` will execute 25 times.
+
+If you need to create your own loop for advanced templates you can use the `{{ Loop }}` function. This function takes a single integer as parameter which is the number of iterations. `Loop` has to be used with `range` e.g.
+
+```html
+{{ range Loop 10 }}
+  I am printed 10 times!
+{{ end }}
+```
+
+In combination with `Loop` and `range` you can use `Odd` and `Even` to determine if the current iteration is odd or even. This is especially helpful when creating HTML tables, for example:
+
+```html
+{{ range $i, $j := Loop 5 }}
+<tr>
+  {{ if Odd $i -}}
+  <td class="odd">
+    {{- else -}}
+  <td class="even">
+    {{- end -}}
+    {{ Name }}
+  </td>
+</tr>
+{{ end }}
+```
+
+By using `Odd` we can create tables with a class name of  `odd` and `even` when generating our HTML. Odd takes an integer as parameter which is why we need to assign the return values of `Loop 5` to the variables `$i` and `$j`.
+
+Beside the helper function `Loop`, `Odd`, and `Even` Go templates also support manipulation with `printf`. By using `printf` we can create a custom output, for example to display a full name in the format `Lastname Firstname` instead of `Firstname Lastname`.
+
+```html
+{{ printf "%s %s" NameLast NameFirst }}
+```
+
+This `printf` will return a name displayed as `LastName FirstName` for each run.
 # How to install
 
 ## Homebrew