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


-- | Functions for safely reading environment variables.
--   
--   Please see README.md
@package read-env-var
@version 1.0.0.0


-- | This Haskell module exports functions for safely reading environment
--   variables.
--   
--   The <tt>lookupEnv*</tt> functions are for reading in
--   <a>String</a>-like environment variables (like hostnames, passwords,
--   etc.), while the <tt>readEnv*</tt> functions are for reading in
--   Haskell datatypes (like <a>Int</a>, <a>Double</a>, etc).
--   
--   Most of these functions run in <a>MonadIO</a>. This means that they
--   can be used from any monad that implements <a>MonadIO</a>. This makes
--   it easier to run in a monad transformer stack. If you're not familiar
--   with <a>MonadIO</a>, you can just think of all the functions as being
--   <a>IO</a> actions.
--   
--   The <a>lookupEnv</a>, <a>lookupEnvDef</a>, and <a>lookupEnvEx</a>
--   functions all use <a>IsString</a> to generalize the return type. This
--   makes it more general than <a>System.Environment</a>'s
--   <a>lookupEnv</a>. It makes it possible to read in things other than
--   <a>String</a>s, like <a>Text</a> or <a>ByteString</a>.
module System.ReadEnvVar

-- | Like <a>System.Environment</a>'s <a>lookupEnv</a>, but using
--   <a>IsString</a> to make it more general.
--   
--   Lookup an environment variable that exists:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR" "foo"
--   
--   &gt;&gt;&gt; lookupEnv "TEST_ENV_VAR" :: IO (Maybe String)
--   Just "foo"
--   </pre>
--   
--   Lookup an environment variable that doesn't exist. Return
--   <a>Nothing</a>:
--   
--   <pre>
--   &gt;&gt;&gt; lookupEnv "THIS_ENV_VAR_WILL_NOT_EXIST" :: IO (Maybe String)
--   Nothing
--   </pre>
lookupEnv :: (IsString a, MonadIO m) => String -> m (Maybe a)

-- | Like <a>lookupEnv</a> but take a default value.
--   
--   Lookup an environment variable that exists:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR" "foo"
--   
--   &gt;&gt;&gt; lookupEnvDef "TEST_ENV_VAR" "bar" :: IO String
--   "foo"
--   </pre>
--   
--   Lookup an environment variable that doesn't exist. Return the default
--   value:
--   
--   <pre>
--   &gt;&gt;&gt; lookupEnvDef "THIS_ENV_VAR_WILL_NOT_EXIST" "bar" :: IO String
--   "bar"
--   </pre>
lookupEnvDef :: (IsString a, MonadIO m) => String -> a -> m a

-- | Lookup a value from an environment variable and read it in with
--   <a>readMaybe</a>.
--   
--   Read an environment variable that exists:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR" "2000"
--   
--   &gt;&gt;&gt; readEnv "TEST_ENV_VAR" :: IO (Maybe Int)
--   Just 2000
--   </pre>
--   
--   Try reading an environment variable that does not exist. Returns
--   <a>Nothing</a>:
--   
--   <pre>
--   &gt;&gt;&gt; readEnv "THIS_ENV_VAR_WILL_NOT_EXIST" :: IO (Maybe Int)
--   Nothing
--   </pre>
--   
--   Try reading an environment variable that cannot be <a>read</a>.
--   Returns <a>Nothing</a>:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "BAD_ENV_VAR" "not an int"
--   
--   &gt;&gt;&gt; readEnv "BAD_ENV_VAR" :: IO (Maybe Int)
--   Nothing
--   </pre>
--   
--   Note that this <b>DOES NOT</b> read string values as one might expect:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR2" "some string 1"
--   
--   &gt;&gt;&gt; readEnv "TEST_ENV_VAR2" :: IO (Maybe String)
--   Nothing
--   </pre>
--   
--   It will read string values as if they were Haskell strings:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR3" "\"some string 1\""
--   
--   &gt;&gt;&gt; readEnv "TEST_ENV_VAR3" :: IO (Maybe String)
--   Just "some string 1"
--   </pre>
readEnv :: (MonadIO m, Read a) => String -> m (Maybe a)

