EVP: Environment Variable Parser

[ bsd3, library, system ] [ Propose Tags ]

See README.md


[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0, 0.1
Change log CHANGELOG.md
Dependencies base (>=4.16), containers, data-default-class, text, yaml [details]
License BSD-3-Clause
Copyright Copyright (c) 2023 Fumiaki Kinoshita
Author Fumiaki Kinoshita
Maintainer fumiexcel@gmail.com
Category System
Home page https://github.com/fumieval/EVP
Source repo head: git clone https://github.com/fumieval/EVP.git
Uploaded by FumiakiKinoshita at 2023-11-30T05:46:42Z
Distributions
Downloads 34 total (10 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2023-11-30 [all 1 reports]

Readme for EVP-0.1

[back to package description]

EVP: Environment Variable Parser

EVP is a simple environment parser which focues on these three aspects:

  • Ease of use: no complicated machinery is needed
  • Observability: for each environment variable, EVP logs the parsed value or an error. An error does not interrupt the parsing process and it checks all the variables exhaustively.
  • Composability: environment parsers can be composed via the Applicative structure.

Example

The following code is a complete example demonstrating how to use EVP:

{-# LANGUAGE ApplicativeDo #-}
{-# LANGUAGE OverloadedStrings #-}

import EVP qualified

main :: IO ()
main = EVP.scan parser

-- ApplicativeDo is important here because Scan is not a monad.
parser :: EVP.Scan ()
parser = do
    -- @secret@ masks the parsed value
    _token <- EVP.secret $ EVP.string "API_TOKEN"
    -- parse the environment variable as a YAML value
    _port <- EVP.yaml "HTTP_PORT"
    -- obtain the environment variable as is
    _foo <- EVP.string "FOO"
    -- you can also provide a default value
    _debug <- EVP.yaml $ "DEBUG_MODE" `EVP.defaultsTo` False
    pure ()

Running this code produces the following output.

[EVP Info] API_TOKEN: <REDACTED>
[EVP Info] HTTP_PORT: 8080
[EVP Info] FOO: foo
[EVP Info] DEBUG_MODE: False (default)

Revealing unused variables

EVP has a mechanism to detect unused variables.

If your application's environment variables has a common prefix MYAPP_, you can set assumePrefix as a unusedLogger.

EVP.scanWith EVP.def
    { EVP.unusedLogger = EVP.assumePrefix "MYAPP_" }
    parser

If an environment variable prefixed by MYAPP_ is set but not referred to, EVP prints the following warning. This is useful for detecting typos too.

[EVP Warn] MYAPP_OBSOLETE_FLAG is set but not used

Alternatively, you can also name unwanted variables individually:

EVP.scanWith EVP.def
    { EVP.unusedLogger = EVP.obsolete ["OBSOLETE_VAR"] }

These can be combined using the Semigroup instance.

EVP.scanWith EVP.def
    { EVP.unusedLogger = EVP.assumePrefix "MYAPP_" <> EVP.obsolete ["OBSOLETE_VAR"] }
    parser

Parser group

You can provide an additional context to a parser by applying group "group name". Group names appear in the log messages:

[EVP Info] DEBUG_MODE: False (default)
[EVP Info/MySQL] MYSQL_HOST: localhost
[EVP Info/MySQL] MYSQL_PASSWORD: <REDACTED>
[EVP Error/MySQL] Failed to parse MYSQL_PORT=blah: Aeson exception:
[EVP Error/MySQL] Error in $: parsing Int failed, expected Number, but encountered String

Design context

  • If Scan were a monad, the parsing process would be non-deterministic. This might cause a burden when there are two or more problems in the environment variables, because it is not possible to reveal all problems in a non-deterministic context.
  • It is recommended to avoid falling back to default values expect for debugging features. If the application configuration has an error such as a typo, it is much safer to exit than launching anyway with a default value.