ModuleCabal-3.12.1.0Haskell2010

Distribution.Simple.Command

This is to do with command line handling. The Cabal command line is organised into a number of named sub-commands (much like darcs). The CommandUI abstraction represents one of these sub-commands, with a name, description, a set of flags. Commands can be associated with actions and run. It handles some common stuff automatically, like the --help and command line completion flags. It is designed to allow other tools make derived commands. This feature is used heavily in cabal-install.

15 types
28 values

PackageCabal-3.12.1.0
Exports43
LanguageHaskell2010
LicenceBSD-3-Clause
SourceCommand.hs

Command interface

6 declarations

datadata CommandUI flags

Constructors

CommandUI
- commandName :: String
  The name of the command as it would be entered on the command line. For example "build".
- commandSynopsis :: String
  A short, one line description of the command to use in help texts.
- commandUsage :: String -> String
  A function that maps a program name to a usage summary for this command.
- commandDescription :: Maybe (String -> String)
  Additional explanation of the command to use in help texts.
- commandNotes :: Maybe (String -> String)
  Post-Usage notes and examples in help texts
- commandDefaultFlags :: flags
  Initial / empty flags
- commandOptions :: ShowOrParseArgs -> [OptionField flags]
  All the Option fields for this command

valuecommandShowOptions :: CommandUI flags -> flags -> [String]

Show flags in the standard long option command line format

datadata CommandParse flags

Constructors

CommandHelp (String -> String)
CommandList [String]
CommandErrors [String]
CommandReadyToGo flags

Instances1Functor

Functor CommandParseDefined in Cabal-3.12.1.0 · Distribution.Simple.Command

valuecommandParseArgs

:: CommandUI flags
-> Bool
Is the command a global or subcommand?
-> [String]
-> CommandParse (flags -> flags, [String])

Parse a bunch of command line arguments

valuegetNormalCommandDescriptions :: [Command action] -> [(String, String)]

Helper function for creating globalCommand description

valuehelpCommandUI :: CommandUI ()

Constructing commands

datadata ShowOrParseArgs

ShowArgs ParseArgs

valueusageDefault :: String -> String -> String

Default "usage" documentation text for commands.

valueusageAlternatives :: String -> [String] -> String -> String

Create "usage" documentation from a list of parameter configurations.

valuemkCommandUI

:: String
name
-> String
synopsis
-> [String]
usage alternatives
-> flags
initial/empty flags
-> (ShowOrParseArgs -> [OptionField flags])
options
-> CommandUI flags

Make a Command from standard GetOpt options.

valuehiddenCommand :: Command action -> Command action

Mark command as hidden. Hidden commands don't show up in the 'progname help' or 'progname --help' output.

Associating actions with commands

datadata Command action

valuecommandAddAction

:: CommandUI flags
-> flags -> [String] -> action
-> Command action

valuenoExtraFlags :: [String] -> IO ()

Utility function, many commands do not accept additional flags. This action fails with a helpful error message if the user supplies any extra.

Building lists of commands

datadata CommandType

NormalCommand HiddenCommand

datadata CommandSpec action

wraps a CommandUI together with a function that turns it into a Command. By hiding the type of flags for the UI allows construction of a list of all UIs at the top level of the program. That list can then be used for generation of manual page as well as for executing the selected command.

Constructors

forall flags. CommandSpec (CommandUI flags) (CommandUI flags -> Command action) CommandType

valuecommandFromSpec :: CommandSpec a -> Command a

Running commands

valuecommandsRun

:: CommandUI a
-> [Command action]
-> [String]
-> IO (CommandParse (a, CommandParse action))

valuecommandsRunWithFallback

:: CommandUI a
-> [Command action]
-> [Command action] -> String -> [String] -> IO (CommandParse action)
-> [String]
-> IO (CommandParse (a, CommandParse action))

valuedefaultCommandFallback

:: [Command action]
-> String
-> [String]
-> IO (CommandParse action)

Option Fields

2 declarations

datadata OptionField a

We usually have a data type for storing configuration values, where every field stores a configuration option, and the user sets the value either via command line flags or a configuration file. An individual OptionField models such a field, and we usually build a list of options associated to a configuration data type.

Constructors

OptionField
- optionName :: Name
- optionDescr :: [OptDescr a]

typetype Name = String

Constructing Option Fields

valueoption

:: SFlags
-> LFlags
-> Description
-> get
-> set
-> MkOptDescr get set a
-> OptionField a

