Skip to content

Commit e9d20fb

Browse files
m-o-em-o-e
committed
Update README
1 parent c552e3c commit e9d20fb

File tree

2 files changed

+154
-6
lines changed

2 files changed

+154
-6
lines changed

‎README.md

+83-5
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,9 @@ Do not edit this file. Edit 'docs/templates/README.md.j2' instead and run 'make
2626

2727
| OS | Arch | Version | |
2828
| ------------ | ------- | --------------------- | ---- |
29-
| macOS (Darwin) | x86_64 | 1.0.3 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) |
30-
| Linux | x86_64 | 1.0.3 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) |
31-
| Linux | aarch64 | 1.0.3 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) |
29+
| macOS (Darwin) | x86_64 | 1.1.0 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) |
30+
| Linux | x86_64 | 1.1.0 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) |
31+
| Linux | aarch64 | 1.1.0 (latest) | [Download](https://github.com/busyloop/envcat/releases/latest) |
3232

3333
#### macOS :beer:
3434

@@ -61,7 +61,6 @@ echo "{{BIND}}:{{PORT | default('443')}} {{NAME}}" | envcat -f j2 -c PORT:?port
6161
:bulb: See `envcat --help` for full syntax reference.
6262

6363

64-
6564
## Templating
6665

6766
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..
126125
Envcat uses a [Crystal implementation of the jinja2 template engine](https://straight-shoota.github.io/crinja/).
127126
Python expressions are **not** supported.
128127

128+
## Layering data from multiple sources
129+
130+
By default envcat reads variables only from your shell environment.
131+
With `-i` you can additionally source data from YAML, JSON or TOML files.
132+
133+
**Example:**
134+
135+
```bash
136+
# Override an env-var via YAML file
137+
$ export FOO=bar
138+
$ echo "foo: batz" >demo.yaml
139+
$ envcat -i env -i yaml:demo.yaml FOO
140+
{"FOO":"batz"}
141+
142+
# We can also ignore the environment
143+
# altogether and use only file sources.
144+
$ envcat -i yaml:foo.yaml -i json:bar.json FOO
145+
{"FOO":"batz"}
146+
```
147+
148+
With `-s` you can overwrite values directly.
149+
150+
**Example:**
151+
152+
```bash
153+
$ export FOO=bar
154+
$ envcat -s FOO=batz HELLO
155+
batz
156+
```
157+
158+
`-s` takes precedence over all other data sources.
159+
160+
161+
### Input normalization
162+
163+
envcat flattens the structure of data sourced via `-i` as follows.
164+
165+
Given the following YAML:
166+
167+
```yaml
168+
# demo.yaml
169+
employee:
170+
name: Jane Smith
171+
department: HR
172+
contact:
173+
email: [email protected]
174+
phone: 555-123-4567
175+
projects:
176+
- Project A
177+
- Project B
178+
skills:
179+
- Skill 1
180+
- Skill 2
181+
```
182+
183+
`envcat -f yaml -i yaml:demo.yaml '*'` produces the following output:
184+
185+
```yaml
186+
EMPLOYEE_NAME: Jane Smith
187+
EMPLOYEE_DEPARTMENT: HR
188+
EMPLOYEE_CONTACT_EMAIL: [email protected]
189+
EMPLOYEE_CONTACT_PHONE: 555-123-4567
190+
EMPLOYEE_PROJECTS_0: Project A
191+
EMPLOYEE_PROJECTS_1: Project B
192+
EMPLOYEE_SKILLS_0: Skill 1
193+
EMPLOYEE_SKILLS_1: Skill 2
194+
```
195+
129196

130197
## Checks
131198

@@ -156,13 +223,21 @@ For a full list of available SPEC constraints see below.
156223
## Synopsis
157224

158225
```
159-
Usage: envcat [-f etf|kv|export|j2|j2_unsafe|json|none|yaml] [-c <VAR[:SPEC]> ..] [GLOB[:etf] ..]
226+
Usage: envcat [-i <SOURCE> ..] [-s <KEY=VALUE> ..] [-c <VAR[:SPEC]> ..] [-f etf|kv|export|j2|j2_unsafe|json|none|yaml] [GLOB[:etf] ..]
160227

228+
-i, --input=SOURCE env|json:PATH|yaml:PATH|toml:PATH (default: env)
229+
-s, --set=KEY=VALUE KEY=VALUE
161230
-f, --format=FORMAT etf|export|j2|j2_unsafe|json|kv|none|yaml (default: json)
162231
-c, --check=VAR[:SPEC] Check VAR against SPEC. Omit SPEC to check only for presence.
163232
-h, --help Show this help
164233
--version Print version and exit
165234

235+
SOURCE
236+
env - Shell environment
237+
json:PATH - JSON file at PATH
238+
yaml:PATH - YAML file at PATH
239+
toml:PATH - TOML file at PATH
240+
166241
FORMAT
167242
etf Envcat Transport Format
168243
export Shell export format
@@ -257,6 +332,9 @@ export B=world
257332
| 1 | Invalid value (`--check` constraint violation) |
258333
| 3 | Syntax error (invalid argument or template) |
259334
| 5 | Undefined variable access (e.g. your template contains `{{FOO}}` but $FOO is not set) |
335+
| 7 | I/O Error |
336+
| 11 | Parsing error |
337+
| 255 | Bug (unhandled exception) |
260338

261339
## Contributing
262340

‎docs/templates/README.md.j2

+71-1
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,6 @@ echo "{{BIND}}:{{PORT | default('443')}} {{NAME}}" | envcat -f j2 -c PORT:?port
6464
:bulb: See `envcat --help` for full syntax reference.
6565

6666

67-
6867
## Templating
6968

7069
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..
129128
Envcat uses a [Crystal implementation of the jinja2 template engine](https://straight-shoota.github.io/crinja/).
130129
Python expressions are **not** supported.
131130

131+
## Layering data from multiple sources
132+
133+
By default envcat reads variables only from your shell environment.
134+
With `-i` you can additionally source data from YAML, JSON or TOML files.
135+
136+
**Example:**
137+
138+
```bash
139+
# Override an env-var via YAML file
140+
$ export FOO=bar
141+
$ echo "foo: batz" >demo.yaml
142+
$ envcat -i env -i yaml:demo.yaml FOO
143+
{"FOO":"batz"}
144+
145+
# We can also ignore the environment
146+
# altogether and use only file sources.
147+
$ envcat -i yaml:foo.yaml -i json:bar.json FOO
148+
{"FOO":"batz"}
149+
```
150+
151+
With `-s` you can overwrite values directly.
152+
153+
**Example:**
154+
155+
```bash
156+
$ export FOO=bar
157+
$ envcat -s FOO=batz HELLO
158+
batz
159+
```
160+
161+
`-s` takes precedence over all other data sources.
162+
163+
164+
### Input normalization
165+
166+
envcat flattens the structure of data sourced via `-i` as follows.
167+
168+
Given the following YAML:
169+
170+
```yaml
171+
# demo.yaml
172+
employee:
173+
name: Jane Smith
174+
department: HR
175+
contact:
176+
email: [email protected]
177+
phone: 555-123-4567
178+
projects:
179+
- Project A
180+
- Project B
181+
skills:
182+
- Skill 1
183+
- Skill 2
184+
```
185+
186+
`envcat -f yaml -i yaml:demo.yaml '*'` produces the following output:
187+
188+
```yaml
189+
EMPLOYEE_NAME: Jane Smith
190+
EMPLOYEE_DEPARTMENT: HR
191+
EMPLOYEE_CONTACT_EMAIL: [email protected]
192+
EMPLOYEE_CONTACT_PHONE: 555-123-4567
193+
EMPLOYEE_PROJECTS_0: Project A
194+
EMPLOYEE_PROJECTS_1: Project B
195+
EMPLOYEE_SKILLS_0: Skill 1
196+
EMPLOYEE_SKILLS_1: Skill 2
197+
```
198+
132199

133200
## Checks
134201

@@ -208,6 +275,9 @@ export B=world
208275
| 1 | Invalid value (`--check` constraint violation) |
209276
| 3 | Syntax error (invalid argument or template) |
210277
| 5 | Undefined variable access (e.g. your template contains `{{FOO}}` but $FOO is not set) |
278+
| 7 | I/O Error |
279+
| 11 | Parsing error |
280+
| 255 | Bug (unhandled exception) |
211281

212282
## Contributing
213283

0 commit comments

Comments
 (0)