View Source Enviable (Enviable v1.0.1)
- code :: https://github.com/halostatue/enviable
- issues :: https://github.com/halostatue/enviable/issues
Enviable is a small collection of functions and delegates that makes working with operating system environment functions a little easier. It exists for two reasons:
Functions like
Enviable.put_env_new/2
do not exist inSystem
and are easier to read than eitherSystem.put_env/2
orSystem.put_env/1
in conjunction withSystem.get_env/2
.Modules in dependencies can reliably be used or
include
d in configuration files in ways that in-source functions cannot be.
Delegates are defined for System.delete_env/1
, System.fetch_env/1
,
System.fetch_env!/1
, System.get_env/0
, System.get_env/2
,
System.put_env/1
, and System.put_env/2
.
Usage
This will typically be used in config/*.exs
files alongside Dotenvy
or similar configuration tools based around environment variables.
# config/runtime.exs
include Config
include Enviable
client = fetch_env!("CLIENT")
Dotenvy.source([".env", ".env.#{client}", System.get_env()])
config :my_app,
key: fetch_env!("SECRET_KEY"),
port: fetch_env_integer!("PORT"),
ssl: fetch_env_boolean!("SSL_ENABLED")
# config/dev.exs
include Config
Enviable.put_env_new("SSL_ENABLED", false)
Installation
Enviable can be installed by adding enviable
to your list of dependencies in
mix.exs
:
def deps do
[
{:enviable, "~> 0.1.0"}
]
end
Documentation is found on HexDocs.
Semantic Versioning
Enviable
uses a Semantic Versioning scheme with one significant
change:
- When PATCH is zero (
0
), it will be omitted from version references.
Summary
Functions
Deletes an environment variable, removing varname
from the environment.
Returns the value of the given environment variable or :error if not found.
Returns the value of the given environment variable or raises if not found.
Returns the value of an environment variable as {:ok, t:boolean/0}
value or :error
if the variable is unset.
Returns the value of an environment variable as a boolean/0
value or raises an
exception if the variable is unset.
Returns the value of an environment variable as {:ok, t:integer/0}
or :error
if the
variable is unset.
Returns the value of an environment variable as a integer/0
value or nil
if the
variable is not set and a default
is not provided.
Returns all system environment variables.
Returns the value of the given environment variable.
Returns the value of an environment variable as a boolean/0
value.
Returns the value of an environment variable as a integer/0
value or nil
if the
variable is not set and a default
is not provided.
Sets multiple environment variables.
Sets an environment variable value.
Set an environment variable value only if it is not yet set.
Functions
@spec delete_env(String.t()) :: :ok
Deletes an environment variable, removing varname
from the environment.
Returns the value of the given environment variable or :error if not found.
If the environment variable varname is set, then {:ok, value} is returned where value is a string. If varname is not set, :error is returned.
Examples
iex> Enviable.fetch_env("PORT")
:error
iex> Enviable.put_env("PORT", "4000")
iex> Enviable.fetch_env("PORT")
{:ok, "4000"}
Returns the value of the given environment variable or raises if not found.
Same as get_env/1
but raises instead of returning nil
when the variable is
not set.
Examples
iex> Enviable.fetch_env!("PORT")
** (System.EnvError) could not fetch environment variable "PORT" because it is not set
iex> Enviable.put_env("PORT", "4000")
iex> Enviable.fetch_env!("PORT")
"4000"
Returns the value of an environment variable as {:ok, t:boolean/0}
value or :error
if the variable is unset.
By default, the values "1"
and "true"
are considered true
values. Any other value
will be considered false
.
This function accepts the following conversion options:
truthy
: a list of string values to be compared for truth values. Mutually exclusive withfalsy
.falsy
: a list of string values to be compared for false values. Mutually exclusive withtruthy
.downcase
: eitherfalse
(the default),true
, or the mode parameter forString.downcase/2
(:default
,:ascii
,:greek
, or:turkic
).
Examples
iex> Enviable.fetch_env_boolean("COLOR")
:error
iex> Enviable.put_env("COLOR", "1")
iex> Enviable.fetch_env_boolean("COLOR")
{:ok, true}
iex> Enviable.put_env("COLOR", "something")
iex> Enviable.fetch_env_boolean("COLOR")
{:ok, false}
iex> Enviable.put_env("COLOR", "oui")
iex> Enviable.fetch_env_boolean("COLOR", truthy: ["oui"])
{:ok, true}
iex> Enviable.put_env("COLOR", "OUI")
iex> Enviable.fetch_env_boolean("COLOR", truthy: ["oui"])
{:ok, false}
iex> Enviable.fetch_env_boolean("COLOR", truthy: ["oui"], downcase: true)
{:ok, true}
iex> Enviable.put_env("COLOR", "NON")
iex> Enviable.fetch_env_boolean("COLOR", falsy: ["non"])
{:ok, true}
iex> Enviable.fetch_env_boolean("COLOR", falsy: ["non"], downcase: true)
{:ok, false}
# Any `default` value is ignored.
iex> Enviable.fetch_env_boolean("COLOR", default: nil)
:error
iex> Enviable.fetch_env_boolean("COLOR", downcase: nil)
** (ArgumentError) cannot execute Enviable.fetch_env_boolean/2 with invalid `downcase` value
iex> Enviable.fetch_env_boolean("COLOR", truthy: ["oui"], falsy: ["non"])
** (ArgumentError) cannot execute Enviable.fetch_env_boolean/2 with both `truthy` and `falsy` options
Returns the value of an environment variable as a boolean/0
value or raises an
exception if the variable is unset.
By default, the values "1"
and "true"
are considered true
values. Any other value
will be considered false
.
This function accepts the following conversion options:
truthy
: a list of string values to be compared for truth values. Mutually exclusive withfalsy
.falsy
: a list of string values to be compared for false values. Mutually exclusive withtruthy
.downcase
: eitherfalse
(the default),true
, or the mode parameter forString.downcase/2
(:default
,:ascii
,:greek
, or:turkic
).
Examples
iex> Enviable.fetch_env_boolean!("COLOR")
** (System.EnvError) could not fetch environment variable "COLOR" because it is not set
iex> Enviable.put_env("COLOR", "1")
iex> Enviable.fetch_env_boolean!("COLOR")
true
iex> Enviable.put_env("COLOR", "something")
iex> Enviable.fetch_env_boolean!("COLOR")
false
iex> Enviable.put_env("COLOR", "oui")
iex> Enviable.fetch_env_boolean!("COLOR", truthy: ["oui"])
true
iex> Enviable.put_env("COLOR", "OUI")
iex> Enviable.fetch_env_boolean!("COLOR", truthy: ["oui"])
false
iex> Enviable.fetch_env_boolean!("COLOR", truthy: ["oui"], downcase: true)
true
iex> Enviable.put_env("COLOR", "NON")
iex> Enviable.fetch_env_boolean!("COLOR", falsy: ["non"])
true
iex> Enviable.fetch_env_boolean!("COLOR", falsy: ["non"], downcase: true)
false
# Any `default` value is ignored.
iex> Enviable.fetch_env_boolean!("COLOR", default: nil)
** (System.EnvError) could not fetch environment variable "COLOR" because it is not set
iex> Enviable.fetch_env_boolean!("COLOR", downcase: nil)
** (ArgumentError) cannot execute Enviable.fetch_env_boolean!/2 with invalid `downcase` value
iex> Enviable.fetch_env_boolean!("COLOR", truthy: ["oui"], falsy: ["non"])
** (ArgumentError) cannot execute Enviable.fetch_env_boolean!/2 with both `truthy` and `falsy` options
Returns the value of an environment variable as {:ok, t:integer/0}
or :error
if the
variable is unset.
This function accepts the following conversion option:
base
: The base (2..36
) for integer conversion. Defaults to10
likeString.to_integer/2
.
Failure to parse the value of the environment variable will result in an exception.
Examples
iex> Enviable.fetch_env_integer("COLOR")
:error
iex> Enviable.put_env("COLOR", "1")
iex> Enviable.fetch_env_integer("COLOR")
{:ok, 1}
iex> Enviable.put_env("COLOR", "ff")
iex> Enviable.fetch_env_integer("COLOR")
:error
iex> Enviable.put_env("COLOR", "ff")
iex> Enviable.fetch_env_integer("COLOR", base: 16)
{:ok, 255}
Returns the value of an environment variable as a integer/0
value or nil
if the
variable is not set and a default
is not provided.
This function accepts the following conversion options:
base
: The base (2..36
) for integer conversion. Defaults to10
likeString.to_integer/2
.default
: the default value, which must be either a binary string value or an integer. If provided as a binary, this will be interpreted according to thebase
option provided.
Failure to parse a binary string default
or the value of the environment variable will
result in an exception.
Examples
iex> Enviable.fetch_env_integer!("COLOR")
** (System.EnvError) could not fetch environment variable "COLOR" because it is not set
iex> Enviable.put_env("COLOR", "1")
iex> Enviable.fetch_env_integer!("COLOR")
1
iex> Enviable.put_env("COLOR", "ff")
iex> Enviable.fetch_env_integer!("COLOR")
** (Enviable.ConversionError) could not convert environment variable "COLOR" to type integer
iex> Enviable.put_env("COLOR", "ff")
iex> Enviable.fetch_env_integer!("COLOR", base: 16)
255
Returns all system environment variables.
The returned value is a map containing name-value pairs. Variable names and their values are strings.
Returns the value of the given environment variable.
The returned value of the environment variable
varname
is a string. If the environment variable
is not set, returns the string specified in default
or
nil
if none is specified.
Examples
iex> Enviable.get_env("PORT")
nil
iex> Enviable.get_env("PORT", "4001")
"4001"
iex> Enviable.put_env("PORT", "4000")
iex> Enviable.get_env("PORT")
"4000"
iex> Enviable.get_env("PORT", "4001")
"4000"
Returns the value of an environment variable as a boolean/0
value.
By default, the values "1"
and "true"
are considered true
values. Any other value,
including unset variable, will be considered false
.
This function accepts the following conversion options:
truthy
: a list of string values to be compared for truth values. Mutually exclusive withfalsy
.falsy
: a list of string values to be compared for false values. Mutually exclusive withtruthy
.downcase
: eitherfalse
(the default),true
, or the mode parameter forString.downcase/2
(:default
,:ascii
,:greek
, or:turkic
).default
: the default value (which must betrue
orfalse
) if the variable is unset. In most cases, whenfalsy
is provided,default: true
should also be provided.
Examples
iex> Enviable.get_env_boolean("COLOR")
false
iex> Enviable.get_env_boolean("COLOR", default: true)
true
iex> Enviable.put_env("COLOR", "1")
iex> Enviable.get_env_boolean("COLOR")
true
iex> Enviable.put_env("COLOR", "something")
iex> Enviable.get_env_boolean("COLOR")
false
iex> Enviable.put_env("COLOR", "oui")
iex> Enviable.get_env_boolean("COLOR", truthy: ["oui"])
true
iex> Enviable.put_env("COLOR", "OUI")
iex> Enviable.get_env_boolean("COLOR", truthy: ["oui"])
false
iex> Enviable.get_env_boolean("COLOR", truthy: ["oui"], downcase: true)
true
iex> Enviable.put_env("COLOR", "NON")
iex> Enviable.get_env_boolean("COLOR", falsy: ["non"])
true
iex> Enviable.get_env_boolean("COLOR", falsy: ["non"], downcase: true)
false
iex> Enviable.get_env_boolean("COLOR", default: nil)
** (ArgumentError) cannot execute Enviable.get_env_boolean/2 with non-boolean `default` value
iex> Enviable.get_env_boolean("COLOR", downcase: nil)
** (ArgumentError) cannot execute Enviable.get_env_boolean/2 with invalid `downcase` value
iex> Enviable.get_env_boolean("COLOR", truthy: ["oui"], falsy: ["non"])
** (ArgumentError) cannot execute Enviable.get_env_boolean/2 with both `truthy` and `falsy` options
Returns the value of an environment variable as a integer/0
value or nil
if the
variable is not set and a default
is not provided.
This function accepts the following conversion options:
base
: The base (2..36
) for integer conversion. Defaults to10
likeString.to_integer/2
.default
: the default value, which must be either a binary string value or an integer. If provided as a binary, this will be interpreted according to thebase
option provided.
Failure to parse a binary string default
or the value of the environment variable will
result in an exception.
Examples
iex> Enviable.get_env_integer("COLOR")
nil
iex> Enviable.get_env_integer("COLOR", default: 255)
255
iex> Enviable.get_env_integer("COLOR", default: "255")
255
iex> Enviable.get_env_integer("COLOR", default: 3.5)
** (ArgumentError) cannot execute Enviable.get_env_integer/2 with non-integer `default` value
iex> Enviable.put_env("COLOR", "1")
iex> Enviable.get_env_integer("COLOR")
1
iex> Enviable.put_env("COLOR", "ff")
iex> Enviable.get_env_integer("COLOR")
** (Enviable.ConversionError) could not convert environment variable "COLOR" to type integer
iex> Enviable.put_env("COLOR", "ff")
iex> Enviable.get_env_integer("COLOR", base: 16)
255
@spec put_env(Enumerable.t()) :: :ok
Sets multiple environment variables.
Sets a new value for each environment variable corresponding
to each {key, value}
pair in enum
. Keys and non-nil values
are automatically converted to charlists. nil
values erase
the given keys.
Overall, this is a convenience wrapper around put_env/2
and
delete_env/2
with support for different key and value formats.
Sets an environment variable value.
Sets a new value
for the environment variable varname
.
Set an environment variable value only if it is not yet set.
Examples
iex> Enviable.put_env_new("PORT", "3000")
:ok
iex> Enviable.get_env("PORT")
"3000"
iex> Enviable.put_env_new("PORT", "5000")
:ok
iex> Enviable.get_env("PORT")
"3000"