Cabal-1.6.0.2: A framework for packaging Haskell software Contents Index

Distribution.Simple.Command Portability portable Maintainer cabal-devel@haskell.org

Contents Command interface Constructing commands Associating actions with commands Running commands Option Fields Constructing Option Fields Liftings & Projections Option Descriptions OptDescr smart constructors

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

data CommandUI flags = CommandUI { commandName :: String commandSynopsis :: String commandUsage :: String -> String commandDescription :: Maybe (String -> String) commandDefaultFlags :: flags commandOptions :: ShowOrParseArgs -> [OptionField flags] } commandShowOptions :: CommandUI flags -> flags -> [String] data ShowOrParseArgs = ShowArgs | ParseArgs makeCommand :: String -> String -> Maybe (String -> String) -> flags -> (ShowOrParseArgs -> [OptionField flags]) -> CommandUI flags data Command action commandAddAction :: CommandUI flags -> (flags -> [String] -> action) -> Command action noExtraFlags :: [String] -> IO () data CommandParse flags = CommandHelp (String -> String) | CommandList [String] | CommandErrors [String] | CommandReadyToGo flags commandsRun :: CommandUI a -> [Command action] -> [String] -> CommandParse (a, CommandParse action) data OptionField a = OptionField { optionName :: Name optionDescr :: [OptDescr a] } type Name = String option :: SFlags -> LFlags -> Description -> get -> set -> MkOptDescr get set a -> OptionField a multiOption :: Name -> get -> set -> [get -> set -> OptDescr a] -> OptionField a liftOption :: (b -> a) -> (a -> b -> b) -> OptionField a -> OptionField b viewAsFieldDescr :: OptionField a -> FieldDescr a data OptDescr a = ReqArg Description OptFlags ArgPlaceHolder (ReadE (a -> a)) (a -> [String]) | OptArg Description OptFlags ArgPlaceHolder (ReadE (a -> a)) (a -> a) (a -> [Maybe String]) | ChoiceOpt [(Description, OptFlags, a -> a, a -> Bool)] | BoolOpt Description OptFlags OptFlags (Bool -> a -> a) (a -> Maybe Bool) type Description = String type SFlags = [Char] type LFlags = [String] type OptFlags = (SFlags, LFlags) type ArgPlaceHolder = String 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 reqArg' :: Monoid b => ArgPlaceHolder -> (String -> b) -> (b -> [String]) -> MkOptDescr (a -> b) (b -> a -> a) a optArg :: Monoid b => ArgPlaceHolder -> ReadE b -> b -> (b -> [Maybe String]) -> MkOptDescr (a -> b) (b -> a -> a) a optArg' :: Monoid b => ArgPlaceHolder -> (Maybe String -> b) -> (b -> [Maybe String]) -> MkOptDescr (a -> b) (b -> a -> a) a 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 choiceOptFromEnum :: (Bounded b, Enum b, Show b, Eq b) => MkOptDescr (a -> b) (b -> a -> a) a

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

Constructing commands

data ShowOrParseArgs

Constructors ShowArgs ParseArgs

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

data CommandParse flags

Constructors CommandHelp (String -> String) CommandList [String] CommandErrors [String] CommandReadyToGo flags Instances Functor CommandParse

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 OptionField optionName :: Name optionDescr :: [OptDescr a]

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 ReqArg Description OptFlags ArgPlaceHolder (ReadE (a -> a)) (a -> [String]) OptArg Description OptFlags ArgPlaceHolder (ReadE (a -> a)) (a -> a) (a -> [Maybe String]) ChoiceOpt [(Description, OptFlags, a -> a, a -> Bool)] BoolOpt Description OptFlags OptFlags (Bool -> a -> a) (a -> Maybe Bool)

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.4.1