nri-env-parser- Read environment variables as settings to build 12-factor apps.
Safe HaskellNone



A module for reading configuration options from environment variables.

Applications have configuration options. The Twelve-Factor App recommends applications read these from environment variables. This requires us to decode environment variables, which are strings, into the different types the app's configuration options might have. This module helps with that.

Here's what sets this package apart from other environment parsers:

  • Very small API, supporting just one way to do environment parsing.
  • Comes with parsers for common configuration option types, such as URIs. Not using type classes for these parsers means we don't have to write a bunch of orphan instances.
  • Mandatory documentation of each environment variable we want to decode.
  • The decoders keep track of all the environment variables they depend on. That way the decoder for an application can tell us all the environment variables an application depends on and what they are used for.


data Parser a Source #

A function that can read values of a type from text. For example, a Parser Int knows how to read a string like "412" and extract from that the number 412.

Parsing functions can fail when they read a text that they do not understand. For example, the Parser Int parser will fail if ran against the string "Not a number in the slightest!".


Instances details
Functor Parser Source # 
Instance details

Defined in Environment


fmap :: (a -> b) -> Parser a -> Parser b #

(<$) :: a -> Parser b -> Parser a #

text :: Parser Text Source #

Parse a text from an environment variable.

int :: Integral a => Parser a Source #

Parse an integer from an environment variable. Works for any integer type (Integer, Int, Int, ...).

float :: Parser Float Source #

Parse a floating point number from an environment variable.

boolean :: Parser Bool Source #

Parse a boolean from an environment variable.

uri :: Parser URI Source #

Parse a URI from an environment variable.

filePath :: Parser FilePath Source #

Parse a file path from an environment variable.

networkURI :: Parser URI Source #

There's two URI types that are in vogue in the Haskell ecosystem. We would like to standardized on the Text.URI package, since it's the more modern Text based version (no Strings for us!), but most libraries require the other type. This function helps convert.

secret :: Parser a -> Parser (Secret a) Source #

Parse a secret value from an environment variable.

Check the documentation for the Log module of nri-prelude to learn more about secrets.

custom :: Parser a -> (a -> Result Text b) -> Parser b Source #

Create a parser for custom types. Build on the back of one of the primitve parsers from this module.

data Environment = Development | Production

environment :: Parser Environment
environment =
    custom text <| \str ->
        case str of
            "development" -> Ok Development
            "production" -> Ok Production
            _ -> Err ("Unknown environment: " ++ str)


data Decoder config Source #

An environment decoder knows how to read an app's configuration from environment variables. Check out the variable function to see how you can begin building decoders.


Instances details
Functor Decoder Source # 
Instance details

Defined in Environment


fmap :: (a -> b) -> Decoder a -> Decoder b #

(<$) :: a -> Decoder b -> Decoder a #

Applicative Decoder Source # 
Instance details

Defined in Environment


pure :: a -> Decoder a #

(<*>) :: Decoder (a -> b) -> Decoder a -> Decoder b #

liftA2 :: (a -> b -> c) -> Decoder a -> Decoder b -> Decoder c #

(*>) :: Decoder a -> Decoder b -> Decoder b #

(<*) :: Decoder a -> Decoder b -> Decoder a #

consumes :: Decoder config -> [Variable] Source #

The list of Variables that this decoder will read when ran.

data Variable Source #

An environment variable with a description of what it is used for.





Instances details
Show Variable Source # 
Instance details

Defined in Environment

variable :: Variable -> Parser a -> Decoder a Source #

Produce a configuration from a single environment veriable. Usually you will combine these with mapN functions to build larger configurations.

Data Settings = Settings
   { amountOfHats :: Int
   , furLined :: Bool

 (variable (Variable "HATS" "Amount of hats" "2") int)
 (variable (Variable "FUR_LINED" "Do hats have fur lining?" "False") boolean)

either :: Decoder a -> Decoder a -> Decoder a Source #

If the first decoder fails, try the second.

decode :: Decoder a -> IO a Source #

Attempt to decode a configuration by reading environment variables. This will fail if one or more environment variables fail to parse.

It will not fail if certain environment variables are absent. Defaults will be used for those missing values.

decodeDefaults :: Decoder a -> Result Text a Source #

Build a configuration using only default values of environment variables. Similar to decode, except this version doesn't read any environment variables.

This is sometimes useful for tests, where you might not care about the exact values of settings.

decodePairs :: Decoder a -> Dict Text Text -> Result Text a Source #

Same as decode, but takes the environment to decode as a dictionary.

Decoders for just the variables

decodeVariables :: Decoder a -> IO [DecodedVariable] Source #

Run a decoder. Instead of returnin the decoded value return metadata about each variable that was decoded.

This can be helpful when generating a --help command, for listing all the variables that the application supports and what they are currently set to.

decodeVariablePairs :: Decoder a -> Dict Text Text -> [DecodedVariable] Source #

Same as decodeVariables, but takes the environment to decode as a dictionary.

data DecodedVariable Source #

Describe a decoded variable for informational purposes.





Instances details
Show DecodedVariable Source # 
Instance details

Defined in Environment