-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Parse environment variables -- -- 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 --@package envparse @version 0.6.0 -- | This module contains an extensible error infrastructure. -- -- Each kind of errors gets a separate type class which encodes a -- Prism (roughly a getter and a constructor). The -- Readers, then, have the constraints for precisely the set of -- errors they can return. module Env.Internal.Error -- | The type of errors returned by envparse's Readers. -- These fall into 3 categories: -- --
-- >>> var str "EDITOR" (def "vim" <> helpDef show) --var :: AsUnset e => Reader e a -> String -> Mod Var a -> Parser e a -- | Environment variable metadata data Var a Var :: Maybe String -> Maybe (a -> String) -> Maybe a -> Bool -> Var a [varHelp] :: Var a -> Maybe String [varHelpDef] :: Var a -> Maybe (a -> String) [varDef] :: Var a -> Maybe a [varSensitive] :: Var a -> Bool defaultVar :: Var a -- | An environment variable's value parser. Use (<=<) and -- (>=>) to combine these type Reader e a = String -> Either e a -- | Create a Reader from a simple parser function eitherReader :: AsUnread e => (String -> Either String a) -> Reader e a -- | The trivial reader str :: IsString s => Reader e s -- | The single character string reader char :: AsUnread e => Reader e Char -- | The reader that accepts only non-empty strings nonempty :: (AsEmpty e, IsString s) => Reader e s -- | The reader that splits a string into a list of strings consuming the -- separator. splitOn :: Char -> Reader e [String] -- | The reader that uses the Read instance of the type auto :: (AsUnread e, Read a) => Reader e a -- | The default value of the variable -- -- Note: specifying it means the parser won't ever fail. def :: a -> Mod Var a -- | Show the default value of the variable in help. helpDef :: (a -> String) -> Mod Var a -- | Use the Show instance to show the default value of the variable -- in help. showDef :: Show a => Mod Var 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. flag :: a -> a -> String -> Mod Flag a -> Parser e a -- | A simple boolean flag -- -- Note: this parser never fails. switch :: String -> Mod Flag Bool -> Parser e Bool -- | Flag metadata data Flag a -- | A class of things that can have a help message attached to them class HasHelp t -- | Attach help text to the variable help :: HasHelp t => String -> Mod t a -- | Mark the enclosed variables as sensitive to remove them from the -- environment once they've been parsed successfully. sensitive :: Parser e a -> Parser e a instance GHC.Base.Functor (Env.Internal.Parser.VarF e) instance GHC.Base.Functor (Env.Internal.Parser.Parser e) instance Env.Internal.Parser.HasHelp Env.Internal.Parser.Var instance Env.Internal.Parser.HasHelp Env.Internal.Parser.Flag instance GHC.Base.Semigroup (Env.Internal.Parser.Mod t a) instance GHC.Base.Monoid (Env.Internal.Parser.Mod t a) instance GHC.Base.Applicative (Env.Internal.Parser.Parser e) instance GHC.Base.Alternative (Env.Internal.Parser.Parser e) module Env.Internal.Help helpInfo :: Info e -> Parser e b -> [(String, e)] -> String -- | A pretty-printed list of recognized environment variables suitable for -- usage messages helpDoc :: Int -> Parser e a -> String -- | Parser's metadata data Info e -- | Given a variable name and an error value, try to produce a useful -- error message type ErrorHandler e = String -> e -> Maybe String defaultInfo :: Info Error -- | The default error handler defaultErrorHandler :: (AsUnset e, AsEmpty e, AsUnread e) => ErrorHandler e -- | Set the help text header (it usually includes the application's name -- and version) header :: String -> Info e -> Info e -- | Set the short description desc :: String -> Info e -> Info e -- | Set the help text footer (it usually includes examples) footer :: String -> Info e -> Info e -- | Set the max info width. -- -- Note: It will be set to 26 columns if a smaller value is -- passed. widthMax :: Int -> Info e -> Info e -- | An error handler handleError :: ErrorHandler e -> Info x -> Info e -- | 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 --module 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")) --parse :: AsUnset e => (Info Error -> Info e) -> Parser e a -> IO a -- | Try to parse the environment -- -- Use this if simply dying on failure (the behavior of parse) is -- inadequate for your needs. parseOr :: AsUnset e => (String -> IO a) -> (Info Error -> Info e) -> Parser e b -> IO (Either a b) -- | An environment parser data Parser e a -- | This represents a modification of the properties of a particular -- Parser. Combine them using the Monoid instance. data Mod t a -- | Parser's metadata data Info e -- | Set the help text header (it usually includes the application's name -- and version) header :: String -> Info e -> Info e -- | Set the short description desc :: String -> Info e -> Info e -- | Set the help text footer (it usually includes examples) footer :: String -> Info e -> Info e -- | Set the max info width. -- -- Note: It will be set to 26 columns if a smaller value is -- passed. widthMax :: Int -> Info e -> Info e -- | An error handler handleError :: ErrorHandler e -> Info x -> Info e -- | Given a variable name and an error value, try to produce a useful -- error message type ErrorHandler e = String -> e -> Maybe String -- | The default error handler defaultErrorHandler :: (AsUnset e, AsEmpty e, AsUnread e) => ErrorHandler e -- | The string to prepend to the name of every declared environment -- variable prefixed :: String -> Parser e a -> Parser e a -- | Parse a particular variable from the environment -- --
-- >>> var str "EDITOR" (def "vim" <> helpDef show) --var :: AsUnset e => Reader e a -> String -> Mod Var a -> Parser e a -- | Environment variable metadata data Var a -- | An environment variable's value parser. Use (<=<) and -- (>=>) to combine these type Reader e a = String -> Either e a -- | Create a Reader from a simple parser function eitherReader :: AsUnread e => (String -> Either String a) -> Reader e a -- | The trivial reader str :: IsString s => Reader e s -- | The single character string reader char :: AsUnread e => Reader e Char -- | The reader that accepts only non-empty strings nonempty :: (AsEmpty e, IsString s) => Reader e s -- | The reader that splits a string into a list of strings consuming the -- separator. splitOn :: Char -> Reader e [String] -- | The reader that uses the Read instance of the type auto :: (AsUnread e, Read a) => Reader e a -- | The default value of the variable -- -- Note: specifying it means the parser won't ever fail. def :: a -> Mod Var a -- | Show the default value of the variable in help. helpDef :: (a -> String) -> Mod Var 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. flag :: a -> a -> String -> Mod Flag a -> Parser e a -- | A simple boolean flag -- -- Note: this parser never fails. switch :: String -> Mod Flag Bool -> Parser e Bool -- | Flag metadata data Flag a -- | A class of things that can have a help message attached to them class HasHelp t -- | Attach help text to the variable help :: HasHelp t => String -> Mod t a -- | Mark the enclosed variables as sensitive to remove them from the -- environment once they've been parsed successfully. sensitive :: Parser e a -> Parser e a -- | A pretty-printed list of recognized environment variables suitable for -- usage messages helpDoc :: Int -> Parser e a -> String -- | The type of errors returned by envparse's Readers. -- These fall into 3 categories: -- --
-- >>> 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 *> final -- Left "it failed" -- -- >>> runExcept $ optional canFail *> final -- Right 42 --optional :: Alternative f => f a -> f (Maybe a) -- | 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 => (b -> m c) -> (a -> m b) -> 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 --(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c infixr 1 >=> -- | An associative operation. -- --
-- >>> [1,2,3] <> [4,5,6] -- [1,2,3,4,5,6] --(<>) :: Semigroup a => a -> a -> a infixr 6 <> -- | The sum of a collection of actions using (<|>), -- generalizing concat. -- -- asum is just like msum, but generalised to -- Alternative. -- --
-- >>> asum [Just "Hello", Nothing, Just "World"] -- Just "Hello" --asum :: (Foldable t, Alternative f) => t (f a) -> f a -- | Try to parse a pure environment parsePure :: AsUnset e => Parser e a -> [(String, String)] -> Either [(String, e)] a -- | Using the Generic facility, this module can derive -- Parsers automatically. -- -- If you have a simple record: -- --
-- {-# LANGUAGE DeriveGeneric #-}
-- {-# LANGUAGE MultiParamTypeClasses #-}
--
-- import Env
-- import Env.Generic
--
-- data Hello = Hello
-- { name :: String
-- , count :: Int
-- , quiet :: Bool
-- } deriving (Show, Eq, Generic)
--
-- instance Record Error Hello
--
-- main :: IO ()
-- main = do
-- hello <- Env.parse (header "envparse example") record
-- print (hello :: Hello)
--
--
-- The generic implementation of the record method translates
-- named fields to field parsers:
--
--
-- % NAME=bob COUNT=3 runhaskell -isrc example/Generic0.hs
-- Hello {name = "bob", count = 3, quiet = False}
--
--
-- If you want to adorn the ugly default help message, augment the fields
-- with descriptions:
--
--
-- {-# LANGUAGE DataKinds #-}
-- {-# LANGUAGE DeriveGeneric #-}
-- {-# LANGUAGE MultiParamTypeClasses #-}
-- {-# LANGUAGE TypeOperators #-}
--
-- import Env
-- import Env.Generic
--
-- data Hello = Hello
-- { name :: String ? "Whom shoud I greet?"
-- , count :: Int ? "How many times to greet them?"
-- , quiet :: Bool ? "Should I be quiet instead?"
-- } deriving (Show, Eq, Generic)
--
-- instance Record Error Hello
--
-- main :: IO ()
-- main = do
-- hello <- Env.parse (header "envparse example") record
-- print (hello :: Hello)
--
--
-- -- % runhaskell -isrc example/Generic1.hs -- envparse example -- -- Available environment variables: -- -- COUNT How many times to greet them? -- NAME Whom shoud I greet? -- QUIET Should I be quiet instead? -- -- Parsing errors: -- -- COUNT is unset -- NAME is unset ---- -- Note that this has an effect of wrapping the values in the Help -- constructor: -- --
-- % NAME=bob COUNT=3 QUIET=YES runhaskell -isrc example/Generic1.hs
-- Hello {name = Help {unHelp = "bob"}, count = Help {unHelp = 3}, quiet = Help {unHelp = True}}
--
module Env.Generic
-- | Given a Record e a instance, a value of the type a
-- can be parsed from the environment. If the parsing fails, a value of
-- an error type e is returned.
--
-- The record method has a default implementation for any type
-- that has a Generic instance. If you need to choose a concrete
-- type for e, the default error type Error is a good
-- candidate. Otherwise, the features you'll use in your parsers will
-- naturally guide GHC to compute the set of required constraints on
-- e.
class Record e a
record :: Record e a => Parser e a
record :: (Record e a, r ~ Rep a, Generic a, GRecord e r) => Parser e a
-- | Given a Field e a instance, a value of the type a
-- can be parsed from an environment variable. If the parsing fails, a
-- value of an error type e is returned.
--
-- The field method has a default implementation for any type that
-- has a Read instance. If you need to choose a concrete type for
-- e, the default error type Error is a good candidate.
-- Otherwise, the features you'll use in your parsers will naturally
-- guide GHC to compute the set of required constraints on e.
--
-- The annotated instances do not use the default implementation.
class Field e a
field :: Field e a => String -> Maybe String -> Parser e a
field :: (Field e a, AsUnset e, AsUnread e, Read a) => String -> Maybe String -> Parser e a
-- | A field annotation.
--
-- If you annotate a record field with a Symbol literal (that
-- is, a statically known type level string) the derivation machinery
-- will use the literal in the help message.
--
-- Please remember that the values of the annotated fields are wrapped in
-- the Help constructor.
newtype a ? tag
Help :: a -> (?) a tag
[unHelp] :: (?) a tag -> a
-- | Representable types of kind *. This class is derivable in GHC
-- with the DeriveGeneric flag on.
--
-- A Generic instance must satisfy the following laws:
--
-- -- from . to ≡ id -- to . from ≡ id --class () => Generic a instance GHC.Classes.Eq Env.Generic.State instance GHC.Show.Show Env.Generic.State instance Data.Traversable.Traversable ((Env.Generic.?) a) instance Data.Foldable.Foldable ((Env.Generic.?) a) instance GHC.Base.Functor ((Env.Generic.?) a) instance forall a k (tag :: k). GHC.Classes.Eq a => GHC.Classes.Eq (a Env.Generic.? tag) instance forall a k (tag :: k). GHC.Show.Show a => GHC.Show.Show (a Env.Generic.? tag) instance (GHC.TypeLits.KnownSymbol tag, Env.Generic.Field e a) => Env.Generic.Field e (a Env.Generic.? tag) instance Env.Generic.Field e a => Env.Generic.GRecord e (GHC.Generics.K1 i a) instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Types.Int instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Int.Int8 instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Int.Int16 instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Int.Int32 instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Int.Int64 instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Num.Integer.Integer instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Types.Word instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Word.Word8 instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Word.Word16 instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Word.Word32 instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Word.Word64 instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Num.Natural.Natural instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Types.Float instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Types.Double instance (Env.Generic.Field e a, Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e (GHC.Maybe.Maybe a) instance Env.Internal.Error.AsUnset e => Env.Generic.Field e GHC.Base.String instance (Env.Internal.Error.AsUnset e, Env.Internal.Error.AsUnread e) => Env.Generic.Field e GHC.Types.Char instance Env.Generic.Field e GHC.Types.Bool instance forall k e (a :: k -> *) (c :: GHC.Generics.Meta). Env.Generic.GRecord e a => Env.Generic.GRecord e (GHC.Generics.D1 c a) instance forall k (c :: GHC.Generics.Meta) e (a :: k -> *). (GHC.Generics.Constructor c, Env.Generic.GRecord e a) => Env.Generic.GRecord e (GHC.Generics.C1 c a) instance forall k e (f :: k -> *) (g :: k -> *). (Env.Generic.GRecord e f, Env.Generic.GRecord e g) => Env.Generic.GRecord e (f GHC.Generics.:*: g) instance forall k e (f :: k -> *) (g :: k -> *). (Env.Generic.GRecord e f, Env.Generic.GRecord e g) => Env.Generic.GRecord e (f GHC.Generics.:+: g) instance forall k (c :: GHC.Generics.Meta) (x1 :: GHC.Types.Symbol) (x2 :: GHC.Generics.SourceUnpackedness) (x3 :: GHC.Generics.SourceStrictness) (x4 :: GHC.Generics.DecidedStrictness) e (a :: k -> *). (GHC.Generics.Selector c, c GHC.Types.~ 'GHC.Generics.MetaSel ('GHC.Maybe.Just x1) x2 x3 x4, Env.Generic.GRecord e a) => Env.Generic.GRecord e (GHC.Generics.S1 c a)