Support piping input to plugin

Signed-off-by: Dave Henderson <dhenderson@gmail.com>

2 files changed, 59 insertions, 7 deletions

diff --git a/docs/content/config.md b/docs/content/config.md
index 22b6f239..91b82fc6 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -300,22 +300,72 @@ outputMap: |
 
 See [`--plugin`](../usage/#--plugin).
 
-An mapping of key/value pairs to plug in custom functions for use in the templates.
+A map that configures custom functions for use in the templates. The key is the
+name of the function, and the value configures the plugin. The value is a map
+containing the command (`cmd`) and the options `pipe` (boolean) and `timeout`
+(duration).
+
+Alternatively, the value can be a string, which sets `cmd`.
 
 ```yaml
 in: '{{ "hello world" | figlet | lolcat }}'
 plugins:
-  figlet: /usr/local/bin/figlet
+  figlet:
+    cmd: /usr/local/bin/figlet
+    pipe: true
+    timeout: 1s
   lolcat: /home/hairyhenderson/go/bin/lolcat
 ```
 
+### `cmd`
+
+The path to the plugin executable (or script) to run.
+
+### `pipe`
+
+Whether to pipe the final argument of the template function to the plugin's
+Stdin, or provide as a separate argument.
+
+For example, given a `myfunc` plugin with a `cmd` of `/bin/myfunc`:
+
+With this template:
+```
+{{ print "bar" | myfunc "foo" }}
+```
+
+If `pipe` is `true`, the plugin executable will receive the input `"bar"` as its
+Stdin, like this shell command:
+
+```console
+$ echo -n "bar" | /bin/myfunc "foo"
+```
+
+If `pipe` is `false` (the default), the plugin executable will receive the
+input `"bar"` as its last argument, like this shell command:
+
+```console
+$ /bin/myfunc "foo" "bar"
+```
+
+_Note:_ in a chained pipeline (e.g. `{{ foo | bar }}`), the result of each
+command is passed as the final argument of the next, and so the template above
+could be written as `{{ myfunc "foo" "bar" }}`.
+
+### `timeout`
+
+The plugin's timeout. After this time, the command will be terminated and the
+template function will return an error. The value must be a valid
+[duration][] such as `1s`, `1m`, `1h`,
+
+The default is `5s`.
+
 ## `pluginTimeout`
 
 See [`--plugin`](../usage/#--plugin).
 
-Sets the timeout for running plugins. By default, plugins will time out after 5
-seconds. This value can be set to override this default. The value must be
-a valid [duration](../functions/time/#time-parseduration) such as `10s` or `3m`.
+Sets the timeout for all configured plugins. Overrides the default of `5s`.
+After this time, plugin commands will be killed. The value must be a valid
+[duration][] such as `10s` or `3m`.
 
 ```yaml
 plugins:
@@ -368,3 +418,4 @@ templates:
 [command-line arguments]: ../usage
 [file an issue]: https://github.com/hairyhenderson/gomplate/issues/new
 [YAML]: http://yaml.org
+[duration]: (../functions/time/#time-parseduration)
diff --git a/docs/content/usage.md b/docs/content/usage.md
index c231955f..b4af259e 100644
--- a/docs/content/usage.md
+++ b/docs/content/usage.md
@@ -236,6 +236,8 @@ A few different forms are valid:
 
 ### `--plugin`
 
+_See the [config file](../config/#plugins) for more plugin configuration options._
+
 Some specialized use cases may need functionality that gomplate isn't capable
 of on its own. If you have a command or script to perform this functionality,
 you can plug in your own custom functions with the `--plugin` flag:
@@ -357,7 +359,7 @@ post-exec command.
 
 ## Suppressing empty output
 
-Sometimes it can be desirable to suppress empty output (i.e. output consisting of only whitespace). To do so, set `suppressEmpty: true` in your [config][] file, or `GOMPLATE_SUPPRESS_EMPTY=true` in your environment:
+Sometimes it can be desirable to suppress empty output (i.e. output consisting of only whitespace). To do so, set `suppressEmpty: true` in your [config](../config/#suppressempty) file, or `GOMPLATE_SUPPRESS_EMPTY=true` in your environment:
 
 ```console
 $ export GOMPLATE_SUPPRESS_EMPTY=true
@@ -368,6 +370,5 @@ cat: out: No such file or directory
 
 [default context]: ../syntax/#the-context
 [context]: ../syntax/#the-context
-[config]: ../config/#suppressempty
 [external templates]: ../syntax/#external-templates
 [`.gitignore`]: https://git-scm.com/docs/gitignore