System.Console.GetOpt.Generics

Simple IO API

withCli :: WithCli main => main -> IO ()

withCli converts an IO operation into a program with a proper CLI. Retrieves command line arguments through withArgs. main (the given IO operation) can have arbitrarily many parameters provided all parameters have instances for HasArguments.

May throw the following exceptions:

• ExitFailure 1 in case of invalid options. Error messages are written to stderr.
• ExitSuccess in case --help is given. (ExitSuccess behaves like a normal exception, except that -- if uncaught -- the process will exit with exit-code 0.) Help output is written to stdout.

Example:

 import WithCli

 main :: IO ()
 main = withCli run

 run :: String -> Int -> Bool -> IO ()
 run s i b = print (s, i, b)

Using the above program in a shell:

 $ program foo 42 true
 ("foo",42,True)
 $ program --help
 program [OPTIONS] STRING INTEGER BOOL
   -h  --help  show help and exit
 $ program foo 42 bar
 cannot parse as BOOL: bar
 # exit-code 1
 $ program
 missing argument of type STRING
 missing argument of type INTEGER
 missing argument of type BOOL
 # exit-code 1
 $ program foo 42 yes bar
 unknown argument: bar
 # exit-code 1

class WithCli main

Everything that can be used as a main function with withCli needs to have an instance of WithCli. You shouldn't need to implement your own instances.

Instances

WithCli (IO ())

(HasArguments a, WithCli rest) => WithCli (a -> rest)

class HasArguments a

Everything that can be used as an argument to your main function (see withCli) needs to have a HasArguments instance.

