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


-- | Safe helpers for accessing and modifying environment variables
--   
--   Please see the README on GitHub at
--   <a>https://github.com/d12frosted/env-extra</a>
@package env-extra
@version 1.0.0.0


-- | The module defines function <a>setEnv</a> - a lifted version of
--   <a>setEnv</a> that works with <a>Text</a> input and various safe
--   versions of <a>lookupEnv</a> that allow one to get any <a>IsString</a>
--   (<a>getEnv</a> and <a>envMaybe</a>) or even provide a <a>Reader</a> to
--   parse the value (<a>envRead</a>)
--   
--   <pre>
--   &gt;&gt;&gt; getEnv "HOME"
--   "/Users/d12frosted"
--   
--   &gt;&gt;&gt; getEnv "WHAAT"
--   *** Exception: Could not find value of $WHAAT in environment.
--   
--   &gt;&gt;&gt; setEnv "WHAAT" "HOME"
--   
--   &gt;&gt;&gt; getEnv "WHAAT"
--   "HOME"
--   
--   &gt;&gt;&gt; getEnv "WHAAT" &gt;&gt;= getEnv
--   "/Users/d12frosted"
--   
--   &gt;&gt;&gt; getEnv "WHAAT" &gt;&gt;= putStrLn
--   HOME
--   
--   &gt;&gt;&gt; setEnv "AGE" "12"
--   
--   &gt;&gt;&gt; envMaybe "AGE"
--   Just "12"
--   
--   &gt;&gt;&gt; envRead decimal "AGE"
--   Just 12
--   </pre>
module System.Environment.Extra

-- | Set value of environment variable.
--   
--   Thorws <a>IOException</a>.
--   
--   <pre>
--   &gt;&gt;&gt; envMaybe "NAME"
--   Nothing
--   
--   &gt;&gt;&gt; setEnv "NAME" "Boris"
--   
--   &gt;&gt;&gt; envMaybe "NAME"
--   Just "Boris"
--   </pre>
setEnv :: (MonadThrow m, MonadIO m) => Text -> Text -> m ()

-- | Get value of environment variable.
--   
--   Throws <a>EnvVarNotFound</a>.
--   
--   <pre>
--   &gt;&gt;&gt; getEnv "NAME"
--   *** Exception: Could not find value of $NAME in environment.
--   
--   &gt;&gt;&gt; getEnv "HOME"
--   "/Users/d12frosted"
--   </pre>
getEnv :: (MonadThrow m, MonadIO m, IsString a) => Text -> m a

-- | Get value of environment variable. &gt;&gt;&gt; getEnv <a>NAME</a>
--   Nothing &gt;&gt;&gt; getEnv <a>HOME</a> Just "<i>Users</i>d12frosted"
envMaybe :: (MonadIO m, IsString a) => Text -> m (Maybe a)

-- | Get value of environment variable and parse it using specific reader.
--   &gt;&gt;&gt; setEnv <a>AGE</a> "12" &gt;&gt;&gt; envMaybe <a>AGE</a>
--   Just "12" &gt;&gt;&gt; envRead decimal <a>AGE</a> Just 12
envRead :: MonadIO m => Reader a -> Text -> m (Maybe a)

-- | Generic reader for readable values.
--   
--   Keep in mind that it's always better from performance view to use
--   specific Reader functions like <tt><a>decimal</a></tt> instead of this
--   generic one.
read :: Read a => Reader a

-- | Exceptions that can occur during reading the environment variable.
newtype EnvironmentException
EnvVarNotFound :: Text -> EnvironmentException

-- | Read some text. If the read succeeds, return its value and the
--   remaining text, otherwise an error message.
type Reader a = IReader Text a

-- | Read a decimal integer. The input must begin with at least one decimal
--   digit, and is consumed until a non-digit or end of string is reached.
--   
--   This function does not handle leading sign characters. If you need to
--   handle signed input, use <tt><a>signed</a> <a>decimal</a></tt>.
--   
--   <i>Note</i>: For fixed-width integer types, this function does not
--   attempt to detect overflow, so a sufficiently long input may give
--   incorrect results. If you are worried about overflow, use
--   <a>Integer</a> for your result type.
decimal :: Integral a => Reader a

-- | Read an optional leading sign character (<tt>'-'</tt> or <tt>'+'</tt>)
--   and apply it to the result of applying the given reader.
signed :: Num a => Reader a -> Reader a

-- | Read a hexadecimal integer, consisting of an optional leading
--   <tt>"0x"</tt> followed by at least one hexadecimal digit. Input is
--   consumed until a non-hex-digit or end of string is reached. This
--   function is case insensitive.
--   
--   This function does not handle leading sign characters. If you need to
--   handle signed input, use <tt><a>signed</a> <a>hexadecimal</a></tt>.
--   
--   <i>Note</i>: For fixed-width integer types, this function does not
--   attempt to detect overflow, so a sufficiently long input may give
--   incorrect results. If you are worried about overflow, use
--   <a>Integer</a> for your result type.
hexadecimal :: Integral a => Reader a

-- | Read a rational number.
--   
--   This function accepts an optional leading sign character, followed by
--   at least one decimal digit. The syntax similar to that accepted by the
--   <a>read</a> function, with the exception that a trailing <tt>'.'</tt>
--   or <tt>'e'</tt> <i>not</i> followed by a number is not consumed.
--   
--   Examples (with behaviour identical to <a>read</a>):
--   
--   <pre>
--   rational "3"     == Right (3.0, "")
--   rational "3.1"   == Right (3.1, "")
--   rational "3e4"   == Right (30000.0, "")
--   rational "3.1e4" == Right (31000.0, "")
--   rational ".3"    == Left "input does not start with a digit"
--   rational "e3"    == Left "input does not start with a digit"
--   </pre>
--   
--   Examples of differences from <a>read</a>:
--   
--   <pre>
--   rational "3.foo" == Right (3.0, ".foo")
--   rational "3e"    == Right (3.0, "e")
--   </pre>
rational :: Fractional a => Reader a

-- | Read a rational number.
--   
--   The syntax accepted by this function is the same as for
--   <a>rational</a>.
--   
--   <i>Note</i>: This function is almost ten times faster than
--   <a>rational</a>, but is slightly less accurate.
--   
--   The <a>Double</a> type supports about 16 decimal places of accuracy.
--   For 94.2% of numbers, this function and <a>rational</a> give identical
--   results, but for the remaining 5.8%, this function loses precision
--   around the 15th decimal place. For 0.001% of numbers, this function
--   will lose precision at the 13th or 14th decimal place.
double :: Reader Double
instance GHC.Exception.Type.Exception System.Environment.Extra.EnvironmentException
instance GHC.Show.Show System.Environment.Extra.EnvironmentException