Environment

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.

Parsers

data Parser a

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

Functor Parser

Defined in Environment

Methods

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

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

text :: Parser Text

Parse a text from an environment variable.

int :: Integral a => Parser a

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

float :: Parser Float

Parse a floating point number from an environment variable.

boolean :: Parser Bool

Parse a boolean from an environment variable.

uri :: Parser URI

Parse a URI from an environment variable.

filePath :: Parser FilePath

Parse a file path from an environment variable.

networkURI :: Parser URI

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)

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

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)

Decoders

data Decoder config

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

Functor Decoder

Defined in Environment

Methods

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

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

Applicative Decoder

Defined in Environment

Methods

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]

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

data Variable

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

Constructors

Variable

Fields

• name :: Text
• description :: Text
• defaultValue :: Text

Instances

Show Variable

Defined in Environment

Methods

showsPrec :: Int -> Variable -> ShowS

show :: Variable -> String

showList :: [Variable] -> ShowS

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

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
   }

map2
 Settings
 (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

If the first decoder fails, try the second.

decode :: Decoder a -> IO a

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

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

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

Decoders for just the variables

decodeVariables :: Decoder a -> IO [DecodedVariable]

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]

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

data DecodedVariable

Describe a decoded variable for informational purposes.

Constructors

DecodedVariable

Fields

• decodedVariable :: Variable
• decodedCurrent :: Maybe Text
• decodedErrors :: List Text

Instances

Show DecodedVariable

Defined in Environment

Methods

showsPrec :: Int -> DecodedVariable -> ShowS

show :: DecodedVariable -> String

showList :: [DecodedVariable] -> ShowS