diff --git a/console-program.cabal b/console-program.cabal --- a/console-program.cabal +++ b/console-program.cabal @@ -1,5 +1,5 @@ Name: console-program -Version: 0.2.0.0 +Version: 0.2.0.1 Cabal-Version: >= 1.6 License: BSD3 Author: Arie Peterson diff --git a/src/System/Console/Action/Internal.hs b/src/System/Console/Action/Internal.hs --- a/src/System/Console/Action/Internal.hs +++ b/src/System/Console/Action/Internal.hs @@ -15,23 +15,23 @@ -- | An @Action s@ is an @IO@ action, which may take arguments --- (\"non-options\") from the command line, and which may use settings +-- (\"non-options\") from the command line, and which may use a configuration -- of type @s@. -data Action s +data Action c = Action { - run :: [String] -> s -> IO () + run :: [String] -> c -> IO () } -- | A simple action, taking no argument. -simple :: IO () -> Action s +simple :: IO () -> Action c simple = Action . const . const -- | Create an action that takes an argument (non-option). -- -- The type of argument is specified by the first parameter; such values can -- be obtained from the module "System.Console.Argument". -withArgument :: Argument.Type x -> (x -> Action s) -> Action s +withArgument :: Argument.Type x -> (x -> Action c) -> Action c withArgument at f = Action g where g (x : xs) = either (const . (>> exitFailure) . putStrLn) -- Show errors and exit. @@ -39,7 +39,7 @@ (Argument.parser at x) g [] = const $ putStrLn ("Error: missing argument of type " ++ Argument.name at) >> exitFailure - -- | Create an action that depends on the program configuration (determined - -- by the configuration file and command line arguments). -usingConfiguration :: (s -> Action s) -> Action s +-- | Create an action that depends on the program configuration (determined +-- by the configuration file and command line arguments). +usingConfiguration :: (c -> Action c) -> Action c usingConfiguration f = Action (\ nonOptions settings -> run (f settings) nonOptions settings) diff --git a/src/System/Console/Argument.hs b/src/System/Console/Argument.hs --- a/src/System/Console/Argument.hs +++ b/src/System/Console/Argument.hs @@ -24,19 +24,32 @@ import qualified Text.Parsec.Extra as P - -- | A @Type a@ represents the type of an option or argument. +-- | A @Type a@ represents the type of an option or argument. +-- +-- Further below you can find some common types of option arguments. data Type a = Type { parser :: String -> Either String a + -- ^ Parse the option argument into a value (@Right@) or signal a parsing + -- error (@Left@). , name :: String + -- ^ A name for this type of option argument (for usage info). , defaultValue :: Maybe a + -- ^ The default value, when the option occurs without option argument. + -- @Nothing@ means that an argument is required for this type of option. + -- + -- Note that this may be different from the corresponding value in the default + -- configuration (the first argument of 'System.Console.Command.execute'); + -- the latter is what you get when this option does not occur at all in the + -- configuration file or command line. } instance Functor Type where fmap f t = t { parser = fmap f . parser t, defaultValue = fmap f (defaultValue t) } --- | Create an option description. +-- | Create an option description. You need this to describe the options your +-- command uses; see 'System.Console.Command.Command'. option :: (a -> s) -- ^ Function that creates a setting (of type @s@) from the option argument. -> [Char] -- ^ List of short option characters. diff --git a/src/System/Console/Command.hs b/src/System/Console/Command.hs --- a/src/System/Console/Command.hs +++ b/src/System/Console/Command.hs @@ -1,3 +1,27 @@ +-- | 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'. module System.Console.Command ( Commands @@ -8,7 +32,7 @@ , showUsage -- * Configuration file - -- $doc + -- $configfile ) where @@ -45,10 +69,16 @@ data Command c = Command { - name :: String -- ^ This determines which command is executed, depending on the command line. - , applicableNonOptions :: [String] -- ^ For usage info. - , applicableOptions :: [GetOpt.OptDescr (Either String (Options.Setting c))] -- ^ For usage info. The union of this field, over all commands in the command tree, also determines which options will be recognised. - , description :: String -- ^ For usage info. + name :: String + -- ^ This determines which command is executed, depending on the command line. + , applicableNonOptions :: [String] + -- ^ For usage info. + , applicableOptions :: [GetOpt.OptDescr (Either String (Options.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.Action c }