-- 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.4.1 -- | 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 [varKeep] :: 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 -- | The trivial reader str :: IsString s => Reader e s -- | 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 -- | A class of things that can be still kept in an environment when the -- parsing has been completed. class HasKeep t -- | Keep a variable. keep :: HasKeep t => Mod t a instance GHC.Base.Functor (Env.Internal.Parser.Parser e) instance GHC.Base.Functor (Env.Internal.Parser.VarF e) instance Env.Internal.Parser.HasKeep Env.Internal.Parser.Var instance Env.Internal.Parser.HasKeep Env.Internal.Parser.Flag 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 :: 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 -- | 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 :: (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 :: (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 -- | 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 -- | The trivial reader str :: IsString s => Reader e s -- | 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 -- | A class of things that can be still kept in an environment when the -- parsing has been completed. class HasKeep t -- | Keep a variable. keep :: HasKeep t => Mod t a -- | A pretty-printed list of recognized environment variables suitable for -- usage messages helpDoc :: Parser e a -> String -- | The type of errors returned by envparse's Readers. -- These fall into 3 categories: -- --
-- (.) :: (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 Kleisli composition of monads. (>=>) :: Monad m => a -> m b -> b -> m c -> a -> m c infixr 1 >=> -- | An associative operation. (<>) :: Semigroup a => a -> a -> a infixr 6 <> -- | The sum of a collection of actions, generalizing concat. -- -- 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 :: 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 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.Classes.Eq Env.Generic.State instance GHC.Show.Show Env.Generic.State 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.Integer.Type.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.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.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.Generics.MetaSel ('GHC.Base.Just x1) x2 x3 x4, Env.Generic.GRecord e a) => Env.Generic.GRecord e (GHC.Generics.S1 c a)