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


-- | Rich environment variable setup for Haskell
--   
--   This package exposes a type that captures a set of rules to modify an
--   existing environment variable set, be it a provided list of key-value
--   pairs (list of duples) or the system's environment variable set
--   itself. Each rule can be either a prefix, a mapping or a value. See
--   README.md for more details.
@package richenv
@version 0.1.0.0


-- | This module contains the basic types used by the library and their
--   typeclass instances.
module RichEnv.Types

-- | Type that represents a set of rules that generate environment
--   variables. A value of this type can be retrieved from a configuration
--   file (e.g. YAML) due to its <a>FromJSON</a> instance, or persisted
--   into one with <a>ToJSON</a>.
data RichEnv
RichEnv :: Values -> Mappings -> Prefixes -> RichEnv

-- | A list of environment variables to be set with their values.
[values] :: RichEnv -> Values

-- | Mappings from one existing environment variable name to another.
[mappings] :: RichEnv -> Mappings

-- | Mappings from different prefixes of existing environment variables to
--   new prefixes.
[prefixes] :: RichEnv -> Prefixes

-- | Default <a>RichEnv</a> value. With everything empty.
defaultRichEnv :: RichEnv

-- | A list of key-value pairs representing environment variables.
type Environment = [(Text, Text)]

-- | A list of key-value pairs representing environment variable name
--   mappings. The internal representation is a 'HashMap Text Text', where
--   the key is the final variable name and the value is the current one
--   which will be replaced.
newtype Mappings
Mappings :: HashMap Text Text -> Mappings
[unMappings] :: Mappings -> HashMap Text Text

-- | A list of key-value pairs representing environment variables. The
--   internal representation is a 'HashMap Text Text', where the key is the
--   variable name and the value is the variable value.
newtype Values
Values :: HashMap Text Text -> Values
[unValues] :: Values -> HashMap Text Text

-- | A list of key-value pairs representing environment variable name
--   prefix mappings. The internal representation is a 'HashMap Text
--   [Text]', where the key is the final prefix and the value is the list
--   of prefixes that will be replaced.
newtype Prefixes
Prefixes :: HashMap Text [Text] -> Prefixes
[unPrefixes] :: Prefixes -> HashMap Text [Text]

-- | Transform the type returned from <a>getEnvironment</a> (<tt>[(String,
--   String)]</tt>) to use <a>Text</a> instead.
toEnvironment :: [(String, String)] -> Environment

-- | Get back a <tt>[(String, String)]</tt> from an <a>Environment</a>.
fromEnvironment :: Environment -> [(String, String)]
instance Data.Aeson.Types.ToJSON.ToJSON RichEnv.Types.RichEnv
instance Data.Aeson.Types.FromJSON.FromJSON RichEnv.Types.RichEnv
instance GHC.Generics.Generic RichEnv.Types.RichEnv
instance GHC.Show.Show RichEnv.Types.RichEnv
instance GHC.Classes.Eq RichEnv.Types.RichEnv
instance GHC.Base.Semigroup RichEnv.Types.RichEnv
instance GHC.Base.Monoid RichEnv.Types.RichEnv


-- | This module contains functions for setting environment variables from
--   the <a>RichEnv</a> types as well as functions for transforming between
--   the different types used by this library (<a>Values</a>,
--   <a>Mappings</a> and <a>Prefixes</a>).
module RichEnv.Setters

-- | Takes an environment variable list and all the name mappings and
--   prepares a set of environment variables according to the RichEnv
--   rules.
--   
--   <pre>
--   &gt;&gt;&gt; mappingsToValues [("FOO", "bar"), ("SOME", "thing")] (Mappings $ HM.fromList [("OTHER", "FOO")])
--   Values {unValues = fromList [("OTHER","bar")]}
--   </pre>
mappingsToValues :: Environment -> Mappings -> Values

-- | Takes an environment variable list and all the prefix mappings and
--   prepares a set of environment variables according to the
--   <a>RichEnv</a> rules.
--   
--   <pre>
--   &gt;&gt;&gt; prefixesToValues [("FOO", "bar"), ("SOME", "thing")] (Prefixes $ HM.fromList [("OTHER", ["FOO"])])
--   Values {unValues = fromList [("OTHER","bar")]}
--   </pre>
prefixesToValues :: Environment -> Prefixes -> Values

-- | Takes a <a>Values</a> object and sets its contents as environment
--   variables.
valuesToEnv :: Values -> IO ()

-- | Takes a <a>Values</a> object and transforms it into a list of
--   key-value pairs representing environment variables.
--   
--   <pre>
--   valuesToEnvList = Data.HashMap.Strict.toList . unValues
--   </pre>
valuesToEnvList :: Values -> Environment

