yaml-env-tag

= YAML !ENV Tag Jakub Jirutka https://github.com/jirutka // custom :gem-name: yaml-env-tag :gh-name: jirutka/{gem-name} :gh-branch: master :codacy-id: d1b32c16409c46a0b81882a679713a67

ifdef::env-github[] image:https://travis-ci.org/{gh-name}.svg?branch={gh-branch}[Build Status, link="https://travis-ci.org/{gh-name}"] 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.load('secret: ENV! API_CLIENT_SECRET') yaml['secret'] # => "top-secret"

However, if you use YAML.safe_load (which is highly recommended), you need to explicitly whitelist YamlEnvTag::EnvVariable:

[source, rb] YAML.safe_load(..., [YamlEnvTag::EnvVariable])

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