-- 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 module Env.Internal.Val -- | A type isomorphic to Either with the accumulating -- Applicative instance. data Val e a Err :: e -> Val e a Ok :: a -> Val e a fromEither :: Either e a -> Val e a toEither :: Val e a -> Either e a instance (GHC.Classes.Eq e, GHC.Classes.Eq a) => GHC.Classes.Eq (Env.Internal.Val.Val e a) instance (GHC.Show.Show e, GHC.Show.Show a) => GHC.Show.Show (Env.Internal.Val.Val e a) instance GHC.Base.Functor (Env.Internal.Val.Val e) instance GHC.Base.Monoid e => GHC.Base.Applicative (Env.Internal.Val.Val e) instance GHC.Base.Monoid e => GHC.Base.Alternative (Env.Internal.Val.Val e) -- | Alt F is the free Alternative functor on F module Env.Internal.Free data Alt f a Nope :: Alt f a Pure :: a -> Alt f a Ap :: Alt f (a -> b) -> Alt f a -> Alt f b Alt :: Alt f a -> Alt f a -> Alt f a Lift :: f a -> Alt f a liftAlt :: f a -> Alt f a runAlt :: Alternative g => (forall x. f x -> g x) -> Alt f a -> g a foldAlt :: Monoid p => (forall a. f a -> p) -> Alt f b -> p hoistAlt :: Functor g => (forall a. f a -> g a) -> Alt f b -> Alt g b -- | Print the free structure inspect :: Alt f a -> String instance GHC.Classes.Eq m => GHC.Classes.Eq (Env.Internal.Free.Mon m a) instance GHC.Show.Show m => GHC.Show.Show (Env.Internal.Free.Mon m a) instance GHC.Base.Functor f => GHC.Base.Functor (Env.Internal.Free.Alt f) instance GHC.Base.Functor f => GHC.Base.Applicative (Env.Internal.Free.Alt f) instance GHC.Base.Functor f => GHC.Base.Alternative (Env.Internal.Free.Alt f) instance GHC.Base.Functor (Env.Internal.Free.Mon m) instance GHC.Base.Monoid m => GHC.Base.Applicative (Env.Internal.Free.Mon m) instance GHC.Base.Monoid m => GHC.Base.Alternative (Env.Internal.Free.Mon m) -- | 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 GHC.Base.Applicative (Env.Internal.Parser.Parser e) instance GHC.Base.Alternative (Env.Internal.Parser.Parser e) instance GHC.Base.Monoid (Env.Internal.Parser.Mod t a) instance Env.Internal.Parser.HasHelp Env.Internal.Parser.Var instance Env.Internal.Parser.HasHelp Env.Internal.Parser.Flag instance Env.Internal.Parser.HasKeep Env.Internal.Parser.Var instance Env.Internal.Parser.HasKeep Env.Internal.Parser.Flag 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: -- --
-- {-# 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 where record = fmap to (gr (State {statePrefix = "", stateCon = "", stateVar = ""}))
record :: Record e a => 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 where field name help = var auto name (foldMap help help)
field :: Field e 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.
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 (k :: BOX) a (tag :: k). GHC.Classes.Eq a => GHC.Classes.Eq (a Env.Generic.? tag)
instance forall (k :: BOX) a (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 Env.Generic.GRecord e a => Env.Generic.GRecord e (GHC.Generics.D1 c a)
instance Env.Generic.Field e a => Env.Generic.GRecord e (GHC.Generics.K1 i a)
instance (GHC.Generics.Constructor c, Env.Generic.GRecord e a) => Env.Generic.GRecord e (GHC.Generics.C1 c a)
instance (Env.Generic.GRecord e f, Env.Generic.GRecord e g) => Env.Generic.GRecord e (f GHC.Generics.:*: g)
instance (Env.Generic.GRecord e f, Env.Generic.GRecord e g) => Env.Generic.GRecord e (f GHC.Generics.:+: g)
instance (GHC.Generics.Selector c, Env.Generic.Type c ~ 'Env.Generic.Record, Env.Generic.GRecord e a) => Env.Generic.GRecord e (GHC.Generics.S1 c 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 (GHC.TypeLits.KnownSymbol tag, Env.Generic.Field e a) => Env.Generic.Field e (a Env.Generic.? tag)