-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Parse environment variables
--   
@package envparse
@version 0.2.2


-- | Here's a simple example of a program that uses <tt>envparse</tt>'s
--   parser:
--   
--   <pre>
--   module Main (main) where
--   
--   import Control.Monad (unless)
--   import Env
--   
--   data Hello = Hello { name :: String, quiet :: Bool }
--   
--   hello :: IO Hello
--   hello = Env.<a>parse</a> (<a>header</a> "envparse example") $
--     Hello &lt;$&gt; <a>var</a> (<a>str</a> &lt;=&lt; <a>nonempty</a>) "NAME"  (<a>help</a> "Target for the greeting")
--           &lt;*&gt; <a>switch</a>                 "QUIET" (<a>help</a> "Whether to actually print the greeting")
--   
--   main :: IO ()
--   main = do
--     Hello { name, quiet } &lt;- hello
--     unless quiet $
--       putStrLn ("Hello, " ++ name ++ "!")
--   </pre>
--   
--   The <tt>NAME</tt> environment variable is mandatory and contains the
--   name of the person to greet. <tt>QUIET</tt>, on the other hand, is an
--   optional boolean flag, false by default, that decides whether the
--   greeting should be silent.
--   
--   If the <tt>NAME</tt> variable is undefined in the environment then
--   running the program will result in the following help text:
--   
--   <pre>
--   envparse example
--   
--   Available environment variables:
--   
--     NAME                   Target for the greeting
--     QUIET                  Whether to actually print the
--                            greeting
--   
--   Parsing errors:
--   
--     NAME is unset
--   </pre>
module Env

-- | Parse the environment or die
--   
--   Prints the help text and exits with <tt>EXIT_FAILURE</tt> on
--   encountering a parse error.
--   
--   <pre>
--   &gt;&gt;&gt; parse (<a>header</a> "env-parse 0.2.0") (<a>var</a> <a>str</a> "USER" (<a>def</a> "nobody"))
--   </pre>
parse :: Mod Info a -> Parser a -> IO a

-- | Try to parse the environment
--   
--   Use this if simply dying on failure (the behavior of <a>parse</a>) is
--   inadequate for your needs.
parseOr :: (String -> IO a) -> Mod Info b -> Parser b -> IO (Either a b)

-- | An environment parser
data Parser a

-- | This represents a modification of the properties of a particular
--   <a>Parser</a>. Combine them using the <a>Monoid</a> instance.
data Mod t a

-- | Parser's metadata
data Info a

-- | A help text header (it usually includes an application name and
--   version)
header :: String -> Mod Info a

-- | A short program description
desc :: String -> Mod Info a

-- | A help text footer (it usually includes examples)
footer :: String -> Mod Info a

-- | The string to prepend to the name of every declared environment
--   variable
prefixed :: String -> Parser a -> Parser a

-- | Parse a particular variable from the environment
--   
--   <pre>
--   &gt;&gt;&gt; var <a>str</a> "EDITOR" (<a>def</a> "vim" &lt;&gt; <a>helpDef</a> show)
--   </pre>
var :: Reader a -> String -> Mod Var a -> Parser a

-- | Environment variable metadata
data Var a

-- | An environment variable's value parser. Use <tt>(&lt;=&lt;)</tt> and
--   <tt>(&gt;=&gt;)</tt> to combine these
type Reader a = String -> Either String a

-- | The trivial reader
str :: IsString s => Reader s

-- | The reader that accepts only non-empty strings
nonempty :: IsString s => Reader s

-- | The reader that uses the <a>Read</a> instance of the type
auto :: Read a => Reader a

-- | The default value of the variable
--   
--   <i>Note:</i> specifying it means the parser won't ever fail.
def :: a -> Mod Var a

-- | Show the default value of the variable in the help text
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
--   
--   <i>Note:</i> this parser never fails.
flag :: a -> a -> String -> Mod Flag a -> Parser a

-- | A simple boolean <a>flag</a>
--   
--   <i>Note:</i> the same caveats apply.
switch :: String -> Mod Flag Bool -> Parser 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 pretty-printed list of recognized environment variables suitable for
--   usage messages.
helpDoc :: Parser a -> String

-- | Lift a value.
pure :: Applicative f => forall a. a -> f a

-- | An infix synonym for <a>fmap</a>.
(<$>) :: Functor f => (a -> b) -> f a -> f b

-- | Sequential application.
(<*>) :: Applicative f => forall a b. f (a -> b) -> f a -> f b

-- | Sequence actions, discarding the value of the first argument.
(*>) :: Applicative f => forall a b. f a -> f b -> f b

-- | Sequence actions, discarding the value of the second argument.
(<*) :: Applicative f => forall a b. f a -> f b -> f a

-- | One or none.
optional :: Alternative f => f a -> f (Maybe a)

-- | The identity of <a>&lt;|&gt;</a>
empty :: Alternative f => forall a. f a

-- | An associative binary operation
(<|>) :: Alternative f => forall a. f a -> f a -> f a

-- | Right-to-left Kleisli composition of monads.
--   <tt>(<a>&gt;=&gt;</a>)</tt>, with the arguments flipped
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c

-- | Left-to-right Kleisli composition of monads.
(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c

-- | An infix synonym for <a>mappend</a>.
--   
--   <i>Since: 4.5.0.0</i>
(<>) :: Monoid m => m -> m -> m

-- | Identity of <a>mappend</a>
mempty :: Monoid a => a

-- | Fold a list using the monoid. For most types, the default definition
--   for <a>mconcat</a> will be used, but the function is included in the
--   class definition so that an optimized version can be provided for
--   specific types.
mconcat :: Monoid a => [a] -> a

-- | The sum of a collection of actions, generalizing <a>concat</a>.
asum :: (Foldable t, Alternative f) => t (f a) -> f a

-- | Try to parse a pure environment
parsePure :: Mod Info a -> Parser a -> [(String, String)] -> Either String a