-- | Lookup a value from an environment variable and read it in with
--   <a>readMaybe</a>. If the environment variable doesn't exist, or it
--   can't be <a>read</a>, return the default value. Like <a>readEnv</a>
--   but with a default value.
--   
--   Read an environment variable that exists:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR1" "1000"
--   
--   &gt;&gt;&gt; readEnvDef "TEST_ENV_VAR1" 5 :: IO Int
--   1000
--   </pre>
--   
--   Try reading an environment variable that does not exist. Returns the
--   default value:
--   
--   <pre>
--   &gt;&gt;&gt; readEnvDef "THIS_ENV_VAR_WILL_NOT_EXIST" 5 :: IO Int
--   5
--   </pre>
--   
--   Try reading an environment variable that cannot be <a>read</a>.
--   Returns the default value:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "BAD_ENV_VAR" "not an int"
--   
--   &gt;&gt;&gt; readEnvDef "BAD_ENV_VAR" 10 :: IO Int
--   10
--   </pre>
--   
--   Note that this <b>DOES NOT</b> read string values as one might expect:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR2" "some string 1"
--   
--   &gt;&gt;&gt; readEnvDef "TEST_ENV_VAR2" "def val" :: IO String
--   "def val"
--   </pre>
--   
--   It will read string values as if they were Haskell strings:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR3" "\"some string 1\""
--   
--   &gt;&gt;&gt; readEnvDef "TEST_ENV_VAR3" "def val" :: IO String
--   "some string 1"
--   </pre>
readEnvDef :: (MonadIO m, Read a) => String -> a -> m a

-- | <a>Exception</a> thrown by <a>lookupEnvEx</a> and <a>readEnvEx</a>
--   when the environment variable being read doesn't exist.
data EnvVarDoesNotExistException

-- | The <a>String</a> is the name of the environment variable that does
--   not exist.
EnvVarDoesNotExistException :: String -> EnvVarDoesNotExistException

-- | Like <a>lookupEnv</a>, but instead of returning a <a>Maybe</a>, throw
--   an <a>EnvVarDoesNotExistException</a> if the environment variable does
--   not exist. The exception is thrown with <a>throwM</a> from
--   <a>MonadThrow</a>.
--   
--   Lookup an environment variable that exists:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR" "foo"
--   
--   &gt;&gt;&gt; lookupEnvEx "TEST_ENV_VAR" :: IO String
--   "foo"
--   </pre>
--   
--   Lookup an environment variable that doesn't exist. Throws
--   <a>EnvVarDoesNotExistException</a>.
--   
--   <pre>
--   &gt;&gt;&gt; lookupEnvEx "THIS_ENV_VAR_WILL_NOT_EXIST" :: IO String
--   *** Exception: EnvVarDoesNotExistException "THIS_ENV_VAR_WILL_NOT_EXIST"
--   </pre>
lookupEnvEx :: (IsString a, MonadIO m, MonadThrow m) => String -> m a

-- | Lookup a value from an environment variable and read it in with
--   <a>readMaybe</a>. Throw an <a>EnvVarDoesNotExistException</a> if the
--   environment variable does not exist. The exception is thrown with
--   <a>throwM</a> from <a>MonadThrow</a>.
--   
--   Read an environment variable that exists:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR" "2000"
--   
--   &gt;&gt;&gt; readEnvEx "TEST_ENV_VAR" :: IO (Maybe Int)
--   Just 2000
--   </pre>
--   
--   Try reading an environment variable that does not exist. Throws
--   <a>EnvVarDoesNotExistException</a>:
--   
--   <pre>
--   &gt;&gt;&gt; readEnvEx "THIS_ENV_VAR_WILL_NOT_EXIST" :: IO (Maybe Int)
--   *** Exception: EnvVarDoesNotExistException "THIS_ENV_VAR_WILL_NOT_EXIST"
--   </pre>
--   
--   Try reading an environment variable that cannot be <a>read</a>.
--   Returns <a>Nothing</a>:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "BAD_ENV_VAR" "not an int"
--   
--   &gt;&gt;&gt; readEnvEx "BAD_ENV_VAR" :: IO (Maybe Int)
--   Nothing
--   </pre>
--   
--   Note that this <b>DOES NOT</b> read string values as one might expect:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR2" "some string 1"
--   
--   &gt;&gt;&gt; readEnvEx "TEST_ENV_VAR2" :: IO (Maybe String)
--   Nothing
--   </pre>
--   
--   It will read string values as if they were Haskell strings:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR3" "\"some string 1\""
--   
--   &gt;&gt;&gt; readEnvEx "TEST_ENV_VAR3" :: IO (Maybe String)
--   Just "some string 1"
--   </pre>
readEnvEx :: (MonadIO m, Read a, MonadThrow m) => String -> m (Maybe a)

