Env

Here's a simple example of a program that uses envparse's parser:

module Main (main) where

import Control.Monad (unless)
import Env

data Hello = Hello { name :: String, quiet :: Bool }

hello :: IO Hello
hello = Env.parse (header "envparse example") $
  Hello <$> var (str <=< nonempty) "NAME"  (help "Target for the greeting")
        <*> switch                 "QUIET" (help "Whether to actually print the greeting")

main :: IO ()
main = do
  Hello {name, quiet} <- hello
  unless quiet $
    putStrLn ("Hello, " ++ name ++ "!")

The NAME environment variable is mandatory and contains the name of the person to greet. QUIET, on the other hand, is an optional boolean flag, false by default, that decides whether the greeting should be silent.

If the NAME variable is undefined in the environment then running the program will result in the following help text:

envparse example

Available environment variables:

  NAME                   Target for the greeting
  QUIET                  Whether to actually print the
                         greeting

Parsing errors:

  NAME is unset

Documentation

parse :: AsUnset e => (Info Error -> Info e) -> Parser e a -> IO a

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

parseOr :: AsUnset e => (String -> IO a) -> (Info Error -> Info e) -> Parser e b -> IO (Either a b)

Try to parse the environment

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

data Parser e a

An environment parser

Instances

Functor (Parser e)

Defined in Env.Internal.Parser

Methods

fmap :: (a -> b) -> Parser e a -> Parser e b

(<$) :: a -> Parser e b -> Parser e a

Applicative (Parser e)

Defined in Env.Internal.Parser

Methods

pure :: a -> Parser e a

(<*>) :: Parser e (a -> b) -> Parser e a -> Parser e b

liftA2 :: (a -> b -> c) -> Parser e a -> Parser e b -> Parser e c

(*>) :: Parser e a -> Parser e b -> Parser e b

(<*) :: Parser e a -> Parser e b -> Parser e a

Alternative (Parser e)

Defined in Env.Internal.Parser

Methods

empty :: Parser e a

(<|>) :: Parser e a -> Parser e a -> Parser e a

some :: Parser e a -> Parser e [a]

many :: Parser e a -> Parser e [a]

data Mod t a

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

Instances

Semigroup (Mod t a)

Defined in Env.Internal.Parser

Methods

(<>) :: Mod t a -> Mod t a -> Mod t a

sconcat :: NonEmpty (Mod t a) -> Mod t a

stimes :: Integral b => b -> Mod t a -> Mod t a

Monoid (Mod t a)

Defined in Env.Internal.Parser

Methods

mempty :: Mod t a

mappend :: Mod t a -> Mod t a -> Mod t a

mconcat :: [Mod t a] -> Mod t a

data Info e

Parser's metadata

header :: String -> Info e -> Info e

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

desc :: String -> Info e -> Info e

Set the short description

footer :: String -> Info e -> Info e

Set the help text footer (it usually includes examples)

handleError :: ErrorHandler e -> Info x -> Info e

An error handler

type ErrorHandler e = String -> e -> Maybe String

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

defaultErrorHandler :: (AsUnset e, AsEmpty e, AsUnread e) => ErrorHandler e

The default error handler

prefixed :: String -> Parser e a -> Parser e a

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

var :: AsUnset e => Reader e a -> String -> Mod Var a -> Parser e a

Parse a particular variable from the environment

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

data Var a

Environment variable metadata

Instances

HasHelp Var

Defined in Env.Internal.Parser

Methods

setHelp :: String -> Var a -> Var a

type Reader e a = String -> Either e a

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

str :: IsString s => Reader e s

The trivial reader

char :: AsUnread e => Reader e Char

The single character string reader

nonempty :: (AsEmpty e, IsString s) => Reader e s

The reader that accepts only non-empty strings

splitOn :: Char -> Reader e [String]

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

auto :: (AsUnread e, Read a) => Reader e a

The reader that uses the Read instance of the type

def :: a -> Mod Var a

The default value of the variable

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

helpDef :: (a -> String) -> Mod Var a

Show the default value of the variable in help.

flag

Arguments

:: a

default value

-> a

active value

-> String

-> Mod Flag a

-> Parser e a

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.

switch :: String -> Mod Flag Bool -> Parser e Bool

A simple boolean flag

Note: this parser never fails.

data Flag a

Flag metadata

Instances

HasHelp Flag

Defined in Env.Internal.Parser

Methods

setHelp :: String -> Flag a -> Flag a

class HasHelp t

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

Minimal complete definition

setHelp

Instances

HasHelp Flag

Defined in Env.Internal.Parser

Methods

setHelp :: String -> Flag a -> Flag a

HasHelp Var

Defined in Env.Internal.Parser

Methods

setHelp :: String -> Var a -> Var a

help :: HasHelp t => String -> Mod t a

Attach help text to the variable

sensitive :: Parser e a -> Parser e a

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

helpDoc :: Parser e a -> String

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

data Error

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.

Constructors

UnsetError

EmptyError

UnreadError String

Instances

Eq Error

Defined in Env.Internal.Error

Methods

(==) :: Error -> Error -> Bool

(/=) :: Error -> Error -> Bool

Show Error

Defined in Env.Internal.Error

Methods

showsPrec :: Int -> Error -> ShowS

show :: Error -> String

showList :: [Error] -> ShowS

AsUnread Error

Defined in Env.Internal.Error

Methods

unread :: String -> Error

tryUnread :: Error -> Maybe String

AsEmpty Error

Defined in Env.Internal.Error

Methods

empty :: Error

tryEmpty :: Error -> Maybe ()

AsUnset Error

Defined in Env.Internal.Error

Methods

unset :: Error

tryUnset :: Error -> Maybe ()

class AsUnset e where

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

Methods

unset :: e

tryUnset :: e -> Maybe ()

Instances

AsUnset Error

Defined in Env.Internal.Error

Methods

unset :: Error

tryUnset :: Error -> Maybe ()

class AsEmpty e where

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

Methods

empty :: e

tryEmpty :: e -> Maybe ()

Instances

AsEmpty Error

Defined in Env.Internal.Error

Methods

empty :: Error

tryEmpty :: Error -> Maybe ()

class AsUnread e where

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

Methods

unread :: String -> e

tryUnread :: e -> Maybe String

Instances

AsUnread Error

Defined in Env.Internal.Error

Methods

unread :: String -> Error

tryUnread :: Error -> Maybe String

Re-exports

External functions that may be useful to the consumer of the library

optional :: Alternative f => f a -> f (Maybe a)

One or none.

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

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

(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c infixr 1

Left-to-right composition of Kleisli arrows.

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

do b <- bs a
   cs b

(<>) :: Semigroup a => a -> a -> a infixr 6

An associative operation.

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

asum :: (Foldable t, Alternative f) => t (f a) -> f a

The sum of a collection of actions, generalizing concat.

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

Testing

Utilities to test—without dabbling in IO—that your parsers do what you want them to do

parsePure :: AsUnset e => Parser e a -> [(String, String)] -> Either [(String, e)] a

Try to parse a pure environment