Create an option taking a single OptDescr. No explicit Name is given for the Option, the name is the first LFlag given.

Example: option sf lf d get set * sf: Short option name, for example: ['d']. No hyphen permitted. * lf: Long option name, for example: ["debug"]. No hyphens permitted. * d: Description of the option, shown to the user in help messages. * get: Get the current value of the flag. * set: Set the value of the flag. Gets the current value of the flag as a parameter.

valuemultiOption

:: Name
-> get
-> set
-> [get -> set -> OptDescr a]
MkOptDescr constructors partially applied to flags and description.
-> OptionField a

Create an option taking several OptDescrs. You will have to give the flags and description individually to the OptDescr constructor.

Liftings & Projections

valueliftOption :: (b -> a) -> (a -> b -> b) -> OptionField a -> OptionField b

valueliftOptionL :: ALens' b a -> OptionField a -> OptionField b

Option Descriptions

6 declarations

datadata OptDescr a

An OptionField takes one or more OptDescrs, describing the command line interface for the field.

Constructors

ReqArg Description OptFlags ArgPlaceHolder (ReadE (a -> a)) (a -> [String])
OptArg Description OptFlags ArgPlaceHolder (ReadE (a -> a)) (String, a -> a) (a -> [Maybe String])
ChoiceOpt [(Description, OptFlags, a -> a, a -> Bool)]
BoolOpt Description OptFlags OptFlags (Bool -> a -> a) (a -> Maybe Bool)

typetype Description = String

typetype SFlags = [Char]

Short command line option strings

typetype LFlags = [String]

Long command line option strings

typetype OptFlags = (SFlags, LFlags)

typetype ArgPlaceHolder = String

OptDescr `smart` constructors

typetype MkOptDescr get set a = SFlags -> LFlags -> Description -> get -> set -> OptDescr a

valuereqArg

:: Monoid b
=> ArgPlaceHolder
-> ReadE b
-> b -> [String]
-> MkOptDescr (a -> b) (b -> a -> a) a

Create a string-valued command line interface. Usually called in the context of option or multiOption.

Example: reqArg ad mkflag showflag

ad: Placeholder shown to the user, e.g. FILES if files are expected parameters.
mkflag: How to parse the argument into the option.
showflag: If parsing goes wrong, display a useful error message to the user.

valuereqArg'

:: Monoid b
=> ArgPlaceHolder
-> String -> b
-> b -> [String]
-> MkOptDescr (a -> b) (b -> a -> a) a

(String -> a) variant of "reqArg"

valueoptArg

:: Monoid b
=> ArgPlaceHolder
-> ReadE b
-> (String, b)
-> b -> [Maybe String]
-> MkOptDescr (a -> b) (b -> a -> a) a

Create a string-valued command line interface with a default value.

valueoptArg'

:: Monoid b
=> ArgPlaceHolder
-> Maybe String -> b
-> b -> [Maybe String]
-> MkOptDescr (a -> b) (b -> a -> a) a

(String -> a) variant of "optArg"

valueoptArgDef'

:: Monoid b
=> ArgPlaceHolder
-> (String, Maybe String -> b)
-> b -> [Maybe String]
-> MkOptDescr (a -> b) (b -> a -> a) a

valuenoArg :: Eq b => b -> MkOptDescr (a -> b) (b -> a -> a) a

valueboolOpt

:: b -> Maybe Bool
-> Bool -> b
-> SFlags
-> SFlags
-> MkOptDescr (a -> b) (b -> a -> a) a

valueboolOpt'

:: b -> Maybe Bool
-> Bool -> b
-> OptFlags
-> OptFlags
-> MkOptDescr (a -> b) (b -> a -> a) a

valuechoiceOpt

:: Eq b
=> [(b, OptFlags, Description)]
-> MkOptDescr (a -> b) (b -> a -> a) a

create a Choice option

valuechoiceOptFromEnum :: (Bounded b, Enum b, Show b, Eq b) => MkOptDescr (a -> b) (b -> a -> a) a

create a Choice option out of an enumeration type. As long flags, the Show output is used. As short flags, the first character which does not conflict with a previous one is used.

Command interface

Constructors

Constructors

Constructing commands

Associating actions with commands

Building lists of commands

Constructors

Running commands

Option Fields

Constructors

Constructing Option Fields

Liftings & Projections

Option Descriptions

Constructors

OptDescr smart constructors

OptDescr `smart` constructors