Like System.Environment's lookupEnv, but using IsString to make it more general.

Lookup an environment variable that exists:

>>> setEnv "TEST_ENV_VAR" "foo"
>>> lookupEnv "TEST_ENV_VAR" :: IO (Maybe String)
Just "foo"

Lookup an environment variable that doesn't exist. Return Nothing:

>>> lookupEnv "THIS_ENV_VAR_WILL_NOT_EXIST" :: IO (Maybe String)
Nothing

Like lookupEnv but take a default value.

Lookup an environment variable that exists:

>>> setEnv "TEST_ENV_VAR" "foo"
>>> lookupEnvDef "TEST_ENV_VAR" "bar" :: IO String
"foo"

Lookup an environment variable that doesn't exist. Return the default value:

>>> lookupEnvDef "THIS_ENV_VAR_WILL_NOT_EXIST" "bar" :: IO String
"bar"

Lookup a value from an environment variable and read it in with readMaybe.

Read an environment variable that exists:

>>> setEnv "TEST_ENV_VAR" "2000"
>>> readEnv "TEST_ENV_VAR" :: IO (Maybe Int)
Just 2000

Try reading an environment variable that does not exist. Returns Nothing:

>>> readEnv "THIS_ENV_VAR_WILL_NOT_EXIST" :: IO (Maybe Int)
Nothing

Try reading an environment variable that cannot be read. Returns Nothing:

>>> setEnv "BAD_ENV_VAR" "not an int"
>>> readEnv "BAD_ENV_VAR" :: IO (Maybe Int)
Nothing

Note that this DOES NOT read string values as one might expect:

>>> setEnv "TEST_ENV_VAR2" "some string 1"
>>> readEnv "TEST_ENV_VAR2" :: IO (Maybe String)
Nothing

It will read string values as if they were Haskell strings:

>>> setEnv "TEST_ENV_VAR3" "\"some string 1\""
>>> readEnv "TEST_ENV_VAR3" :: IO (Maybe String)
Just "some string 1"

Lookup a value from an environment variable and read it in with readMaybe. If the environment variable doesn't exist, or it can't be read, return the default value. Like readEnv but with a default value.

Read an environment variable that exists:

>>> setEnv "TEST_ENV_VAR1" "1000"
>>> readEnvDef "TEST_ENV_VAR1" 5 :: IO Int
1000

Try reading an environment variable that does not exist. Returns the default value:

>>> readEnvDef "THIS_ENV_VAR_WILL_NOT_EXIST" 5 :: IO Int
5

Try reading an environment variable that cannot be read. Returns the default value:

>>> setEnv "BAD_ENV_VAR" "not an int"
>>> readEnvDef "BAD_ENV_VAR" 10 :: IO Int
10

Note that this DOES NOT read string values as one might expect:

>>> setEnv "TEST_ENV_VAR2" "some string 1"
>>> readEnvDef "TEST_ENV_VAR2" "def val" :: IO String
"def val"

It will read string values as if they were Haskell strings:

>>> setEnv "TEST_ENV_VAR3" "\"some string 1\""
>>> readEnvDef "TEST_ENV_VAR3" "def val" :: IO String
"some string 1"

Exception thrown by lookupEnvEx and readEnvEx when the environment variable being read doesn't exist.

Like lookupEnv, but instead of returning a Maybe, throw an EnvVarDoesNotExistException if the environment variable does not exist. The exception is thrown with throwM from MonadThrow.

Lookup an environment variable that exists:

>>> setEnv "TEST_ENV_VAR" "foo"
>>> lookupEnvEx "TEST_ENV_VAR" :: IO String
"foo"

Lookup an environment variable that doesn't exist. Throws EnvVarDoesNotExistException.

>>> lookupEnvEx "THIS_ENV_VAR_WILL_NOT_EXIST" :: IO String
*** Exception: EnvVarDoesNotExistException "THIS_ENV_VAR_WILL_NOT_EXIST"

Lookup a value from an environment variable and read it in with readMaybe. Throw an EnvVarDoesNotExistException if the environment variable does not exist. The exception is thrown with throwM from MonadThrow.

Read an environment variable that exists:

>>> setEnv "TEST_ENV_VAR" "2000"
>>> readEnvEx "TEST_ENV_VAR" :: IO (Maybe Int)
Just 2000

Try reading an environment variable that does not exist. Throws EnvVarDoesNotExistException:

>>> readEnvEx "THIS_ENV_VAR_WILL_NOT_EXIST" :: IO (Maybe Int)
*** Exception: EnvVarDoesNotExistException "THIS_ENV_VAR_WILL_NOT_EXIST"

Try reading an environment variable that cannot be read. Returns Nothing:

>>> setEnv "BAD_ENV_VAR" "not an int"
>>> readEnvEx "BAD_ENV_VAR" :: IO (Maybe Int)
Nothing

Note that this DOES NOT read string values as one might expect:

>>> setEnv "TEST_ENV_VAR2" "some string 1"
>>> readEnvEx "TEST_ENV_VAR2" :: IO (Maybe String)
Nothing

It will read string values as if they were Haskell strings:

>>> setEnv "TEST_ENV_VAR3" "\"some string 1\""
>>> readEnvEx "TEST_ENV_VAR3" :: IO (Maybe String)
Just "some string 1"

Exception thrown by readEnvEx' when the environment variable cannot be read.

Just like readEnvEx, but also throw an exception when the environment variable cannot be read.

This can throw both EnvVarCannotBeReadException and EnvVarDoesNotExistException with throwM.

Read an environment variable that exists:

>>> setEnv "TEST_ENV_VAR" "2000"
>>> readEnvEx' "TEST_ENV_VAR" :: IO Int
2000

Try reading an environment variable that does not exist. Throws EnvVarDoesNotExistException:

>>> readEnvEx' "THIS_ENV_VAR_WILL_NOT_EXIST" :: IO Int
*** Exception: EnvVarDoesNotExistException "THIS_ENV_VAR_WILL_NOT_EXIST"

Try reading an environment variable that cannot be read. Throws EnvVarCannotBeReadException:

>>> setEnv "BAD_ENV_VAR" "not an int"
>>> readEnvEx' "BAD_ENV_VAR" :: IO Int
*** Exception: EnvVarCannotBeReadException "BAD_ENV_VAR"

Note that this DOES NOT read string values as one might expect:

>>> setEnv "TEST_ENV_VAR2" "some string 1"
>>> readEnvEx' "TEST_ENV_VAR2" :: IO String
*** Exception: EnvVarCannotBeReadException "TEST_ENV_VAR2"

It will read string values as if they were Haskell strings:

>>> setEnv "TEST_ENV_VAR3" "\"some string 1\""
>>> readEnvEx' "TEST_ENV_VAR3" :: IO String
"some string 1"

setEnv name value sets the specified environment variable to value.

On Windows setting an environment variable to the empty string removes that environment variable from the environment. For the sake of compatibility we adopt that behavior. In particular

setEnv name ""

has the same effect as

unsetEnv name

If you don't care about Windows support and want to set an environment variable to the empty string use System.Posix.Env.setEnv from the unix package instead.

Throws IOException if name is the empty string or contains an equals sign.

Since: 4.7.0.0