https://github.com/jirutka/yaml-env-tag
Custom YAML tag for referring environment variables in YAML documents
https://github.com/jirutka/yaml-env-tag
psych ruby yaml yaml-tag
Last synced: 9 months ago
JSON representation
Custom YAML tag for referring environment variables in YAML documents
- Host: GitHub
- URL: https://github.com/jirutka/yaml-env-tag
- Owner: jirutka
- License: mit
- Created: 2017-12-04T19:39:34.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2022-09-28T00:54:52.000Z (over 3 years ago)
- Last Synced: 2025-09-15T06:49:16.847Z (9 months ago)
- Topics: psych, ruby, yaml, yaml-tag
- Language: Ruby
- Homepage:
- Size: 19.5 KB
- Stars: 4
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= YAML !ENV Tag
Jakub Jirutka
// custom
:gem-name: yaml-env-tag
:gh-name: jirutka/{gem-name}
:gh-branch: master
:codacy-id: d1b32c16409c46a0b81882a679713a67
ifdef::env-github[]
image:https://github.com/{gh-name}/workflows/CI/badge.svg[CI Status, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22]
image:https://api.codacy.com/project/badge/Coverage/{codacy-id}["Test Coverage", link="https://www.codacy.com/app/{gh-name}"]
image:https://api.codacy.com/project/badge/Grade/{codacy-id}["Codacy Code quality", link="https://www.codacy.com/app/{gh-name}"]
image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link="https://rubygems.org/gems/{gem-name}"]
endif::env-github[]
A custom YAML tag for referring environment variables in YAML files.
No need to use ERB in YAML just to set some keys from environment variables.
[source, yaml]
.*Sample YAML file using !ENV tag*
oauth:
base_uri: !ENV API_BASE_URI
client_id: !ENV [API_CLIENT_ID, "demo"]
client_secret: !ENV [API_CLIENT_SECRET, API_CLIENT_KEY, ~]
== Usage
Just require `{gem-name}` and load YAML as you’re used to:
[source, rb, subs="+attributes"]
----
require '{gem-name}'
yaml = YAML.safe_load('secret: !ENV API_CLIENT_SECRET', permitted_classes: [YamlEnvTag::EnvVariable])
yaml['secret'] # => "top-secret"
----
*Note:* Since Ruby 3.1, `YAML.load` is an alias for `YAML.safe_load`, which means you have to explicitly whitelist the `YamlEnvTag::EnvVariable` class (see keyword argument `permitted_classes`).
Analogously, `YAML.load_file` became an alias for `YAML.safe_load_file`.
Also keep in mind that the _safe_ variant disables aliases (anchors); you can enable them by setting the `aliases` parameter to `true` (e.g. `YAML.safe_load(..., aliases: true)`).
For compatibility with older Ruby versions, it’s better to always use `YAML.safe_load` and `YAML.safe_load_file`.
=== Single Required Variable
Specify one environment variable as a `!ENV` tagged scalar.
If it does not exist (is not set), `YAML.load` (and other load methods) will raise `YamlEnvTag::MissingEnvVariableError`.
[source, yaml]
!ENV SOME_VARIABLE
This can be also written as a tagged sequence `!ENV [SOME_VARIABLE]` or `!ENV [SOME_VARIABLE, ~]`, all three variants are equivalent.
=== Default Value
You can define a default value that is used when the specified environment variable does not exist.
This makes the variable optional.
Default value is the last element of a `!ENV` tagged sequence (array) with more than one element.
[source, yaml]
!ENV [SOME_VARIABLE, "default value"]
=== Multiple Variables (Fallbacks)
You may also specify more environment variables in a `!ENV` tagged sequence (array) – the first one that does exist is used.
Keep in mind that the last element of a multi-element sequence is always interpreted as a default value, not a name of environment variable!
[source, yaml]
!ENV [SOME_VARIABLE, LEGACY_VARIABLE, "default value"]
If you want to raise an exception when none of the specified environment variables exist, use `~` (nil) as the last element:
[source, yaml]
!ENV [SOME_VARIABLE, LEGACY_VARIABLE, ~]
== License
This project is licensed under http://opensource.org/licenses/MIT/[MIT License].
For the full text of the license, see the link:LICENSE[LICENSE] file.