From e9d20fb807768553065aed7d364c0eb1cb5468b5 Mon Sep 17 00:00:00 2001 From: moe Date: Mon, 9 Oct 2023 00:06:06 +0200 Subject: [PATCH] Update README --- README.md | 88 ++++++++++++++++++++++++++++++++++--- docs/templates/README.md.j2 | 72 +++++++++++++++++++++++++++++- 2 files changed, 154 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2237d37..d98df0f 100644 --- a/README.md +++ b/README.md @@ -26,9 +26,9 @@ Do not edit this file. Edit 'docs/templates/README.md.j2' instead and run 'make | OS | Arch | Version | | | ------------ | ------- | --------------------- | ---- | -| macOS (Darwin) | x86_64 | 1.0.3 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) | -| Linux | x86_64 | 1.0.3 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) | -| Linux | aarch64 | 1.0.3 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) | +| macOS (Darwin) | x86_64 | 1.1.0 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) | +| Linux | x86_64 | 1.1.0 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) | +| Linux | aarch64 | 1.1.0 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) | #### macOS :beer: @@ -61,7 +61,6 @@ echo "{{BIND}}:{{PORT | default('443')}} {{NAME}}" | envcat -f j2 -c PORT:?port :bulb: See `envcat --help` for full syntax reference. - ## Templating With `-f j2`, or when called by the name `envtpl`, envcat renders a jinja2 template from _stdin_ to _stdout_. @@ -126,6 +125,74 @@ echo "{% for x in FOO | split(',') %}{{x}}..{% endfor %}" | envtpl FOO # => a.. Envcat uses a [Crystal implementation of the jinja2 template engine](https://straight-shoota.github.io/crinja/). Python expressions are **not** supported. +## Layering data from multiple sources + +By default envcat reads variables only from your shell environment. +With `-i` you can additionally source data from YAML, JSON or TOML files. + +**Example:** + +```bash +# Override an env-var via YAML file +$ export FOO=bar +$ echo "foo: batz" >demo.yaml +$ envcat -i env -i yaml:demo.yaml FOO +{"FOO":"batz"} + +# We can also ignore the environment +# altogether and use only file sources. +$ envcat -i yaml:foo.yaml -i json:bar.json FOO +{"FOO":"batz"} +``` + +With `-s` you can overwrite values directly. + +**Example:** + +```bash +$ export FOO=bar +$ envcat -s FOO=batz HELLO +batz +``` + +`-s` takes precedence over all other data sources. + + +### Input normalization + +envcat flattens the structure of data sourced via `-i` as follows. + +Given the following YAML: + +```yaml +# demo.yaml +employee: + name: Jane Smith + department: HR + contact: + email: jane@example.com + phone: 555-123-4567 + projects: + - Project A + - Project B + skills: + - Skill 1 + - Skill 2 +``` + +`envcat -f yaml -i yaml:demo.yaml '*'` produces the following output: + +```yaml +EMPLOYEE_NAME: Jane Smith +EMPLOYEE_DEPARTMENT: HR +EMPLOYEE_CONTACT_EMAIL: jane@example.com +EMPLOYEE_CONTACT_PHONE: 555-123-4567 +EMPLOYEE_PROJECTS_0: Project A +EMPLOYEE_PROJECTS_1: Project B +EMPLOYEE_SKILLS_0: Skill 1 +EMPLOYEE_SKILLS_1: Skill 2 +``` + ## Checks @@ -156,13 +223,21 @@ For a full list of available SPEC constraints see below. ## Synopsis ``` -Usage: envcat [-f etf|kv|export|j2|j2_unsafe|json|none|yaml] [-c ..] [GLOB[:etf] ..] +Usage: envcat [-i ..] [-s ..] [-c ..] [-f etf|kv|export|j2|j2_unsafe|json|none|yaml] [GLOB[:etf] ..] + -i, --input=SOURCE env|json:PATH|yaml:PATH|toml:PATH (default: env) + -s, --set=KEY=VALUE KEY=VALUE -f, --format=FORMAT etf|export|j2|j2_unsafe|json|kv|none|yaml (default: json) -c, --check=VAR[:SPEC] Check VAR against SPEC. Omit SPEC to check only for presence. -h, --help Show this help --version Print version and exit +SOURCE + env - Shell environment + json:PATH - JSON file at PATH + yaml:PATH - YAML file at PATH + toml:PATH - TOML file at PATH + FORMAT etf Envcat Transport Format export Shell export format @@ -257,6 +332,9 @@ export B=world | 1 | Invalid value (`--check` constraint violation) | | 3 | Syntax error (invalid argument or template) | | 5 | Undefined variable access (e.g. your template contains `{{FOO}}` but $FOO is not set) | +| 7 | I/O Error | +| 11 | Parsing error | +| 255 | Bug (unhandled exception) | ## Contributing diff --git a/docs/templates/README.md.j2 b/docs/templates/README.md.j2 index f73de8e..724271d 100644 --- a/docs/templates/README.md.j2 +++ b/docs/templates/README.md.j2 @@ -64,7 +64,6 @@ echo "{{BIND}}:{{PORT | default('443')}} {{NAME}}" | envcat -f j2 -c PORT:?port :bulb: See `envcat --help` for full syntax reference. - ## Templating With `-f j2`, or when called by the name `envtpl`, envcat renders a jinja2 template from _stdin_ to _stdout_. @@ -129,6 +128,74 @@ echo "{% for x in FOO | split(',') %}{{x}}..{% endfor %}" | envtpl FOO # => a.. Envcat uses a [Crystal implementation of the jinja2 template engine](https://straight-shoota.github.io/crinja/). Python expressions are **not** supported. +## Layering data from multiple sources + +By default envcat reads variables only from your shell environment. +With `-i` you can additionally source data from YAML, JSON or TOML files. + +**Example:** + +```bash +# Override an env-var via YAML file +$ export FOO=bar +$ echo "foo: batz" >demo.yaml +$ envcat -i env -i yaml:demo.yaml FOO +{"FOO":"batz"} + +# We can also ignore the environment +# altogether and use only file sources. +$ envcat -i yaml:foo.yaml -i json:bar.json FOO +{"FOO":"batz"} +``` + +With `-s` you can overwrite values directly. + +**Example:** + +```bash +$ export FOO=bar +$ envcat -s FOO=batz HELLO +batz +``` + +`-s` takes precedence over all other data sources. + + +### Input normalization + +envcat flattens the structure of data sourced via `-i` as follows. + +Given the following YAML: + +```yaml +# demo.yaml +employee: + name: Jane Smith + department: HR + contact: + email: jane@example.com + phone: 555-123-4567 + projects: + - Project A + - Project B + skills: + - Skill 1 + - Skill 2 +``` + +`envcat -f yaml -i yaml:demo.yaml '*'` produces the following output: + +```yaml +EMPLOYEE_NAME: Jane Smith +EMPLOYEE_DEPARTMENT: HR +EMPLOYEE_CONTACT_EMAIL: jane@example.com +EMPLOYEE_CONTACT_PHONE: 555-123-4567 +EMPLOYEE_PROJECTS_0: Project A +EMPLOYEE_PROJECTS_1: Project B +EMPLOYEE_SKILLS_0: Skill 1 +EMPLOYEE_SKILLS_1: Skill 2 +``` + ## Checks @@ -208,6 +275,9 @@ export B=world | 1 | Invalid value (`--check` constraint violation) | | 3 | Syntax error (invalid argument or template) | | 5 | Undefined variable access (e.g. your template contains `{{FOO}}` but $FOO is not set) | +| 7 | I/O Error | +| 11 | Parsing error | +| 255 | Bug (unhandled exception) | ## Contributing