cmdargs

System.Console.CmdArgs.Explicit

Contents

- Running command lines
- Constructing command lines
- Displaying help
- Utilities for working with command line

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

- process :: Mode a -> [String] -> Either String a
- processArgs :: Mode a -> IO a
- processValue :: Mode a -> [String] -> a
- module System.Console.CmdArgs.Explicit.Type
- flagHelpSimple :: (a -> a) -> Flag a
- flagHelpFormat :: (HelpFormat -> TextFormat -> a -> a) -> Flag a
- flagVersion :: (a -> a) -> Flag a
- flagsVerbosity :: (Verbosity -> a -> a) -> [Flag a]
- module System.Console.CmdArgs.Explicit.Help
- module System.Console.CmdArgs.Explicit.SplitJoin
- data Complete
  - = CompleteValue String
  - | CompleteFile String FilePath
  - | CompleteDir String FilePath
- complete :: Mode a -> [String] -> (Int, Int) -> [Complete]

# Running command lines

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

Process a list of flags (usually obtained from `getArgs`) 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`` 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`) 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

module System.Console.CmdArgs.Explicit.Type

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

module System.Console.CmdArgs.Explicit.Help

# Utilities for working with command line

module System.Console.CmdArgs.Explicit.SplitJoin

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

Instances

Eq Complete |
Ord Complete |
Show Complete |

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.