-- 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.5.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
-- case runOptions options args of
-- Left (ParseFailed msg _ _) -> do
-- putStrLn msg
-- putStrLn $ getHelpDescription options
-- 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] -> Either OptionsError (m ())
-- | A monad 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 -> 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 Applicative (Options m)
instance Functor (Options m)
instance Monad (Options m)
instance MonadState (OptionsState m) (Options m)
instance Show OptionsError
instance Show FormattingConfig
instance Read FormattingConfig
instance Eq FormattingConfig
instance Ord FormattingConfig
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