-- | Takes an environment variable list and a <a>RichEnv</a> object and
--   generates a <a>Values</a> object.
--   
--   <pre>
--   &gt;&gt;&gt; richEnvToValues RichEnv.Types.defaultRichEnv [("FOO", "bar"), ("SOME", "thing")]
--   Values {unValues = fromList []}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; import RichEnv.Types.Values as V
--   
--   &gt;&gt;&gt; let richEnvValue = RichEnv.Types.defaultRichEnv { values = V.fromList [("OTHER", "var")]}
--   
--   &gt;&gt;&gt; let envList = [("FOO", "bar"), ("SOME", "thing")]
--   
--   &gt;&gt;&gt; richEnvToValues richEnvValue envList
--   Values {unValues = fromList [("OTHER","var")]}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; import RichEnv.Types.Mappings as M
--   
--   &gt;&gt;&gt; let richEnvValue = RichEnv.Types.defaultRichEnv { mappings = M.fromList [("SOME", "FOO")]}
--   
--   &gt;&gt;&gt; let envList = [("FOO", "bar"), ("SOME", "thing"), ("SOME", "other")]
--   
--   &gt;&gt;&gt; richEnvToValues richEnvValue envList
--   Values {unValues = fromList [("SOME","bar")]}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; import RichEnv.Types.Prefixes as P
--   
--   &gt;&gt;&gt; let richEnvValue = RichEnv.Types.defaultRichEnv { prefixes = P.fromList [("NEW_", ["PREFIXED_"])]}
--   
--   &gt;&gt;&gt; let envList = [("PREFIXED_VAR", "content"), ("PREFIXED_VAR2", "content2")]
--   
--   &gt;&gt;&gt; richEnvToValues richEnvValue envList
--   Values {unValues = fromList [("NEW_VAR","content"),("NEW_VAR2","content2")]}
--   </pre>
richEnvToValues :: RichEnv -> Environment -> Values


-- | This module provides functions to set environment variables or
--   retrieve an environment variable list according to a <a>RichEnv</a>
--   object input, which defines:
--   
--   <ul>
--   <li>A list of environment variables to be set with their values.</li>
--   <li>Mapping the name from one existing environment variable name to
--   another (If there's an environment variable <tt><b>FOO=bar</b></tt>, a
--   mapping <tt><b>("SOME", "FOO")</b></tt> will generate an environment
--   variable definition <tt><b>SOME</b></tt> with the contents of the
--   variable <tt><b>FOO</b></tt>).</li>
--   <li>Mapping the prefixes of existing environment variables to a new
--   prefix (If there's an environment variable
--   <tt><b>FOO_VAR=bar</b></tt>, a prefix mapping <tt><b>("SOME",
--   ["FOO"])</b></tt> will generate an environment variable definition
--   <tt><b>SOME_VAR</b></tt> with the contents of the variable
--   <tt><b>FOO_VAR</b></tt>).</li>
--   </ul>
module RichEnv

-- | Type that represents a set of rules that generate environment
--   variables. A value of this type can be retrieved from a configuration
--   file (e.g. YAML) due to its <a>FromJSON</a> instance, or persisted
--   into one with <a>ToJSON</a>.
data RichEnv
RichEnv :: Values -> Mappings -> Prefixes -> RichEnv

-- | A list of environment variables to be set with their values.
[values] :: RichEnv -> Values

-- | Mappings from one existing environment variable name to another.
[mappings] :: RichEnv -> Mappings

-- | Mappings from different prefixes of existing environment variables to
--   new prefixes.
[prefixes] :: RichEnv -> Prefixes

-- | A list of key-value pairs representing environment variables.
type Environment = [(Text, Text)]

-- | Get a key-value list of environment variables processing the passed
--   environment with the <a>RichEnv</a> input.
--   
--   <pre>
--   toEnvList re env = valuesToEnvList (toEnvValues re env)
--   </pre>
toEnvList :: RichEnv -> Environment -> Environment

-- | Get a hashmap of environment variables processing the passed
--   environment with the <a>RichEnv</a> input. The idea is that the output
--   could be passed to functions like <a>Yaml</a>'s <a>applyEnvValue</a>.
--   
--   <pre>
--   toEnvMap re env = unValues (toEnvValues re env)
--   </pre>
toEnvMap :: RichEnv -> Environment -> HashMap Text Text

-- | Sets the environment variables available for the current process
--   abiding to the <a>RichEnv</a> rules.
setRichEnv :: RichEnv -> Environment -> IO ()

-- | Sets the environment variables available for the current process by
--   checking the current environment variables and applying the
--   <a>RichEnv</a> rules.
--   
--   <pre>
--   setRichEnvFromCurrent re = getEnvironment &gt;&gt;= setRichEnv re . toEnvironment
--   </pre>
setRichEnvFromCurrent :: RichEnv -> IO ()

-- | Get a key-value list of environment variables processing the current
--   environment with the <a>RichEnv</a> input.
--   
--   <pre>
--   toEnvListFromCurrent re = toEnvList re . toEnvironment &lt;$&gt; getEnvironment
--   </pre>
toEnvListFromCurrent :: RichEnv -> IO Environment

-- | Get a hashmap of environment variables processing the current
--   environment with the <a>RichEnv</a> input. The idea is that the output
--   could be passed to functions like <a>Yaml</a>'s <a>applyEnvValue</a>.
--   
--   <pre>
--   toEnvMapFromCurrent re = toEnvMap re . toEnvironment &lt;$&gt; getEnvironment
--   </pre>
toEnvMapFromCurrent :: RichEnv -> IO (HashMap Text Text)

-- | Clears all environment variables of the current process.
clearEnvironment :: [(String, String)] -> IO ()