Env

Parse the environment or die

Prints the help text and exits with EXIT_FAILURE on encountering a parse error.

>>> parse (header "env-parse 0.2.0") (var str "USER" (def "nobody"))

Try to parse the environment

Use this if simply dying on failure (the behavior of parse) is inadequate for your needs.

An environment parser

This represents a modification of the properties of a particular Parser. Combine them using the Monoid instance.

Parser's metadata

Set the help text header (it usually includes the application's name and version)

Set the short description

Set the help text footer (it usually includes examples)

Set the max info width.

Note: It will be set to 26 columns if a smaller value is passed.

An error handler

Given a variable name and an error value, try to produce a useful error message

The default error handler

The string to prepend to the name of every declared environment variable

Parse a particular variable from the environment

>>> var str "EDITOR" (def "vim" <> helpDef show)

Environment variable metadata

An environment variable's value parser. Use (<=<) and (>=>) to combine these

Create a Reader from a simple parser function

The trivial reader

The single character string reader

The reader that accepts only non-empty strings

The reader that splits a string into a list of strings consuming the separator.

The reader that uses the Read instance of the type

The default value of the variable

Note: specifying it means the parser won't ever fail.

Show the default value of the variable in help.

A flag that takes the active value if the environment variable is set and non-empty and the default value otherwise

Note: this parser never fails.

A simple boolean flag

Note: this parser never fails.

Flag metadata

A class of things that can have a help message attached to them

Attach help text to the variable

Mark the enclosed variables as sensitive to remove them from the environment once they've been parsed successfully.

A pretty-printed list of recognized environment variables suitable for usage messages

The type of errors returned by envparse's Readers. These fall into 3 categories:

• Variables that are unset in the environment.

• Variables whose value is empty.

• Variables whose value cannot be parsed.

The class of types that contain and can be constructed from the error returned from parsing unset variables.

The class of types that contain and can be constructed from the error returned from parsing variables whose value is empty.

The class of types that contain and can be constructed from the error returned from parsing variable whose value cannot be parsed.

One or none.

It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

>>> import Control.Monad.Except

>>> canFail = throwError "it failed" :: Except String Int>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

>>> runExcept $ canFail *> finalLeft "it failed"

>>> runExcept $ optional canFail *> finalRight 42

Right-to-left composition of Kleisli arrows. (>=>), with the arguments flipped.

Note how this operator resembles function composition (.):

(.)   ::            (b ->   c) -> (a ->   b) -> a ->   c
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c

Left-to-right composition of Kleisli arrows.

'(bs >=> cs) a' can be understood as the do expression

do b <- bs a
   cs b

or in terms of (>>=) as

bs a >>= cs

An associative operation.

Examples

>>> [1,2,3] <> [4,5,6][1,2,3,4,5,6]

>>> Just [1, 2, 3] <> Just [4, 5, 6]Just [1,2,3,4,5,6]

>>> putStr "Hello, " <> putStrLn "World!"Hello, World!

The sum of a collection of actions using (<|>), generalizing concat.

asum is just like msum, but generalised to Alternative.

Examples

Basic usage:

>>> asum [Just "Hello", Nothing, Just "World"]Just "Hello"

Try to parse a pure environment