console-program 0.2.0.0 → 0.2.0.1

raw patch · 4 files changed

+59/−16 lines, 4 files

Files

• console-program.cabal +1/−1
• src/System/Console/Action/Internal.hs +8/−8
• src/System/Console/Argument.hs +15/−2
• src/System/Console/Command.hs +35/−5

@@ -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

@@ -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)

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

@@ -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     }