Copyright | (c) Boris Buliga 2016-2020 |
---|---|

License | MIT |

Maintainer | boris@d12frosted.io |

Stability | experimental |

Portability | POSIX |

Safe Haskell | Safe |

Language | Haskell2010 |

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`

)

`>>>`

"/Users/d12frosted"`getEnv "HOME"`

`>>>`

*** Exception: Could not find value of $WHAAT in environment.`getEnv "WHAAT"`

`>>>`

`setEnv "WHAAT" "HOME"`

`>>>`

"HOME"`getEnv "WHAAT"`

`>>>`

"/Users/d12frosted"`getEnv "WHAAT" >>= getEnv`

`>>>`

HOME`getEnv "WHAAT" >>= putStrLn`

`>>>`

`setEnv "AGE" "12"`

`>>>`

Just "12"`envMaybe "AGE"`

`>>>`

Just 12`envRead decimal "AGE"`

## Synopsis

- setEnv :: (MonadThrow m, MonadIO m) => Text -> Text -> m ()
- getEnv :: (MonadThrow m, MonadIO m, IsString a) => Text -> m a
- envMaybe :: (MonadIO m, IsString a) => Text -> m (Maybe a)
- envRead :: MonadIO m => Reader a -> Text -> m (Maybe a)
- read :: Read a => Reader a
- newtype EnvironmentException = EnvVarNotFound Text
- type Reader a = IReader Text a
- decimal :: Integral a => Reader a
- signed :: Num a => Reader a -> Reader a
- hexadecimal :: Integral a => Reader a
- rational :: Fractional a => Reader a
- double :: Reader Double

# Documentation

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

Set value of environment variable.

Thorws `IOException`

.

`>>>`

Nothing`envMaybe "NAME"`

`>>>`

`setEnv "NAME" "Boris"`

`>>>`

Just "Boris"`envMaybe "NAME"`

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

Get value of environment variable.

Throws `EnvVarNotFound`

.

`>>>`

*** Exception: Could not find value of $NAME in environment.`getEnv "NAME"`

`>>>`

"/Users/d12frosted"`getEnv "HOME"`

read :: Read a => Reader a Source #

Generic reader for readable values.

Keep in mind that it's always better from performance view to use specific
Reader functions like

instead of this generic one.`decimal`

# Data types

newtype EnvironmentException Source #

Exceptions that can occur during reading the environment variable.

## Instances

Show EnvironmentException Source # | |

Defined in System.Environment.Extra showsPrec :: Int -> EnvironmentException -> ShowS # show :: EnvironmentException -> String # showList :: [EnvironmentException] -> ShowS # | |

Exception EnvironmentException Source # | |

# 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")

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.