System.Console.Command

This is the main module of console-program. You can use it to build a console program, that parses the command line (and a configuration file), divides it into modes/commands, options and non-options, and executes the corresponding action from a tree of commands.

The main function is execute; provided with a tree of commands and a default configuration, it can be used as the main function.

A "mode" or "command" provides a mode of operation of your program. This allows a single executable to provide many different pieces of functionality. The first argument to the program (or the first few, if it has subcommands) determines which command should be executed. (darcs and cabal are examples of programs that make heavy use of modes.)

Options can be given in a configuration file, and on the command line. Commands specify which options apply to them (the applicableOptions field). Such option descriptions can be created by System.Console.Argument.option.

Options can have arguments, as in program --option=value, where value is the argument to option. These arguments have types, dictated by the particular option. These types are represented by a System.Console.Argument.Type.

A command can have also non-option arguments (plain arguments). These also have types. Create such commands using the function System.Console.Action.withArgument.

Documentation

type Commands setting = Tree (Command setting)

Commands s is a tree of commands. It represents the whole set of possible commands of a program.

data Command c

A Command s is an action, together with some descriptive information. The description, and lists of applicable options and non-options are used only to show usage information for the command. s is the type of settings that the action may use.

Constructors

Command

Fields

name :: String

This determines which command is executed, depending on the command line.

applicableNonOptions :: [String]

For usage info.

applicableOptions :: [OptDescr (Either String (Setting c))]

For usage info; also, the union of this field, over all commands in the command tree, determines which options will be recognised when parsing the configuration file and command line.

description :: String

For usage info.

action :: Action c

Using a command tree to construct a program

execute

Arguments

:: Configuration c

=> c

Default configuration.

-> Commands c

Tree of commands.

-> IO ()

Load the configuration file (if present), and run the action given on the command line. You may use this function, with appropriate arguments, as your main function.

Settings in the configuration file override the default configuration; settings on the command line override both.

showUsage :: Commands c -> IO ()

Print usage info for the program to stdout.

Configuration file

The configuration file is assumed to be in the user's home directory, and to be named ".foobar", where "foobar" is the name of the command at the root of the command tree (usually the name of the program).

Settings in this file are of the form option-name=option-value , see module Fez.Data.Conf for details. The format of the "option-value" part depends on the type of the option argument; see System.Console.Argument.