Envsubst params (#1147)

* Can give envsubst optional arguments

pkg/yqlib/doc/operators/env-variable-operators.md

@@ -8,6 +8,17 @@ There are three operators:
 - `envsubst` which you pipe strings into and it interpolates environment variables in strings using [envsubst](https://github.com/a8m/envsubst). 
 
 
+## EnvSubst Options
+You can optionally pass envsubst any of the following options:
+  - nu: NoUnset, this will fail if there are any referenced variables that are not set
+  - ne: NoEmpty, this will fail if there are any referenced variables that are empty
+  - ff: FailFast, this will abort on the first failure (rather than collect all the errors)
+
+E.g:
+`envsubst(ne, ff)` will fail on the first empty variable.
+
+See [Imposing Restrictions](https://github.com/a8m/envsubst#imposing-restrictions) in the `envsubst` documentation for more information, and below for examples.
+
 ## Tip
 To replace environment variables across all values in a document, `envsubst` can be used with the recursive descent operator
 as follows:
@@ -133,23 +144,83 @@ the cat meows
 ## Replace strings with envsubst, missing variables
 Running
 ```bash
-myenv="cat" yq --null-input '"the ${myenvnonexisting} meows" | envsubst'
+yq --null-input '"the ${myenvnonexisting} meows" | envsubst'
 ```
 will output
 ```yaml
 the  meows
 ```
 
+## Replace strings with envsubst(nu), missing variables
+(nu) not unset, will fail if there are unset (missing) variables
+
+Running
+```bash
+yq --null-input '"the ${myenvnonexisting} meows" | envsubst(nu)'
+```
+will output
+```bash
+Error: variable ${myenvnonexisting} not set
+```
+
+## Replace strings with envsubst(ne), missing variables
+(ne) not empty, only validates set variables
+
+Running
+```bash
+yq --null-input '"the ${myenvnonexisting} meows" | envsubst(ne)'
+```
+will output
+```yaml
+the  meows
+```
+
+## Replace strings with envsubst(ne), empty variable
+(ne) not empty, will fail if a references variable is empty
+
+Running
+```bash
+myenv="" yq --null-input '"the ${myenv} meows" | envsubst(ne)'
+```
+will output
+```bash
+Error: variable ${myenv} set but empty
+```
+
 ## Replace strings with envsubst, missing variables with defaults
 Running
 ```bash
-myenv="cat" yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst'
+yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst'
 ```
 will output
 ```yaml
 the dog meows
 ```
 
+## Replace strings with envsubst(nu), missing variables with defaults
+Having a default specified skips over the missing variable.
+
+Running
+```bash
+yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst(nu)'
+```
+will output
+```yaml
+the dog meows
+```
+
+## Replace strings with envsubst(ne), missing variables with defaults
+Fails, because the variable is explicitly set to blank.
+
+Running
+```bash
+myEmptyEnv="" yq --null-input '"the ${myEmptyEnv-dog} meows" | envsubst(ne)'
+```
+will output
+```bash
+Error: variable ${myEmptyEnv} set but empty
+```
+
 ## Replace string environment variable in document
 Given a sample.yml file of:
 ```yaml
@@ -164,3 +235,26 @@ will output
 v: cat meow
 ```
 
+## (Default) Return all envsubst errors
+By default, all errors are returned at once.
+
+Running
+```bash
+yq --null-input '"the ${notThere} ${alsoNotThere}" | envsubst(nu)'
+```
+will output
+```bash
+Error: variable ${notThere} not set
+variable ${alsoNotThere} not set
+```
+
+## Fail fast, return the first envsubst error (and abort)
+Running
+```bash
+yq --null-input '"the ${notThere} ${alsoNotThere}" | envsubst(nu,ff)'
+```
+will output
+```bash
+Error: variable ${notThere} not set
+```
+