dotenv
Loads environment variables from dotenv files
https://github.com/stackbuilders/dotenv-hs
Version on this page: | 0.8.0.7 |
LTS Haskell 22.39: | 0.11.0.2 |
Stackage Nightly 2024-10-31: | 0.12.0.0 |
Latest on Hackage: | 0.12.0.0 |
dotenv-0.8.0.7@sha256:fa500b439396bd0cc2ee83229241cbfa56363dbbe7d5bdb2d43b966ec2f00663,5910
Module documentation for 0.8.0.7
- Configuration
Dotenv files for Haskell
In most applications, configuration should be separated from code. While it usually works well to keep configuration in the environment, there are cases where you may want to store configuration in a file outside of version control.
“Dotenv” files have become popular for storing configuration, especially in development and test environments. In Ruby, Python and Javascript there are libraries to facilitate loading of configuration options from configuration files. This library loads configuration to environment variables for programs written in Haskell.
Installation
In most cases you will just add dotenv
to your cabal file. You can
also install the library and executable by invoking stack install dotenv
or
you can download the dotenv binaries from our
releases page.
Usage
Set configuration variables in a file following the format below:
S3_BUCKET=YOURS3BUCKET
SECRET_KEY=YOURSECRETKEYGOESHERE
Then, calling Dotenv.load
from your Haskell program reads the above
settings into the environment:
import Configuration.Dotenv (loadFile, defaultConfig)
loadFile defaultConfig
After calling Dotenv.load
, you are able to read the values set in your
environment using standard functions from System.Environment
or
System.Environment.Blank
(base
>= 4.11.0.0), such as getEnv
.
If your version of base
is < 4.11.0.0, then setting an environment variable value to
a blank string will remove the variable from the environment entirely.
Variable substitution
In order to use compound env vars use the following sintax within your env vars ${your_env_var}. For instance:
DATABASE=postgres://${USER}@localhost/database
Running it on the CLI:
$ dotenv "echo $DATABASE"
postgres://myusername@localhost/database
Command substitution
In order to use the standard output of a command in your env vars use the following sintax $(your_command). For instance:
DATABASE=postgres://$(whoami)@localhost/database
Running it on the CLI:
$ dotenv "echo $DATABASE"
postgres://myusername@localhost/database
Type checking envs
Env variables are simple strings. However, they can represent other types like integers, booleans, IP addresses, emails, URIs, and so on. We provide an interface that performs type checking after loading the envs and before running your application. If the type-check succeeded the application is executed, otherwise you will get an error with the types that mismatch.
In order to use this functionality you can use the loadSafeFile
which takes the same
configuration value as the loadFile
function. Also, you need to have a .schema.yml
in your current directory. This file must have the following structure:
- name: DOTENV
type: bool
required: true
- name: OTHERENV
type: bool
- name: PORT
type: integer
required: true
- name: TOKEN
type: text
required: false
It is a list of type and envs. So, in this example, DOTENV
must have a value
of true
or false
otherwise it won’t be parsed as a boolean value. And envs
like PORT
must be any integer. Currently, we are supporting the following types:
bool
- Accepts valuesfalse
ortrue
integer
- Accepts values of possitive integerstext
- Any text
require specifies if the env var is obligatory or not. In case you set it to true
but do not provide it, you wil get an exception. When required is omited, the default
value is false
.
NOTE: All the variables which are required in the schema.yml
must be defined
in the dotenvs.
Configuration
The first argument to loadFile
specifies the configuration. You cans use
defaultConfig
which parses the .env
file in your current directory and
doesn’t override your envs. You can also define your own configuration with
the Config
type.
False
in configOverride
means Dotenv will respect
already-defined variables, and True
means Dotenv will overwrite
already-defined variables.
In the configPath
you can write a list of all the dotenv files where are
envs defined (e.g [".env", ".tokens", ".public_keys"]
).
In the configExamplePath
you can write a list of all the dotenv example files
where you can specify which envs must be defined until running a program
(e.g [".env.example", ".tokens.example", ".public_keys.example"]
). If you don’t
need this functionality you can set configExamplePath
to an empty list.
Advanced Dotenv File Syntax
You can add comments to your Dotenv file, on separate lines or after values. Values can be wrapped in single or double quotes. Multi-line values can be specified by wrapping the value in double-quotes, and using the “\n” character to represent newlines.
The spec file is the best place to understand the nuances of Dotenv file parsing.
Command-Line Usage
You can call dotenv from the command line in order to load settings from one or more dotenv file before invoking an executable:
$ dotenv -f mydotenvfile myprogram
The -f
flag is optional, by default it looks for the .env
file in the current
working directory.
$ dotenv myprogram
Aditionally you can pass arguments and flags to the program passed to Dotenv:
$ dotenv -f mydotenvfile myprogram -- --myflag myargument
or:
$ dotenv -f mydotenvfile "myprogram --myflag myargument"
Also, you can use a --example
flag to use dotenv-safe functionality
so that you can have a list of strict envs that should be defined in the environment
or in your dotenv files before the execution of your program. For instance:
$ cat .env.example
DOTENV=
FOO=
BAR=
$ cat .env
DOTENV=123
$ echo $FOO
123
This will fail:
$ dotenv -f .env --example .env.example "myprogram --myflag myargument"
> dotenv: Missing env vars! Please, check (this/these) var(s) (is/are) set: BAR
This will succeed:
$ export BAR=123 # Or you can do something like: "echo 'BAR=123' >> .env"
$ dotenv -f .env --example .env.example "myprogram --myflag myargument"
Hint: The env
program in most Unix-like environments prints out the
current environment settings. By invoking the program env
in place
of myprogram
above you can see what the environment will look like
after evaluating multiple Dotenv files.
The --schema FILE
will get the envs configuration from the FILE
. For instance:
$ cat .env
PORT=123a
$ cat .schema.yml
- name: PORT
required: true
type: integer
running dotenv
will throw:
$ dotenv -s .schema.yml "echo $PORT"
dotenv: 1:4:
unexpected 'a'
expecting digit or end of input
NOTE: The flag can be omited when the .schema.yml
is in the current working
directory. To disable type checking add the flag --no-schema
.
Author
Justin Leitgeb
License
MIT
Copyright
(C) 2015-2020 Stack Builders Inc.
Changes
MASTER
Dotenv 0.8.0.7
- Allow megaparsec-0.9.0.0
Dotenv 0.8.0.6
- Allow optparse-applicative-0.16.0.0
Dotenv 0.8.0.5
- Extend ghc support to 8.8 and 8.10
Dotenv 0.8.0.4
- Fix test fixtures
Dotenv 0.8.0.3
- Add suppport for
megaparsec-8.0.0
Dotenv 0.8.0.2
- Add support for GHC 8.6
Dotenv 0.8.0.1
- Support for
optparse-applicative-0.15
Dotenv 0.8.0.0
- Add
Configuration.Dotenv.Environment
module exporting functions fromSystem.Environment
,System.Environment.Compat
, orSystem.Environment.Blank
, depending onbase
version. - Add support for blank environment variables for
base
>= 4.11.0.0.
Dotenv 0.7.0.0
- Hide helper modules in other-modules
Dotenv 0.6.0.3
- Reexport
defaultConfig
inConfiguration.Dotenv
(thanks to: matsubara0507)
Dotenv 0.6.0.2
- Support for
process-1.6.3.0
Dotenv 0.6.0.1
- Add support for
megaparsec-7.0.1
- Drop support for
GHC 7.8.4
Dotenv 0.6.0.0
- Move
loadSafeFile
toConfiguration.Dotenv
- Export
Configuration.Dotenv.Types
fromConfiguration.Dotenv
- Change
loadSafeFile
signature to accept different types of validators. - Add
type ValidatorMap = Map Text (Text -> Bool)
for custom validations.
Dotenv 0.5.2.5
- Update
exceptions
bounds>= 0.8 && < 0.11
Dotenv 0.5.2.4
- Add error message when there is more than one definition in the Scheme for the same env
Dotenv 0.5.2.3
- Update bounds
exceptions
== 0.9.* - Support
megaparsec
>= 6.4.0
Dotenv 0.5.2.1
- Update documentation for Configuration.Dotenv.Types
Dotenv 0.5.2.0
- Add
loadSafeFile
to typecheck the envs. - Add
(--schema|-s) FILE
flag to thedotenv
CLI tool to enable safe mode. - Add
(--no-schema)
flag to thedotenv
CLI tool to disable safe mode. - Turn safe mode on automatically when the
.schema.yml
file is present. - Make
required
optional in the.schema.yml
.
Dotenv 0.5.1.1
- Allow
.env
empty files
Dotenv 0.5.1.0
- Add support for command substitution on env vars.
Dotenv 0.5.0.2
- Set
.env
file as default file for environment variables. - Add
--version
flag to check the version of dotenv that is in use.
Dotenv 0.5.0.0
- Add dotenv-safe functionality
- Add the
Config
type with options to override env variables, and setting the path for .env and .env.example files. - Changed
loadFile
function to getConfig
with the paths for the .env file and the .env.example file.
Dotenv 0.4.0.0
- Use Megaparsec 6.0
- Dropped support for GHC 7.6
Dotenv 0.3.4.0
- Allow optparse-applicative 0.14
Dotenv 0.3.3.0
- Add support for variable expansion. Thanks to حبيب الامين (GitHub: habibalamin) for making this contribution.
Dotenv 0.3.2.0
- Add the option to pass arguments to the program passed to Dotenv. Thanks to Oleg Grenrus (GitHub: phadej) for making this contribution.
Dotenv 0.3.1.0
-
Made interface more polymorphic so the functions works in any instance of
MonadIO
, not onlyIO
. This should reduce amount of lifting in some cases. -
Added
onMissingFile
helper to deal with possibly missing files. -
Parser was rewritten to take full advantage of Megaparsec.
hspec-megaparsec
is now used for testing of the parser. -
Dropped support for GHC 7.4.
Dotenv 0.3.0.3
- Allow optparse-applicative 0.13
Dotenv 0.3.0.1
- Remove unnecessary package dependencies.
Dotenv 0.3.0.0
- Reverted change to Data.Text in favor of String, for maintaining compatibility with common Haskell system libraries. Added separate interface for parsing a file into tuples containing Data.Text values. Thanks to Daisuke Fujimura (GitHub: fujimura).
- Fixed parsing of CRLF characters for Windows users.
Dotenv 0.2.0.0 (deprecated)
- Changed public interfaces to use Data.Text.
- Added function
parseFile
to read dotenv file without modifying the environment. Thanks to Daisuke Fujimura (GitHub: fujimura) for making this contribution.
Dotenv 0.1.0.0
- First public release.