![](haskell_icon.gif) | Cabal-1.10.1.0: A framework for packaging Haskell software | Contents | Index |
|
Distribution.Simple.Command | Portability | portable | Maintainer | cabal-devel@haskell.org |
|
|
|
|
|
Description |
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.
|
|
Synopsis |
|
|
|
|
Command interface
|
|
data 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 | The useage line summary for this command
| commandDescription :: Maybe (String -> String) | Additional explanation of the command to use in help texts.
| commandDefaultFlags :: flags | Initial / empty flags
| commandOptions :: ShowOrParseArgs -> [OptionField flags] | All the Option fields for this command
|
|
|
|
|
commandShowOptions :: CommandUI flags -> flags -> [String] |
Show flags in the standard long option command line format
|
|
data CommandParse flags |
Constructors | CommandHelp (String -> String) | | CommandList [String] | | CommandErrors [String] | | CommandReadyToGo flags | |
| Instances | |
|
|
commandParseArgs |
:: CommandUI flags | | -> Bool | Is the command a global or subcommand?
| -> [String] | | -> CommandParse (flags -> flags, [String]) | | Parse a bunch of command line arguments
|
|
|
Constructing commands
|
|
data ShowOrParseArgs |
|
|
makeCommand |
:: String | name
| -> String | short description
| -> Maybe (String -> String) | long description
| -> flags | initial/empty flags
| -> ShowOrParseArgs -> [OptionField flags] | options
| -> CommandUI flags | | Make a Command from standard GetOpt options.
|
|
|
Associating actions with commands
|
|
data Command action |
|
commandAddAction :: CommandUI flags -> (flags -> [String] -> action) -> Command action |
|
noExtraFlags :: [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.
|
|
Running commands
|
|
commandsRun :: CommandUI a -> [Command action] -> [String] -> CommandParse (a, CommandParse action) |
|
Option Fields
|
|
data OptionField a |
We usually have a datatype 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 datatype.
| Constructors | |
|
|
type Name = String |
|
Constructing Option Fields
|
|
option :: 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.
|
|
multiOption |
:: 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
|
|
liftOption :: (b -> a) -> (a -> b -> b) -> OptionField a -> OptionField b |
|
viewAsFieldDescr :: OptionField a -> FieldDescr a |
to view as a FieldDescr, we sort the list of interfaces (Req > Bool > Choice > Opt) and consider only the first one.
|
|
Option Descriptions
|
|
data OptDescr a |
An OptionField takes one or more OptDescrs, describing the command line interface for the field.
| Constructors | |
|
|
type Description = String |
|
type SFlags = [Char] |
Short command line option strings
|
|
type LFlags = [String] |
Long command line option strings
|
|
type OptFlags = (SFlags, LFlags) |
|
type ArgPlaceHolder = String |
|
OptDescr smart constructors
|
|
type MkOptDescr get set a = SFlags -> LFlags -> Description -> get -> set -> OptDescr a |
|
reqArg :: Monoid b => ArgPlaceHolder -> ReadE b -> (b -> [String]) -> MkOptDescr (a -> b) (b -> a -> a) a |
Create a string-valued command line interface.
|
|
reqArg' :: Monoid b => ArgPlaceHolder -> (String -> b) -> (b -> [String]) -> MkOptDescr (a -> b) (b -> a -> a) a |
(String -> a) variant of reqArg
|
|
optArg :: Monoid b => ArgPlaceHolder -> ReadE b -> b -> (b -> [Maybe String]) -> MkOptDescr (a -> b) (b -> a -> a) a |
Create a string-valued command line interface with a default value.
|
|
optArg' :: Monoid b => ArgPlaceHolder -> (Maybe String -> b) -> (b -> [Maybe String]) -> MkOptDescr (a -> b) (b -> a -> a) a |
(String -> a) variant of optArg
|
|
noArg :: (Eq b, Monoid b) => b -> MkOptDescr (a -> b) (b -> a -> a) a |
|
boolOpt :: (b -> Maybe Bool) -> (Bool -> b) -> SFlags -> SFlags -> MkOptDescr (a -> b) (b -> a -> a) a |
|
boolOpt' :: (b -> Maybe Bool) -> (Bool -> b) -> OptFlags -> OptFlags -> MkOptDescr (a -> b) (b -> a -> a) a |
|
choiceOpt :: Eq b => [(b, OptFlags, Description)] -> MkOptDescr (a -> b) (b -> a -> a) a |
create a Choice option
|
|
choiceOptFromEnum :: (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.
|
|
Produced by Haddock version 2.6.1 |