System.Environment.Extra

The module defines function setEnv - a lifted version of setEnv that works with Text input and various safe versions of lookupEnv that allow one to get any IsString (getEnv and envMaybe) or even provide a Reader to parse the value (envRead)

>>> getEnv "HOME"
"/Users/d12frosted"
>>> getEnv "WHAAT"
*** Exception: Could not find value of $WHAAT in environment.
>>> setEnv "WHAAT" "HOME"
>>> getEnv "WHAAT"
"HOME"
>>> getEnv "WHAAT" >>= getEnv
"/Users/d12frosted"
>>> getEnv "WHAAT" >>= putStrLn
HOME
>>> setEnv "AGE" "12"
>>> envMaybe "AGE"
Just "12"
>>> envRead decimal "AGE"
Just 12

Documentation

setEnv :: (MonadThrow m, MonadIO m) => Text -> Text -> m ()

Set value of environment variable.

Thorws IOException.

>>> envMaybe "NAME"
Nothing
>>> setEnv "NAME" "Boris"
>>> envMaybe "NAME"
Just "Boris"

getEnv :: (MonadThrow m, MonadIO m, IsString a) => Text -> m a

Get value of environment variable.

Throws EnvVarNotFound.

>>> getEnv "NAME"
*** Exception: Could not find value of $NAME in environment.
>>> getEnv "HOME"
"/Users/d12frosted"

envMaybe :: (MonadIO m, IsString a) => Text -> m (Maybe a)

Get value of environment variable. >>> getEnv NAME Nothing >>> getEnv HOME Just "Usersd12frosted"

envRead :: MonadIO m => Reader a -> Text -> m (Maybe a)

Get value of environment variable and parse it using specific reader. >>> setEnv AGE "12" >>> envMaybe AGE Just "12" >>> envRead decimal AGE Just 12

read :: Read a => Reader a

Generic reader for readable values.

Keep in mind that it's always better from performance view to use specific Reader functions like decimal instead of this generic one.

Data types

newtype EnvironmentException

Exceptions that can occur during reading the environment variable.

Constructors

EnvVarNotFound Text

Instances

Show EnvironmentException

Defined in System.Environment.Extra

Methods

showsPrec :: Int -> EnvironmentException -> ShowS

show :: EnvironmentException -> String

showList :: [EnvironmentException] -> ShowS

Exception EnvironmentException

Defined in System.Environment.Extra

Methods

toException :: EnvironmentException -> SomeException

fromException :: SomeException -> Maybe EnvironmentException

displayException :: EnvironmentException -> String

Reexport several Readers from Data.Text

type Reader a = IReader Text a

Read some text. If the read succeeds, return its value and the remaining text, otherwise an error message.

decimal :: Integral a => Reader 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 signed decimal.

Note: 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 Integer for your result type.

signed :: Num a => Reader a -> Reader a

Read an optional leading sign character ('-' or '+') and apply it to the result of applying the given reader.

hexadecimal :: Integral a => Reader a

Read a hexadecimal integer, consisting of an optional leading "0x" 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 signed hexadecimal.

Note: 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 Integer for your result type.

rational :: Fractional 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 read function, with the exception that a trailing '.' or 'e' not followed by a number is not consumed.

Examples (with behaviour identical to read):

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"

Examples of differences from read:

rational "3.foo" == Right (3.0, ".foo")
rational "3e"    == Right (3.0, "e")

double :: Reader Double

Read a rational number.

The syntax accepted by this function is the same as for rational.

Note: This function is almost ten times faster than rational, but is slightly less accurate.

The Double type supports about 16 decimal places of accuracy. For 94.2% of numbers, this function and rational 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.