Text.LambdaOptions

Documentation

runOptions :: Monad m => Options m () -> [String] -> m (Either OptionsError (m ()))

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.

data Options m a

A monad transformer for parsing options.

Instances

MonadTrans Options

Monad m => Monad (Options m)

Functor m => Functor (Options m)

(Monad m, Functor m) => Applicative (Options m)

MonadIO m => MonadIO (Options m)

data OptionsError

Contains information about what went wrong during an unsuccessful options parse.

Constructors

ParseFailed String Int Int

Contains (error-message) (begin-args-index) (end-args-index)

Instances

Show OptionsError

data Keyword

An option keyword, such as "--help"

Constructors

Keyword

Fields

kwNames :: [String]

All the aliases for this keyword.

kwArgText :: String

Text to describe the arguments to the option given by this keyword.

kwText :: String

Text to describe the function of the option given by this keyword.

Instances

Eq Keyword

Ord Keyword

Show Keyword

IsString Keyword

ToKeyword Keyword

Identiy mapping.

type OptionCallback m f = (Monad m, GetOpaqueParsers f, WrapCallback m f)

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 ()

addOption :: OptionCallback m f => Keyword -> f -> Options m ()

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.

newtype HelpDescription

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

Constructors

HelpDescription String

Instances

Parseable HelpDescription

Consumes nothing. Returns the options' help description. Never fails.

Typeable * HelpDescription

getHelpDescription :: Monad m => Options m a -> m String

Produces the help description given by the input options.

class ToKeyword a where

Convenience Keyword creation class.

Methods

toKeyword :: a -> Keyword

Instances

ToKeyword String

Used to create a Keyword with a single alias.

ToKeyword Keyword

Identiy mapping.

ToKeyword [String]

Used to create a Keyword with many (or no) aliases

kw :: ToKeyword a => a -> Keyword

Shorthand for toKeyword.

text :: Keyword -> String -> Keyword

Sets the kwText field in the keyword. Intended to be used infix.

kw "--quiet" `text` "Suppress message display."

argText :: Keyword -> String -> Keyword

Sets the kwArgText field in the keyword. Intended to be used infix:

kw "--directory" `argText` "DIR" `text` "Write files to DIR."

class Parseable a where

Class describing parseable values. Much like the Read class.

Methods

parse :: [String] -> (Maybe a, Int)

Given a sequence of strings, returns Nothing and the number of strings consumed if the parse failed. Otherwise, return Just the parsed value and the number of strings consumed. Element-wise, an entire string must be parsed in the sequence to be considered a successful parse.

Instances

Parseable Float

Parses a Float using its Read instance.

Parseable Int

Parses an Int using its Read instance.

Parseable String

Identity parser.

Parseable HelpDescription

Consumes nothing. Returns the options' help description. Never fails.

Parseable a => Parseable (Maybe a)

Greedily parses a single argument or no argument. Never fails.

Parseable a => Parseable (List a)

Greedily parses arguments item-wise. Never fails.

newtype List a

A simple wrapper over [a]. Used to avoid overlapping instances for Parseable [a] and Parseable String

Constructors

List [a]

Instances

Eq a => Eq (List a)

Ord a => Ord (List a)

Read a => Read (List a)

Show a => Show (List a)

Parseable a => Parseable (List a)

Greedily parses arguments item-wise. Never fails.

Typeable (* -> *) List