-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A modern command-line parser for Haskell.
--
-- A modern command-line parser for Haskell.
@package lambda-options
@version 0.4.0.0
module Text.LambdaOptions
-- | Tries to parse the supplied options against input arguments. If
-- successful, parsed option callbacks are returned in Right.
-- Otherwise an OptionsError is returned in Left.
--
-- Example program:
--
--
-- import System.Environment
-- import Text.LambdaOptions
--
-- options :: Options IO ()
-- options = do
-- addOption (kw ["--help", "-h"] `text` "Display this help text.") $ \(HelpDescription desc) -> do
-- putStrLn "Usage:"
-- putStrLn desc
-- addOption (kw "--user" `argText` "NAME" `text` "Prints name.") $ \name -> do
-- putStrLn $ "Name:" ++ name
-- addOption (kw "--user" `argText` "NAME AGE" `text` "Prints name and age.") $ \name age -> do
-- putStrLn $ "Name:" ++ name ++ " Age:" ++ show (age :: Int)
--
-- main :: IO ()
-- main = do
-- args <- getArgs
-- result <- runOptions options args
-- case result of
-- Left (ParseFailed msg _ _) -> do
-- putStrLn msg
-- desc <- getHelpDescription options
-- putStrLn desc
-- Right action -> action
--
--
--
-- >>> example.exe --user John 20 --user Jane
-- Name:John Age:20
-- Name:Jane
--
-- >>> example.exe -h
-- Usage:
-- -h, --help Display this help text.
-- --user NAME Prints name.
-- --user NAME AGE Prints name and age.
--
-- >>> example.exe --user BadLuckBrian thirteen
-- Unknown option at index 2: `thirteen'
-- Usage:
-- -h, --help Display this help text.
-- --user NAME Prints name.
-- --user NAME AGE Prints name and age.
--
runOptions :: Monad m => Options m () -> [String] -> m (Either OptionsError (m ()))
-- | A monad transformer for parsing options.
data Options m a
-- | Contains information about what went wrong during an unsuccessful
-- options parse.
data OptionsError
-- | Contains (error-message) (begin-args-index)
-- (end-args-index)
ParseFailed :: String -> Int -> Int -> OptionsError
-- | An option keyword, such as "--help"
data Keyword
Keyword :: [String] -> String -> String -> Keyword
-- | All the aliases for this keyword.
kwNames :: Keyword -> [String]
-- | Text to describe the arguments to the option given by this keyword.
kwArgText :: Keyword -> String
-- | Text to describe the function of the option given by this keyword.
kwText :: Keyword -> String
-- | Describes the callback f to be called for a successfully
-- parsed option.
--
-- The function (or value) f can have any arity and ultimately
-- returns a value with type Monad m => m ()
--
-- Each of the callback's arguments must have a type t which
-- implements Parseable and Typeable.
--
-- Think of this as the following constraint synonym:
--
--
-- type OptionCallback m f = (Monad m, f ~ (Parseable t*, Typeable t*) => t0 -> t1 -> ... -> tN -> m ())
--
--
-- Example callbacks:
--
--
-- f0 = putStrLn "Option parsed!" :: IO ()
-- f1 = put :: String -> State String ()
-- f2 n = liftIO (print n) :: (MonadIO m) => Int -> m ()
-- f3 name year ratio = lift (print (name, year, ratio)) :: (MonadTrans m) => String -> Int -> Float -> m IO ()
--
type OptionCallback m f = (Monad m, GetOpaqueParsers f, WrapCallback m f)
-- | Adds the supplied option to the Options m () context.
--
-- If the keyword is matched and the types of the callback's parameters
-- can successfully be parsed, the callback is called with the parsed
-- arguments.
addOption :: OptionCallback m f => Keyword -> f -> Options m ()
-- | When used as a callback argument, this contains the help description
-- given by the added options.
--
-- Example:
--
--
-- addOption (kw ["--help", "-h"]) $ \(HelpDescription desc) -> do
-- putStrLn desc
--
newtype HelpDescription
HelpDescription :: String -> HelpDescription
-- | Produces the help description given by the input options.
getHelpDescription :: Monad m => Options m a -> m String
-- | Convenience Keyword creation class.
class ToKeyword a
toKeyword :: ToKeyword a => a -> Keyword
-- | Shorthand for toKeyword.
kw :: ToKeyword a => a -> Keyword
-- | Sets the kwText field in the keyword. Intended to be used
-- infix.
--
--
-- kw "--quiet" `text` "Suppress message display."
--
text :: Keyword -> String -> Keyword
-- | Sets the kwArgText field in the keyword. Intended to be used
-- infix:
--
--
-- kw "--directory" `argText` "DIR" `text` "Write files to DIR."
--
argText :: Keyword -> String -> Keyword
-- | Class describing parseable values. Much like the Read class.
class Parseable a
parse :: Parseable a => [String] -> (Maybe a, Int)
-- | A simple wrapper over [a]. Used to avoid overlapping
-- instances for Parseable [a] and Parseable String
newtype List a
List :: [a] -> List a
instance Typeable List
instance Typeable HelpDescription
instance Show a => Show (List a)
instance Read a => Read (List a)
instance Eq a => Eq (List a)
instance Ord a => Ord (List a)
instance Show Keyword
instance Eq Keyword
instance Ord Keyword
instance (Monad m, Functor m) => Applicative (Options m)
instance Functor m => Functor (Options m)
instance Monad m => Monad (Options m)
instance Monad m => MonadState (OptionsState m) (Options m)
instance MonadIO m => MonadIO (Options m)
instance Show OptionsError
instance Show FormattingConfig
instance Read FormattingConfig
instance Eq FormattingConfig
instance Ord FormattingConfig
instance MonadTrans Options
instance ToKeyword [String]
instance ToKeyword String
instance ToKeyword Keyword
instance IsString Keyword
instance (Typeable a, WrapCallback m b) => WrapCallback m (a -> b)
instance WrapCallback m (m ())
instance Monad m => GetOpaqueParsers (m ())
instance (Parseable a, Typeable a, GetOpaqueParsers b) => GetOpaqueParsers (a -> b)
instance Parseable HelpDescription
instance Parseable a => Parseable (List a)
instance Parseable a => Parseable (Maybe a)
instance Parseable Float
instance Parseable String
instance Parseable Int