HasArguments also allows to conjure up instances for record types to create more complex command line interfaces. Here's an example:

 {-# LANGUAGE DeriveAnyClass #-}
 {-# LANGUAGE DeriveGeneric #-}

 import WithCli

 data Options
   = Options {
     port :: Int,
     daemonize :: Bool,
     config :: Maybe FilePath
   }
   deriving (Show, Generic, HasArguments)

 main :: IO ()
 main = withCli run

 run :: Options -> IO ()
 run = print

In a shell this program behaves like this:

 $ program --port 8080 --config some/path
 Options {port = 8080, daemonize = False, config = Just "some/path"}
 $ program  --port 8080 --daemonize
 Options {port = 8080, daemonize = True, config = Nothing}
 $ program --port foo
 cannot parse as INTEGER: foo
 # exit-code 1
 $ program
 missing option: --port=INTEGER
 # exit-code 1
 $ program --help
 program [OPTIONS]
       --port=INTEGER
       --daemonize
       --config=STRING (optional)
   -h  --help                      show help and exit

Instances

HasArguments Bool

HasArguments Double

HasArguments Float

HasArguments Int

HasArguments String

Argument a => HasArguments [a]

Argument a => HasArguments (Maybe a)

(HasArguments a, HasArguments b) => HasArguments (a, b)

(HasArguments a, HasArguments b, HasArguments c) => HasArguments (a, b, c)

class Argument a where

Argument is a typeclass for things that can be parsed as atomic values from single command line arguments, e.g. strings (and filenames) and numbers.

Occasionally you might want to declare your own instance for additional type safety and for providing a more informative command argument type. Here's an example:

 {-# LANGUAGE DeriveDataTypeable #-}

 import WithCli

 data File = File FilePath
   deriving (Show, Typeable)

 instance Argument File where
   argumentType Proxy = "custom-file-type"
   parseArgument f = Just (File f)

 instance HasArguments File where
   argumentsParser = atomicArgumentsParser

 main :: IO ()
 main = withCli run

 run :: File -> IO ()
 run = print

And this is how the above program behaves:

 $ program --help
 program [OPTIONS] custom-file-type
   -h  --help  show help and exit
 $ program some/file
 File "some/file"

Methods

argumentType :: Proxy a -> String

parseArgument :: String -> Maybe a

Instances

Argument Double

Argument Float

Argument Int

Argument Integer

Argument String

Customizing the CLI

withCliModified :: WithCli main => [Modifier] -> main -> IO ()

This is a variant of withCli that allows to tweak the generated command line interface by providing a list of Modifiers.

data Modifier

Modifiers can be used to customize the command line parser.

Constructors

AddShortOption String Char

AddShortOption fieldName c adds the Char c as a short option for the field addressed by fieldName.

RenameOption String String

RenameOption fieldName customName renames the option generated through the fieldName by customName.

RenameOptions (String -> Maybe String)

RenameOptions f renames all options with the given functions. In case the function returns Nothing the original field name is used.

Can be used together with stripPrefix.

UseForPositionalArguments String String

UseForPositionalArguments fieldName argumentType fills the field addressed by fieldName with the positional arguments (i.e. arguments that don't correspond to a flag). The field has to have type [String].

argumentType is used as the type of the positional arguments in the help output.

AddOptionHelp String String

AddOptionHelp fieldName helpText adds a help text for the option fieldName.

AddVersionFlag String

AddVersionFlag version adds a --version flag.

IO API

getArguments :: forall a. (Generic a, GTo a, GDatatypeInfo a, All2 HasArguments (GCode a)) => IO a

Parses command line arguments (gotten from withArgs) and returns the parsed value. This function should be enough for simple use-cases.

Throws the same exceptions as withCli.

Here's an example:

 {-# LANGUAGE DeriveGeneric #-}

 module RecordType where

 import System.Console.GetOpt.Generics

 -- All you have to do is to define a type and derive an instance for Generic:

 data Options
   = Options {
     port :: Int,
     daemonize :: Bool,
     config :: Maybe FilePath
   }
   deriving (Show, Generic)

 -- Then you can use `getArguments` to create a command-line argument parser:

 main :: IO ()
 main = do
   options <- getArguments
   print (options :: Options)

And this is how the above program behaves:

 $ program --port 8080 --config some/path
 Options {port = 8080, daemonize = False, config = Just "some/path"}
 $ program  --port 8080 --daemonize
 Options {port = 8080, daemonize = True, config = Nothing}
 $ program --port foo
 cannot parse as INTEGER: foo
 # exit-code 1
 $ program
 missing option: --port=INTEGER
 # exit-code 1
 $ program --help
 program [OPTIONS]
       --port=INTEGER
       --daemonize
       --config=STRING (optional)
   -h  --help                      show help and exit

modifiedGetArguments :: forall a. (Generic a, GTo a, GDatatypeInfo a, All2 HasArguments (GCode a)) => [Modifier] -> IO a

Like getArguments but allows you to pass in Modifiers.

Pure API

parseArguments

Arguments

:: (Generic a, GTo a, GDatatypeInfo a, All2 HasArguments (GCode a))

=> String

Name of the program (e.g. from getProgName).

-> [Modifier]

List of Modifiers to manually tweak the command line interface.

-> [String]

List of command line arguments to parse (e.g. from getArgs).

-> Result a

Pure variant of modifiedGetArguments.

Does not throw any exceptions.

data Result a

Type to wrap results from the pure parsing functions.

Constructors

Success a

The CLI was used correctly and a value of type a was successfully constructed.

Errors [String]

The CLI was used incorrectly. The Result contains a list of error messages.

It can also happen that the data type you're trying to use isn't supported. See the README for details.

OutputAndExit String

The CLI was used with --help. The Result contains the help message.

Instances

Monad Result

Functor Result

Applicative Result

Eq a => Eq (Result a)

Ord a => Ord (Result a)

Show a => Show (Result a)

Re-exports

class Generic a

Representable types of kind *. This class is derivable in GHC with the DeriveGeneric flag on.

Minimal complete definition

from, to

Instances

Generic Bool

Generic Char

Generic Double

Generic Float

Generic Int

Generic Ordering

Generic ()

Generic All

Generic Any

Generic Arity

Generic Fixity

Generic Associativity

Generic [a]

Generic (U1 p)

Generic (Par1 p)

Generic (ZipList a)

Generic (Dual a)

Generic (Endo a)

Generic (Sum a)

Generic (Product a)

Generic (First a)

Generic (Last a)

Generic (Maybe a)

Generic (I a)

Generic (Either a b)

Generic (Rec1 f p)

Generic (a, b)

Generic (Const a b)

Generic (WrappedMonad m a)

Generic (Proxy * t)

Generic (K1 i c p)

Generic ((:+:) f g p)

Generic ((:*:) f g p)

Generic ((:.:) f g p)

Generic (a, b, c)

Generic (WrappedArrow a b c)

Generic (Alt k f a)

Generic (K k a b)

Generic (M1 i c f p)

Generic (a, b, c, d)

Generic (a, b, c, d, e)

Generic ((:.:) l k f g p)

Generic (a, b, c, d, e, f)

Generic (a, b, c, d, e, f, g)

type GDatatypeInfo a = GDatatypeInfo' (Rep a)

Constraint for the class that computes gdatatypeInfo.

type GCode a = ToSumCode (Rep a) ([] [*])

Compute the SOP code of a datatype.

This requires that Rep is defined, which in turn requires that the type has a Generic (from module GHC.Generics) instance.

This is the default definition for Code. For more info, see Generic.

class (AllF [k] (All k f) xss, SListI [k] xss) => All2 f xss

Require a constraint for every element of a list of lists.

If you have a datatype that is indexed over a type-level list of lists, then you can use All2 to indicate that all elements of the innert lists must satisfy a given constraint.

Example: The constraint

All2 Eq '[ '[ Int ], '[ Bool, Char ] ]

is equivalent to the constraint

(Eq Int, Eq Bool, Eq Char)

Example: A type signature such as

f :: All2 Eq xss => SOP I xs -> ...

means that f can assume that all elements of the sum of product satisfy Eq.

Instances

(AllF [k] (All k f) xss, SListI [k] xss) => All2 k f xss