Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@m-o-e
m-o-e committed Oct 8, 2023
1 parent c552e3c commit b38386b
Show file tree
Hide file tree
Showing 2 changed files with 152 additions and 4 deletions.
86 changes: 82 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -60,6 +60,73 @@ echo "{{BIND}}:{{PORT | default('443')}} {{NAME}}" | envcat -f j2 -c PORT:?port

:bulb: See `envcat --help` for full syntax reference.

## 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"}
```

### Input normalization

envcat flattens and normalizes the structure
of data read from file-sources.

Given the following YAML:

```yaml
# demo.yaml
employee:
name: Jane Smith
department: HR
contact:
email: [email protected]
phone: 555-123-4567
projects:
- Project A
- Project B
skills:
- Skill 1
- Skill 2
```
`envcat -f yaml -i yaml:demo.yaml '*'` will produce the following output:

```yaml
EMPLOYEE_NAME: Jane Smith
EMPLOYEE_DEPARTMENT: HR
EMPLOYEE_CONTACT_EMAIL: [email protected]
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
```

### 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.


## Templating
Expand Down Expand Up @@ -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 <VAR[:SPEC]> ..] [GLOB[:etf] ..]
Usage: envcat [-i <SOURCE> ..] [-s <KEY=VALUE> ..] [-c <VAR[:SPEC]> ..] [-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
Expand Down Expand Up @@ -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

Expand Down
70 changes: 70 additions & 0 deletions docs/templates/README.md.j2
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,73 @@ echo "{{BIND}}:{{PORT | default('443')}} {{NAME}}" | envcat -f j2 -c PORT:?port

:bulb: See `envcat --help` for full syntax reference.

## 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"}
```

### Input normalization

envcat flattens and normalizes the structure
of data read from file-sources.

Given the following YAML:

```yaml
# demo.yaml
employee:
name: Jane Smith
department: HR
contact:
email: [email protected]
phone: 555-123-4567
projects:
- Project A
- Project B
skills:
- Skill 1
- Skill 2
```

`envcat -f yaml -i yaml:demo.yaml '*'` will produce the following output:

```yaml
EMPLOYEE_NAME: Jane Smith
EMPLOYEE_DEPARTMENT: HR
EMPLOYEE_CONTACT_EMAIL: [email protected]
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
```

### 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.


## Templating
Expand Down Expand Up @@ -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

Expand Down

0 comments on commit b38386b

Please sign in to comment.