Console.Options

Options parsing using a simple DSL approach.

Using this API, your program should have the following shape:

defaultMain $ do
    f1 <- flag ..
    f2 <- argument ..
    action $ \toParam ->
        something (toParam f1) (toParam f2) ..

You can also define subcommand using:

defaultMain $ do
    subcommand "foo" $ do
       <..flags & parameters definitions...>
       action $ \toParam -> <..IO-action..>
    subcommand "bar" $ do
       <..flags & parameters definitions...>
       action $ \toParam -> <..IO-action..>

Example:

main = defaultMain $ do
    programName "test-cli"
    programDescription "test CLI program"
    flagA    <- flag $ FlagShort 'a' <> FlagLong "aaa"
    allArgs  <- remainingArguments "FILE"
    action $ \toParam -> do
        putStrLn $ "using flag A : " ++ show (toParam flagA)
        putStrLn $ "args: " ++ show (toParam allArgs)

Running

defaultMain :: OptionDesc (IO ()) () -> IO ()

run parse options description on the action

to be able to specify the arguments manually (e.g. pre-handling), you can use defaultMainWith. >defaultMain dsl = getArgs >>= defaultMainWith dsl

defaultMainWith :: OptionDesc (IO ()) () -> [String] -> IO ()

same as defaultMain, but with the argument

parseOptions :: OptionDesc r () -> [String] -> (ProgramDesc r, OptionRes r)

This is only useful when you want to handle all the description parsing manually and need to not automatically execute any action or help/error handling.

Used for testing the parser.

data OptionRes r

return value of the option parser. only needed when using parseOptions directly

Constructors

OptionSuccess Params (Action r)

OptionHelp

OptionError String

OptionInvalid String

data OptionDesc r a

Option description Monad

Instances

Monad (OptionDesc r)

Defined in Console.Options.Monad

Methods

(>>=) :: OptionDesc r a -> (a -> OptionDesc r b) -> OptionDesc r b

(>>) :: OptionDesc r a -> OptionDesc r b -> OptionDesc r b

return :: a -> OptionDesc r a

fail :: String -> OptionDesc r a

Functor (OptionDesc r)

Defined in Console.Options.Monad

Methods

fmap :: (a -> b) -> OptionDesc r a -> OptionDesc r b

(<$) :: a -> OptionDesc r b -> OptionDesc r a

Applicative (OptionDesc r)

Defined in Console.Options.Monad

Methods

pure :: a -> OptionDesc r a

(<*>) :: OptionDesc r (a -> b) -> OptionDesc r a -> OptionDesc r b

liftA2 :: (a -> b -> c) -> OptionDesc r a -> OptionDesc r b -> OptionDesc r c

(*>) :: OptionDesc r a -> OptionDesc r b -> OptionDesc r b

(<*) :: OptionDesc r a -> OptionDesc r b -> OptionDesc r a

MonadState (OptionDesc r)

Defined in Console.Options.Monad

Associated Types

type State (OptionDesc r) :: Type

Methods

withState :: (State (OptionDesc r) -> (a, State (OptionDesc r))) -> OptionDesc r a

type State (OptionDesc r)

Defined in Console.Options.Monad

type State (OptionDesc r)

Description

programName :: String -> OptionDesc r ()

Set the program name

default is the result of base's getProgName

programVersion :: Version -> OptionDesc r ()

Set the program version

programDescription :: String -> OptionDesc r ()

Set the program description

command :: String -> OptionDesc r () -> OptionDesc r ()

Create a new sub command

data FlagFrag

Fragment of flag definition.

Use the monoid approach to concat flags together e.g. > FlagShort o <> FlagLong "option"

Constructors

FlagShort Char

short option e.g. '-a'

FlagLong String

long option e.g. "--aaaa"

FlagDescription String

description of this flag. | FlagDefault String

Instances

Eq FlagFrag

Defined in Console.Options.Flags

Methods

(==) :: FlagFrag -> FlagFrag -> Bool

(/=) :: FlagFrag -> FlagFrag -> Bool

Show FlagFrag

Defined in Console.Options.Flags

Methods

showsPrec :: Int -> FlagFrag -> ShowS

show :: FlagFrag -> String

showList :: [FlagFrag] -> ShowS

Semigroup FlagFrag

Defined in Console.Options.Flags

Methods

(<>) :: FlagFrag -> FlagFrag -> FlagFrag

sconcat :: NonEmpty FlagFrag -> FlagFrag

stimes :: Integral b => b -> FlagFrag -> FlagFrag

Monoid FlagFrag

Defined in Console.Options.Flags

Methods

mempty :: FlagFrag

mappend :: FlagFrag -> FlagFrag -> FlagFrag

mconcat :: [FlagFrag] -> FlagFrag

flag :: FlagFrag -> OptionDesc r (Flag Bool)

Flag option either of the form -short or --long

for flag that expect a value (optional or mandatory), uses flagArg

flagParam :: FlagFrag -> FlagParser a -> OptionDesc r (FlagParam a)

Flag option either of the form -short or --long

for flag that doesn't have parameter, use flag

flagMany :: OptionDesc r (FlagParam a) -> OptionDesc r (FlagMany a)

Apply on a flagParam to turn into a flag that can be invoked multiples, creating a list of values in the action.

argument :: String -> ValueParser a -> OptionDesc r (Arg a)

An unnamed positional argument

For now, argument in a point of tree that contains sub trees will be ignored. TODO: record a warning or add a strict mode (for developping the CLI) and error.

remainingArguments :: String -> OptionDesc r (ArgRemaining [String])

All the remaining position arguments

This is useful for example for a program that takes an unbounded list of files as parameters.

action :: Action r -> OptionDesc r ()

Set the action to run in this command

description :: String -> OptionDesc r ()

Set the description for a command

type Action r = (forall a p. Param p => p a -> Ret p a) -> r

Represent a program to run

Arguments

type ValueParser a = String -> Either String a

A parser for a value. In case parsing failed Left should be returned.

data FlagParser a

A parser for a flag's value, either optional or required.

Constructors

FlagRequired (ValueParser a)

flag value parser with a required parameter.

FlagOptional a (ValueParser a)

Optional flag value parser: Default value if not present to a

data Flag a

Represent a boolean flag (present / not present)

data FlagLevel a

Represent a Flag that can be called multiples times and will increase a counter.

data FlagParam a

Represent a Flag with an optional or required value associated

data FlagMany a

Represent a Flag with optional or required value that can be added multiple times

data Arg a

A positional argument

data ArgRemaining a

All the remaining positional arguments

data Params

A dictionary of parsed flags and arguments

paramsFlags :: Params -> [(Nid, Maybe String)]

return all the flags and their unique identifier. internal only

getParams :: Param p => Params -> forall a. p a -> Ret p a

get the value associated with a specific Param (either a Flag, FlagParam, or an Arg)