-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Loads environment variables from dotenv files
--   
--   In most applications, <a>configuration should be separated from
--   code</a>. While it usually works well to keep configuration in the
--   environment, there are cases where you may want to store configuration
--   in a file outside of version control.
--   
--   <a>Dotenv</a> files have become popular for storing configuration,
--   especially in development and test environments. In <a>Ruby</a>,
--   <a>Python</a> and <a>Javascript</a> there are libraries to facilitate
--   loading of configuration options from configuration files. This
--   library loads configuration to environment variables for programs
--   written in Haskell.
--   
--   To use, call <a>loadFile</a> from your application:
--   
--   <pre>
--   import Control.Monad (void)
--   import Configuration.Dotenv
--   void $ loadFile defaultConfig
--   </pre>
--   
--   This package also includes an executable that can be used to inspect
--   the results of applying one or more Dotenv files to the environment,
--   or for invoking your executables with an environment after one or more
--   Dotenv files is applied.
--   
--   See the <a>Github</a> page for more information on this package.
@package dotenv
@version 0.8.0.0

module Configuration.Dotenv.Environment

-- | <a>getEnvironment</a> retrieves the entire environment as a list of
--   <tt>(key,value)</tt> pairs.
--   
--   If an environment entry does not contain an <tt>'='</tt> character,
--   the <tt>key</tt> is the whole entry and the <tt>value</tt> is the
--   empty string.
getEnvironment :: IO [(String, String)]
lookupEnv :: String -> IO (Maybe String)
setEnv :: String -> String -> IO ()

-- | Like <a>unsetEnv</a>, but allows for the removal of blank environment
--   variables. May throw an exception if the underlying platform doesn't
--   support unsetting of environment variables.
unsetEnv :: String -> IO ()


-- | This module contains common functions to load and read dotenv files.
module Configuration.Dotenv

-- | Loads the given list of options into the environment. Optionally
--   override existing variables with values from Dotenv files.
load :: MonadIO m => Bool -> [(String, String)] -> m ()

-- | <tt>loadFile</tt> parses the environment variables defined in the
--   dotenv example file and checks if they are defined in the dotenv file
--   or in the environment. It also allows to override the environment
--   variables defined in the environment with the values defined in the
--   dotenv file.
loadFile :: MonadIO m => Config -> m [(String, String)]

-- | <tt>loadSafeFile</tt> parses the <i>.scheme.yml</i> file and will
--   perform the type checking of the environment variables in the
--   <i>.env</i> file.
loadSafeFile :: MonadIO m => ValidatorMap -> FilePath -> Config -> m [(String, String)]

-- | Parses the given dotenv file and returns values <i>without</i> adding
--   them to the environment.
parseFile :: MonadIO m => FilePath -> m [(String, String)]

-- | The helper allows to avoid exceptions in the case of missing files and
--   perform some action instead.
onMissingFile :: MonadCatch m => m a -> m a -> m a

-- | Configuration Data Types with extra options for executing dotenv.
data Config
Config :: [FilePath] -> [FilePath] -> Bool -> Config

-- | The paths for the .env files
[configPath] :: Config -> [FilePath]

-- | The paths for the .env.example files
[configExamplePath] :: Config -> [FilePath]

-- | Flag to allow override env variables
[configOverride] :: Config -> Bool

-- | Default configuration. Use .env file without .env.example strict envs
--   and without overriding.
defaultConfig :: Config

-- | Parameters:
--   
--   <ul>
--   <li><b>Key:</b> Name of the <i>format</i> to check.</li>
--   <li><b>Value:</b> Function to check if some text meets the
--   condition.</li>
--   </ul>
type ValidatorMap = Map Text (Text -> Bool)

-- | Default configuration for <tt>loadSafeFile</tt>. It currently checks:
--   <tt>bool</tt>, <tt>integer</tt>, and <tt>text</tt>.
defaultValidatorMap :: ValidatorMap
