README.md

RichEnv

Rich environment variable setup for Haskell

This package exposes a type that captures a set of rules that modify an existing environment variable set, be it a provided list of key-value pairs (list of tuples) or the system's environment variable set.

Each rule can be either a prefix, a mapping or a value. Prefixes take environment variable names and prepend a prefix to them, replacing existing prefixes (i.e. fist removing old prefix, then adding the new one) if desired. Mappings replace the name of the environment variable with a different one, and values create the environment variable with the provided value.

Getting started

The idea behind this library is that you can find a set of rules for setting environment variables that may or may not use the current environment as starting stage, to replace the ones in the current process or pass a custom env to System.Process.CreateProcess to spawn some sub-process.

If your application uses a configuration file, for example in YAML format, you could add a new field to your config like this:

# example.yaml
env:
  values:
    VERBOSE: "true"
  mappings:
    NEWNAME: OLDNAME
  prefixes:
    NEW_PREFIX_:
      - PREFIXED_
      - OTHER_PREFIXED_
    OTHER_NEW_PREFIX_: [OTHER_PREFIXED_]
# More configs ...

When parsing this new env field as the RichEnv type (it provides FromJSON/ToJSON instances), this defines a set of rules:

• values: these are simple environment variable definitions with a value (in textual format).
• mappings: these will create new environment variables from existing environment variables on an 1-1 basis. In the YAML config above, a NEWNAME var will be created with the contents of the OLDNAME var.
• prefixes: these will create new environment variables from existing environment variable by prefix substitution. In the example, environment variables with the prefixes OLD_PREFIX_* and OTHER_OLD_PREFIX_* will all be stripped of the prefix and created with the NEW_PREFIX_* instead.

Thus, after parsing, you will end up with a set of environment variables that you can:

• Apply to an externally provided list of environment variables and values and then apply the result them to the current process with functions like setRichEnv.
• Generate an environment variable list of type [(Text, Text)] with toEnvList.
• Generate a [(String, String)] (with something like fromEnvironment . toEnvList) to pass to System.Process.CreateProcess.
• etc

You can either provide a list of environment variables (normally of type [(Text, Text)]) to apply RichEnv rules or use the environment variables from the current process.

Code example

Assuming you are using the previous YAML example (and a controlled set of environment variables for the current process, see steps 1 and 2 below), you could use RichEnv modify the environment variables like this:

{-# LANGUAGE DeriveAnyClass #-}
{-# LANGUAGE DeriveGeneric #-}

module Main where

import Data.Aeson (FromJSON, ToJSON)
import Data.Yaml (decodeFileEither)
import Data.Yaml.Aeson (ParseException)
import GHC.Generics (Generic)
import RichEnv (RichEnv (..), clearEnvironment, setRichEnvFromCurrent)
import System.Environment (getEnvironment, setEnv)

newtype SomeConfig = SomeConfig {env :: RichEnv} deriving (Show, Eq, Generic, FromJSON, ToJSON)

main :: IO ()
main = do
  decodedYaml <- decodeFileEither "./example.yaml" :: IO (Either ParseException SomeConfig)
  case decodedYaml of
    Left err -> error $ show err
    Right rEnv -> do
      -- Successfully parsed. Now we can use the RichEnv
      -- 1. clear the environment of the current process
      getEnvironment >>= clearEnvironment
      -- 2. Set an example environment for the current process
      mapM_ (uncurry setEnv) [("FOO", "bar"), ("OLDNAME", "qux"), ("PREFIXED_VAR", "content"), ("OTHER_PREFIXED_VAR2", "content2")]
      -- 3. modify the current environment with the RichEnv
      setRichEnvFromCurrent (env rEnv)
      -- 4. check the environment again
      getEnvironment >>= print

-- printedOutput =
--   [ ("OTHER_NEW_PREFIX_VAR2", "content2"),
--     ("VERBOSE", "true"),
--     ("NEWNAME", "qux"),
--     ("NEW_PREFIX_VAR", "content"),
--     ("NEW_PREFIX_VAR2", "content2")
--   ]
  -- ...

As mentioned before, instead of modifying the current process, you use RichEnv to spawn processes with custom environments (for example with System.Process' proc and CreateProcess' env field) defined with your rules, effectively controlling how the environment is forwarded from the current process to the spawned ones.

See the Hackage documentation and the tests for more details and examples.