Parser's metadata

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.

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

An environment parser

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

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

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 unset variables.

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

Flag metadata

Environment variable metadata

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

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

An associative operation.

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

Left-to-right composition of Kleisli arrows.

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

do b <- bs a
   cs b

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

The single character string reader

One or none.

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

Examples

>>> import Control.Monad.Except

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

>>> runExcept $ canFail *> final
Left "it failed"
>>> runExcept $ optional canFail *> final
Right 42

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

asum is just like msum, but generalised to Alternative.

Examples

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

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

Parse a particular variable from the environment

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

Set the help text footer (it usually includes examples)

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

The default value of the variable

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

Try to parse a pure environment

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

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

A simple boolean flag

Note: this parser never fails.

The trivial reader

The reader that accepts only non-empty strings

The reader that uses the Read instance of the type

Show the default value of the variable in help.

Attach help text to the variable

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

Set the short description

An error handler

The default error handler

Try to parse the environment

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

Designates the value of a parameter when a flag is not provided.

Designates the value of a parameter when a flag is provided.

Parse a simple flag

If the variable is present and non-empty in the environment, the active value is returned, otherwise the default is used.

>>> import Blammo.Logging (LogLevel(..))

>>> flag (Off LevelInfo) (On LevelDebug) "DEBUG" mempty `parsePure` [("DEBUG", "1")]
Right LevelDebug

>>> flag (Off LevelInfo) (On LevelDebug) "DEBUG" mempty `parsePure` [("DEBUG", "")]
Right LevelInfo

>>> flag (Off LevelInfo) (On LevelDebug) "DEBUG" mempty `parsePure` []
Right LevelInfo

N.B. only the empty string is falsey:

>>> flag (Off LevelInfo) (On LevelDebug) "DEBUG" mempty `parsePure` [("DEBUG", "false")]
Right LevelDebug

>>> flag (Off LevelInfo) (On LevelDebug) "DEBUG" mempty `parsePure` [("DEBUG", "no")]
Right LevelDebug

Represents a timeout in seconds or milliseconds

Create a Reader from a simple parser function

This is a building-block for other Readers

Read a time value using the given format

>>> var (time "%Y-%m-%d") "TIME" mempty `parsePure` [("TIME", "1985-02-12")]
Right 1985-02-12 00:00:00 UTC

>>> var (time "%Y-%m-%d") "TIME" mempty `parsePure` [("TIME", "10:00PM")]
Left [("TIME",UnreadError "unable to parse time as %Y-%m-%d: \"10:00PM\"")]

Read key-value pairs

>>> var keyValues "TAGS" mempty `parsePure` [("TAGS", "foo:bar,baz:bat")]
Right [("foo","bar"),("baz","bat")]

Value-less keys are not supported:

>>> var keyValues "TAGS" mempty `parsePure` [("TAGS", "foo,baz:bat")]
Left [("TAGS",UnreadError "Key foo has no value: \"foo\"")]

Nor are key-less values:

>>> var keyValues "TAGS" mempty `parsePure` [("TAGS", "foo:bar,:bat")]
Left [("TAGS",UnreadError "Value bat has no key: \":bat\"")]

Use splitOn then call the given Reader on each element

splitOnParse c pure == splitOn c

>>> var (splitOnParse @Error ',' nonempty) "X" mempty `parsePure` [("X", "a,b")]
Right ["a","b"]

>>> var (splitOnParse @Error ',' nonempty) "X" mempty `parsePure` [("X", ",,")]
Left [("X",EmptyError)]

Read a timeout value as seconds or milliseconds

>>> var timeout "TIMEOUT" mempty `parsePure` [("TIMEOUT", "10")]
Right (TimeoutSeconds 10)

>>> var timeout "TIMEOUT" mempty `parsePure` [("TIMEOUT", "10s")]
Right (TimeoutSeconds 10)

>>> var timeout "TIMEOUT" mempty `parsePure` [("TIMEOUT", "10ms")]
Right (TimeoutMilliseconds 10)

>>> var timeout "TIMEOUT" mempty `parsePure` [("TIMEOUT", "20m")]
Left [("TIMEOUT",UnreadError "must be {digits}(s|ms): \"20m\"")]

>>> var timeout "TIMEOUT" mempty `parsePure` [("TIMEOUT", "2m0")]
Left [("TIMEOUT",UnreadError "must be {digits}(s|ms): \"2m0\"")]