System.Console.GetOpt.Generics

getopt-generics tries to make it very simple to create command line argument parsers. An introductory example can be found in the README.

IO API

getArguments :: forall a. (Generic a, HasDatatypeInfo a, All2 Option (Code a)) => IO a

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

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.

Pure API

parseArguments :: forall a. (Generic a, HasDatatypeInfo a, All2 Option (Code a)) => String -> [Modifier] -> [String] -> Result a

Pure variant of getArguments. Also allows to declare Modifiers.

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

Eq a => Eq (Result a)

Ord a => Ord (Result a)

Show a => Show (Result a)

Customizing the CLI

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.

Instances

Eq Modifier

Ord Modifier

Show Modifier

deriveShortOptions :: (HasDatatypeInfo a, SingI (Code a)) => Proxy a -> [Modifier]

Derives AddShortOptions for all fields of the datatype that start with a unique character.

Available Field Types

class Option a where

Type class for all allowed field types.

Implementing custom instances to allow different types is possible. In the easiest case you just implement argumentType and parseArgument (the minimal complete definition).

(Unfortunately implementing instances for lists or Maybes of custom types is not very straightforward.)

Minimal complete definition

argumentType, parseArgument

Methods

argumentType :: Proxy a -> String

Name of the argument type, e.g. "bool" or "integer".

parseArgument :: String -> Maybe a

Parses a String into an argument. Returns Nothing on parse errors.

_toOption :: ArgDescr (FieldState a)

This is meant to be an internal function.

_emptyOption :: String -> FieldState a

This is meant to be an internal function.

_accumulate :: a -> a -> a

This is meant to be an internal function.

Instances

Option Bool

Option Int

Option String

Option [Int]

Option [String]

Option (Maybe Int)

Option (Maybe String)