envy
An environmentally friendly way to deal with environment variables
Version on this page: | 2.1.2.0 |
LTS Haskell 22.33: | 2.1.3.0 |
Stackage Nightly 2024-09-07: | 2.1.3.0 |
Latest on Hackage: | 2.1.3.0 |
envy-2.1.2.0@sha256:831a8dc0db2b9dca9671dc757af0d75d81579d4bc7edc9f4d275ffd67df750bb,1743
Module documentation for 2.1.2.0
- System
envy
Let’s face it, dealing with environment variables in Haskell isn’t that satisfying.
import System.Environment
import Data.Text (pack)
import Text.Read (readMaybe)
data ConnectInfo = ConnectInfo {
pgPort :: Int
pgURL :: Text
} deriving (Show, Eq)
getPGPort :: IO ConnectInfo
getPGPort = do
portResult <- lookupEnv "PG_PORT"
urlResult <- lookupEnv "PG_URL"
case (portResult, urlResult) of
(Just port, Just url) ->
case readMaybe port :: Maybe Int of
Nothing -> error "PG_PORT isn't a number"
Just portNum -> return $ ConnectInfo portNum (pack url)
(Nothing, _) -> error "Couldn't find PG_PORT"
(_, Nothing) -> error "Couldn't find PG_URL"
-- Pretty gross right...
Another attempt to remedy the lookup madness is with a MaybeT IO a
. See below.
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
import Control.Applicative
import Control.Monad.Trans.Maybe
import Control.Monad.IO.Class
import System.Environment
newtype Env a = Env { unEnv :: MaybeT IO a }
deriving (Functor, Applicative, Monad, MonadIO, Alternative, MonadPlus)
getEnv :: Env a -> IO (Maybe a)
getEnv env = runMaybeT (unEnv env)
env :: String -> Env a
env key = Env (MaybeT (lookupEnv key))
connectInfo :: Env ConnectInfo
connectInfo = ConnectInfo
<$> env "PG_HOST"
<*> env "PG_PORT"
<*> env "PG_USER"
<*> env "PG_PASS"
<*> env "PG_DB"
This abstraction falls short in two areas:
- Lookups don’t return any information when a variable doesn’t exist (just a
Nothing
) - Lookups don’t attempt to parse the returned type into something meaningful (everything is returned as a
String
becauselookupEnv :: String -> IO (Maybe String)
)
What if we could apply aeson’s FromJSON
/ ToJSON
pattern to give us variable lookups that provide both key-lookup and parse failure information?
Armed with the GeneralizedNewTypeDeriving
extension we can derive instances of Var
that will parse to and from an environment variable. The Var
typeclass is simply:
class Var a where
toVar :: a -> String
fromVar :: String -> Maybe a
With instances for most concrete and primitive types supported (Word8
- Word64
, Int
, Integer
, String
, Text
, etc.) the Var
class is easily deriveable. The FromEnv
typeclass provides a parser type that is an instance of MonadError String
and MonadIO
. This allows for connection pool initialization inside of our environment parser and custom error handling. The ToEnv
class allows us to create an environment configuration given any a
. See below for an example.
{-# LANGUAGE ScopedTypeVariables #-}
{-# LANGUAGE RecordWildCards #-}
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE DeriveDataTypeable #-}
------------------------------------------------------------------------------
module Main ( main ) where
------------------------------------------------------------------------------
import Control.Applicative
import Control.Exception
import Control.Monad
import Data.Either
import Data.Word
import System.Environment
import System.Envy
------------------------------------------------------------------------------
data ConnectInfo = ConnectInfo {
pgHost :: String
, pgPort :: Word16
, pgUser :: String
, pgPass :: String
, pgDB :: String
} deriving (Show)
------------------------------------------------------------------------------
-- | FromEnv instances support popular aeson combinators *and* IO
-- for dealing with connection pool initialization. `env` is equivalent to (.:) in `aeson`
-- and `envMaybe` is equivalent to (.:?), except here the lookups are impure.
instance FromEnv ConnectInfo where
fromEnv _ =
ConnectInfo <$> envMaybe "PG_HOST" .!= "localhost"
<*> env "PG_PORT"
<*> env "PG_USER"
<*> env "PG_PASS"
<*> env "PG_DB"
------------------------------------------------------------------------------
-- | To Environment Instances
-- (.=) is a smart constructor for producing types of `EnvVar` (which ensures
-- that Strings are set properly in an environment so they can be parsed properly
instance ToEnv ConnectInfo where
toEnv ConnectInfo {..} = makeEnv
[ "PG_HOST" .= pgHost
, "PG_PORT" .= pgPort
, "PG_USER" .= pgUser
, "PG_PASS" .= pgPass
, "PG_DB" .= pgDB
]
------------------------------------------------------------------------------
-- | Example
main :: IO ()
main = do
setEnvironment (toEnv :: EnvList ConnectInfo)
print =<< do decodeEnv :: IO (Either String ConnectInfo)
-- unsetEnvironment (toEnv :: EnvList ConnectInfo) -- remove when done
Our parser might also make use a set of an optional default values provided by the user, for dealing with errors when reading from the environment
instance FromEnv ConnectInfo where
fromEnv Nothing =
ConnectInfo <$> envMaybe "PG_HOST" .!= "localhost"
<*> env "PG_PORT"
<*> env "PG_USER"
<*> env "PG_PASS"
<*> env "PG_DB"
fromEnv (Just def) =
ConnectInfo <$> envMaybe "PG_HOST" .!= (pgHost def)
<*> envMaybe "PG_PORT" .!= (pgPort def)
<*> env "PG_USER" .!= (pgUser def)
<*> env "PG_PASS" .!= (pgPass def)
<*> env "PG_DB" .!= (pgDB def)
Note: As of base 4.7 setEnv
and getEnv
throw an IOException
if a =
is present in an environment. envy
catches these synchronous exceptions and delivers them
purely to the end user.
Generics
As of version 1.0
, all FromEnv
instance boilerplate can be completely removed thanks to GHC.Generics
! Below is an example.
{-# LANGUAGE DeriveGeneric #-}
module Main where
import System.Envy
import GHC.Generics
import System.Environment.Blank
-- This record corresponds to our environment, where the field names become the variable names, and the values the environment variable value
data PGConfig = PGConfig {
pgHost :: String -- "PG_HOST"
, pgPort :: Int -- "PG_PORT"
} deriving (Generic, Show)
instance FromEnv PGConfig
-- Generically creates instance for retrieving environment variables (PG_HOST, PG_PORT)
main :: IO ()
main = do
_ <- setEnv "PG_HOST" "valueFromEnv" True
_ <- setEnv "PG_PORT" "66354651" True
print =<< do decodeEnv :: IO (Either String PGConfig)
-- > PGConfig { pgHost = "valueFromEnv", pgPort = 66354651 }
If the variables are not found in the environment, the parser will currently fail with an error about the first missing field.
The user can decide to provide a default value, whose fields will be used by the generic instance, if retrieving them from the environment fails.
defConfig :: PGConfig
defConfig = PGConfig "localhost" 5432
main :: IO ()
main =
_ <- setEnv "PG_HOST" "customURL" True
print =<< decodeWithDefaults defConfig :: IO (Either String PGConfig)
-- > PGConfig { pgHost = "customURL", pgPort = 5432 }
Suppose you’d like to customize the field name (i.e. add your own prefix, or drop the existing record prefix). This too is possible. See below.
{-# LANGUAGE DeriveGeneric #-}
module Main where
import System.Envy
import GHC.Generics
data PGConfig = PGConfig {
connectHost :: String -- "PG_HOST"
, connectPort :: Int -- "PG_PORT"
} deriving (Generic, Show)
instance DefConfig PGConfig where
defConfig = PGConfig "localhost" 5432
-- All fields will be converted to uppercase
instance FromEnv PGConfig where
fromEnv = gFromEnvCustom Option {
dropPrefixCount = 7
, customPrefix = "CUSTOM"
}
main :: IO ()
main =
_ <- setEnv "CUSTOM_HOST" "customUrl" True
print =<< do decodeEnv :: IO (Either String PGConfig)
-- PGConfig { pgHost = "customUrl", pgPort = 5432 }
It’s also possible to avoid typeclasses altogether using runEnv
with gFromEnvCustom
.
{-# LANGUAGE DeriveGeneric #-}
module Main where
import System.Envy
import GHC.Generics
data PGConfig = PGConfig {
pgHost :: String -- "PG_HOST"
, pgPort :: Int -- "PG_PORT"
} deriving (Generic, Show)
-- All fields will be converted to uppercase
getPGEnv :: IO (Either String PGConfig)
getPGEnv = runEnv $ gFromEnvCustom defOption
(Just (PGConfig "localhost" 5432))
main :: IO ()
main = print =<< getPGEnv
-- PGConfig { pgHost = "localhost", pgPort = 5432 }