cmdargs

Safe HaskellSafe-Infered

System.Console.CmdArgs.Explicit

Contents

Description

This module constructs command lines. You may either use the helper functions (flagNone, flagOpt, mode etc.) or construct the type directly. These types are intended to give all the necessary power to the person constructing a command line parser.

For people constructing simpler command line parsers, the module System.Console.CmdArgs.Implicit may be more appropriate.

As an example of a parser:

    arguments :: Mode [(String,String)]
    arguments = mode "explicit" [] "Explicit sample program" (flagArg (upd "file") "FILE")
        [flagOpt "world" ["hello","h"] (upd "world") "WHO" "World argument"
        ,flagReq ["greeting","g"] (upd "greeting") "MSG" "Greeting to give"
        ,flagHelpSimple (("help",""):)]
        where upd msg x v = Right $ (msg,x):v

And this can be invoked by:

    main = do
        xs <- processArgs arguments
        if ("help","") `elem` xs then
            print $ helpText [] HelpFormatDefault arguments
         else
            print xs

Groups: The Group structure allows flags/modes to be grouped for the purpose of displaying help. When processing command lines, the group structure is ignored.

Modes: The Explicit module allows multiple mode programs by placing additional modes in modeGroupModes. Every mode is allowed sub-modes, and thus multiple levels of mode may be created. Given a mode x with sub-modes xs, if the first argument corresponds to the name of a sub-mode, then that sub-mode will be applied. If not, then the arguments will be processed by mode x. Consequently, if you wish to force the user to explicitly enter a mode, simply give sub-modes, and leave modeArgs as Nothing. Alternatively, if you want one sub-mode to be selected by default, place all it's flags both in the sub-mode and the outer mode.

Parsing rules: Command lines are parsed as per most GNU programs. Short arguments single letter flags start with -, longer flags start with --, and everything else is considered an argument. Anything after -- alone is considered to be an argument. For example:

 -f --flag argument1 -- --argument2

This command line passes one single letter flag (f), one longer flag (flag) and two arguments (argument1 and --argument2).

Synopsis

Running command lines

process :: Mode a -> [String] -> Either String a

Process a list of flags (usually obtained from getArgs/expandArgsAt) with a mode. Returns Left and an error message if the command line fails to parse, or Right and the associated value.

processArgs :: Mode a -> IO a

Process the flags obtained by getArgs and expandArgsAt with a mode. Displays an error and exits with failure if the command line fails to parse, or returns the associated value. Implemented in terms of process. This function makes use of the following environment variables:

  • $CMDARGS_COMPLETE - causes the program to produce completions using complete, then exit. Completions are based on the result of getArgs, the index of the current argument is taken from $CMDARGS_COMPLETE (set it to - to complete the last argument), and the index within that argument is taken from $CMDARGS_COMPLETE_POS (if set).
  • $CMDARGS_HELPER/$CMDARGS_HELPER_PROG - uses the helper mechanism for entering command line programs as described in System.Console.CmdArgs.Helper.

processValue :: Mode a -> [String] -> a

Process a list of flags (usually obtained from getArgs and expandArgsAt) with a mode. Displays an error and exits with failure if the command line fails to parse, or returns the associated value. Implemeneted in terms of process. This function does not take account of any environment variables that may be set (see processArgs).

Constructing command lines

flagHelpSimple :: (a -> a) -> Flag a

Create a help flag triggered by -?/--help.

flagHelpFormat :: (HelpFormat -> TextFormat -> a -> a) -> Flag a

Create a help flag triggered by -?/--help. The user may optionally modify help by specifying the format, such as:

 --help=all          - help for all modes
 --help=html         - help in HTML format
 --help=100          - wrap the text at 100 characters
 --help=100,one      - full text wrapped at 100 characters

flagVersion :: (a -> a) -> Flag a

Create a version flag triggered by -V/--version.

flagsVerbosity :: (Verbosity -> a -> a) -> [Flag a]

Create verbosity flags triggered by -v/--verbose and -q/--quiet

Displaying help

Utilities for working with command lines

data Complete

How to complete a command line option. The Show instance is suitable for parsing from shell scripts.

Constructors

CompleteValue String

Complete to a particular value

CompleteFile String FilePath

Complete to a prefix, and a file

CompleteDir String FilePath

Complete to a prefix, and a directory

complete

Arguments

:: Mode a

Mode specifying which arguments are allowed

-> [String]

Arguments the user has already typed

-> (Int, Int)

0-based index of the argument they are currently on, and the position in that argument

-> [Complete] 

Given a current state, return the set of commands you could type now, in preference order.