-- | <a>Exception</a> thrown by <a>readEnvEx'</a> when the environment
--   variable cannot be <a>read</a>.
data EnvVarCannotBeReadException

-- | The first <a>String</a> is the name of the environment variable that
--   cannot be <a>read</a>.
EnvVarCannotBeReadException :: String -> EnvVarCannotBeReadException

-- | Just like <a>readEnvEx</a>, but also throw an exception when the
--   environment variable cannot be <a>read</a>.
--   
--   This can throw both <a>EnvVarCannotBeReadException</a> and
--   <a>EnvVarDoesNotExistException</a> with <a>throwM</a>.
--   
--   Read an environment variable that exists:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR" "2000"
--   
--   &gt;&gt;&gt; readEnvEx' "TEST_ENV_VAR" :: IO Int
--   2000
--   </pre>
--   
--   Try reading an environment variable that does not exist. Throws
--   <a>EnvVarDoesNotExistException</a>:
--   
--   <pre>
--   &gt;&gt;&gt; readEnvEx' "THIS_ENV_VAR_WILL_NOT_EXIST" :: IO Int
--   *** Exception: EnvVarDoesNotExistException "THIS_ENV_VAR_WILL_NOT_EXIST"
--   </pre>
--   
--   Try reading an environment variable that cannot be <a>read</a>. Throws
--   <a>EnvVarCannotBeReadException</a>:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "BAD_ENV_VAR" "not an int"
--   
--   &gt;&gt;&gt; readEnvEx' "BAD_ENV_VAR" :: IO Int
--   *** Exception: EnvVarCannotBeReadException "BAD_ENV_VAR"
--   </pre>
--   
--   Note that this <b>DOES NOT</b> read string values as one might expect:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR2" "some string 1"
--   
--   &gt;&gt;&gt; readEnvEx' "TEST_ENV_VAR2" :: IO String
--   *** Exception: EnvVarCannotBeReadException "TEST_ENV_VAR2"
--   </pre>
--   
--   It will read string values as if they were Haskell strings:
--   
--   <pre>
--   &gt;&gt;&gt; setEnv "TEST_ENV_VAR3" "\"some string 1\""
--   
--   &gt;&gt;&gt; readEnvEx' "TEST_ENV_VAR3" :: IO String
--   "some string 1"
--   </pre>
readEnvEx' :: (MonadIO m, Read a, MonadThrow m) => String -> m a

-- | <tt>setEnv name value</tt> sets the specified environment variable to
--   <tt>value</tt>.
--   
--   Early versions of this function operated under the mistaken belief
--   that setting an environment variable to the <i>empty string</i> on
--   Windows removes that environment variable from the environment. For
--   the sake of compatibility, it adopted that behavior on POSIX. In
--   particular
--   
--   <pre>
--   setEnv name ""
--   </pre>
--   
--   has the same effect as
--   
--   <pre>
--   <a>unsetEnv</a> name
--   </pre>
--   
--   If you'd like to be able to set environment variables to blank
--   strings, use <a>setEnv</a>.
--   
--   Throws <a>IOException</a> if <tt>name</tt> is the empty string or
--   contains an equals sign.
setEnv :: String -> String -> IO ()
instance GHC.Show.Show System.ReadEnvVar.EnvVarCannotBeReadException
instance GHC.Read.Read System.ReadEnvVar.EnvVarCannotBeReadException
instance GHC.Classes.Ord System.ReadEnvVar.EnvVarCannotBeReadException
instance GHC.Classes.Eq System.ReadEnvVar.EnvVarCannotBeReadException
instance Data.Data.Data System.ReadEnvVar.EnvVarCannotBeReadException
instance GHC.Show.Show System.ReadEnvVar.EnvVarDoesNotExistException
instance GHC.Read.Read System.ReadEnvVar.EnvVarDoesNotExistException
instance GHC.Classes.Ord System.ReadEnvVar.EnvVarDoesNotExistException
instance GHC.Classes.Eq System.ReadEnvVar.EnvVarDoesNotExistException
instance Data.Data.Data System.ReadEnvVar.EnvVarDoesNotExistException
instance GHC.Exception.Exception System.ReadEnvVar.EnvVarCannotBeReadException
instance GHC.Exception.Exception System.ReadEnvVar.EnvVarDoesNotExistException
