+ CmdArgs is a Haskell library for defining command line parsers. The two features that make it a better choice than the standard getopt library are: +
++ A very simple example of a command line processor is: +
+
+data Sample = Sample {hello :: String} deriving (Show, Data, Typeable)
+
+sample = Sample{hello = def &= help "World argument" &= opt "world"}
+ &= summary "Sample v1"
+
+main = print =<< cmdArgs sample
+
++ Despite being very concise, this processor is already fairly well featured: +
+
+$ runhaskell Sample.hs --hello=world
+Sample {hello = "world"}
+
+$ runhaskell Sample.hs --help
+Sample v1, (C) Neil Mitchell 2009
+
+sample [FLAG]
+
+ -? --help[=FORMAT] Show usage information (optional format)
+ -V --version Show version information
+ -v --verbose Higher verbosity
+ -q --quiet Lower verbosity
+ -h --hello=VALUE World argument (default=world)
+
+
++ The rest of this document explains how to write the "hello world" of command line processors, then how to extend it with features into a complex command line processor. Finally this document gives three samples, which the cmdargs program can run. The three samples are: +
++ For each example you are encouraged to look at it's source (see the darcs repo, or the bottom of this document) and run it (try cmdargs hlint --help). The HLint program is fairly standard in terms of it's argument processing, and previously used the System.Console.GetOpt library. Using GetOpt required 90 lines and a reasonable amount of duplication. Using CmdArgs the code requires 30 lines, and the logic is much simpler. +
++ Thanks to Kevin Quick for substantial patches, and additional code contributions from Sebastian Fischer and Daniel Schoepe. +
+ + ++ The following code defines a complete command line argument processor: +
+ + {-# LANGUAGE DeriveDataTypeable #-} + module Sample where + import System.Console.CmdArgs + + data Sample = Sample {hello :: String} + deriving (Show, Data, Typeable) + + sample = Sample{hello = def} + + main = print =<< cmdArgs sample + ++ To use the CmdArgs library there are three steps: +
++ Now we have a reasonably functional command line argument processor. Some sample interactions are: +
+
+$ runhaskell Sample.hs --hello=world
+Sample {hello = "world"}
+
+$ runhaskell Sample.hs --version
+The sample program
+
+$ runhaskell Sample.hs --help
+The sample program
+
+sample [OPTIONS]
+
+ -? --help Display help message
+ -V --version Print version information
+ -h --hello=ITEM
+
++ CmdArgs uses defaults to automatically infer a command line parser for a value, and provides annotations to override any of the the defaults. CmdArgs automatically supports --help and --version flags, and optionally supports verbosity flags. +
+ ++ In order to control the behaviour we can add attributes. For example to add an attribute specifying the help text for the --hello argument we can write: +
+
+sample = Sample{hello = def &= help "Who to say hello to"}
+
++ We can add additional attributes, for example to specify the type of the value expected by hello: +
+
+sample = Sample {hello = def &= help "Who to say hello to" &= typ "WORLD"}
+
++ Now when running --help the final line is: +
++ -h --hello=WORLD Who to say hello to ++
+ There are many more attributes, detailed in the Haddock documentation. +
+ + ++ To specify a program with multiple modes, similar to darcs, we can supply a data type with multiple constructors, for example: +
+ + + data Sample = Hello {whom :: String} + | Goodbye + deriving (Show, Data, Typeable) + + hello = Hello{whom = def} + goodbye = Goodbye + + main = print =<< cmdArgs (modes [hello,goodbye]) + ++ Compared to the first example, we now have multiple constructors, and a sample value for each constructor is passed to cmdArgs. Some sample interactions with this command line are: +
+
+$ runhaskell Sample.hs hello --whom=world
+Hello {whom = "world"}
+
+$ runhaskell Sample.hs goodbye
+Goodbye
+
+$ runhaskell Sample.hs --help
+The sample program
+
+sample [OPTIONS]
+
+ Common flags
+ -? --help Display help message
+ -V --version Print version information
+
+sample hello [OPTIONS]
+
+ -w --whom=ITEM
+
+sample goodbye [OPTIONS]
+
++ As before, the behaviour can be customised using attributes. +
+ ++ For each of the following examples we first explain the purpose of the program, then give the source code, and finally the output of --help=HTML. The programs are intended to show sample uses of CmdArgs, and are available to experiment with through cmdargs progname. +
+ ++ The HLint program analyses a list of files, using various options to control the analysis. The command line processing is simple, but a few interesting points are: +
+
+{-# LANGUAGE DeriveDataTypeable #-}
+module HLint where
+import System.Console.CmdArgs
+
+data HLint = HLint
+ {report :: [FilePath]
+ ,hint :: [FilePath]
+ ,color :: Bool
+ ,ignore_ :: [String]
+ ,show_ :: Bool
+ ,extension :: [String]
+ ,language :: [String]
+ ,utf8 :: Bool
+ ,encoding :: String
+ ,find :: [FilePath]
+ ,test_ :: Bool
+ ,datadir :: [FilePath]
+ ,cpp_define :: [String]
+ ,cpp_include :: [FilePath]
+ ,files :: [FilePath]
+ }
+ deriving (Data,Typeable,Show,Eq)
+
+hlint = HLint
+ {report = def &= opt "report.html" &= typFile &= help "Generate a report in HTML"
+ ,hint = def &= typFile &= help "Hint/ignore file to use"
+ ,color = def &= name "c" &= name "colour" &= help "Color the output (requires ANSI terminal)"
+ ,ignore_ = def &= typ "MESSAGE" &= help "Ignore a particular hint"
+ ,show_ = def &= help "Show all ignored ideas"
+ ,extension = def &= typ "EXT" &= help "File extensions to search (defaults to hs and lhs)"
+ ,language = def &= name "X" &= typ "LANG" &= help "Language extension (Arrows, NoCPP)"
+ ,utf8 = def &= help "Use UTF-8 text encoding"
+ ,encoding = def &= typ "ENC" &= help "Choose the text encoding"
+ ,find = def &= typFile &= help "Find hints in a Haskell file"
+ ,test_ = def &= help "Run in test mode"
+ ,datadir = def &= typDir &= help "Override the data directory"
+ ,cpp_define = def &= typ "NAME[=VALUE]" &= help "CPP #define"
+ ,cpp_include = def &= typDir &= help "CPP include path"
+ ,files = def &= args &= typ "FILES/DIRS"
+ } &=
+ verbosity &=
+ help "Suggest improvements to Haskell source code" &=
+ summary "HLint v0.0.0, (C) Neil Mitchell" &=
+ details ["Hlint gives hints on how to improve Haskell code",""
+ ,"To check all Haskell files in 'src' and generate a report type:"," hlint src --report"]
+
+mode = cmdArgsMode hlint
+
+
+ HLint v0.0.0, (C) Neil Mitchell
+
+ hlint [OPTIONS] [FILES/DIRS]
+ Suggest improvements to Haskell source code
+
+ Common flags:
+ -r --report[=FILE] Generate a report in HTML
+ -h --hint=FILE Hint/ignore file to use
+ -c --colour --color Color the output (requires ANSI terminal)
+ -i --ignore=MESSAGE Ignore a particular hint
+ -s --show Show all ignored ideas
+ --extension=EXT File extensions to search (defaults to hs and lhs)
+ -X --language=LANG Language extension (Arrows, NoCPP)
+ -u --utf8 Use UTF-8 text encoding
+ --encoding=ENC Choose the text encoding
+ -f --find=FILE Find hints in a Haskell file
+ -t --test Run in test mode
+ -d --datadir=DIR Override the data directory
+ --cpp-define=NAME[=VALUE] CPP #define
+ --cpp-include=DIR CPP include path
+ -? --help Display help message
+ -V --version Print version information
+ -v --verbose Loud verbosity
+ -q --quiet Quiet verbosity
+
+ Hlint gives hints on how to improve Haskell code
+
+ To check all Haskell files in 'src' and generate a report type:
+ hlint src --report
+
+
++ The Diffy sample is a based on the idea of creating directory listings and comparing them. The tool can operate in two separate modes, create or diff. This sample is fictional, but the ideas are drawn from a real program. A few notable features: +
+
+{-# LANGUAGE DeriveDataTypeable #-}
+module Diffy where
+import System.Console.CmdArgs
+
+data Diffy = Create {src :: Maybe FilePath, out :: FilePath}
+ | Diff {old :: FilePath, new :: FilePath, out :: FilePath}
+ deriving (Data,Typeable,Show,Eq)
+
+outFlags x = x &= help "Output file" &= typFile
+
+create = Create
+ {src = def &= help "Source directory" &= typDir
+ ,out = outFlags "ls.txt"
+ } &= help "Create a fingerprint"
+
+diff = Diff
+ {old = def &= typ "OLDFILE" &= argPos 0
+ ,new = def &= typ "NEWFILE" &= argPos 1
+ ,out = outFlags "diff.txt"
+ } &= help "Perform a diff"
+
+mode = cmdArgsMode $ modes [create,diff] &= help "Create and compare differences" &= program "diffy" &= summary "Diffy v1.0"
+
+
+
+ Diffy v1.0
+
+ diffy [COMMAND] ... [OPTIONS]
+ Create and compare differences
+
+ Common flags:
+ -o --out=FILE Output file
+ -? --help Display help message
+ -V --version Print version information
+
+ diffy create [OPTIONS]
+ Create a fingerprint
+
+ -s --src=DIR Source directory
+
+ diffy diff [OPTIONS] OLDFILE NEWFILE
+ Perform a diff
+
+
+
++ The Maker sample is based around a build system, where we can either build a project, clean the temporary files, or run a test. Some interesting features are: +
+
+{-# LANGUAGE DeriveDataTypeable #-}
+module Maker where
+import System.Console.CmdArgs
+
+data Method = Debug | Release | Profile
+ deriving (Data,Typeable,Show,Eq)
+
+data Maker
+ = Wipe
+ | Test {threads :: Int, extra :: [String]}
+ | Build {threads :: Int, method :: Method, files :: [FilePath]}
+ deriving (Data,Typeable,Show,Eq)
+
+threadsMsg x = x &= help "Number of threads to use" &= name "j" &= typ "NUM"
+
+wipe = Wipe &= help "Clean all build objects"
+
+test_ = Test
+ {threads = threadsMsg def
+ ,extra = def &= typ "ANY" &= args
+ } &= help "Run the test suite"
+
+build = Build
+ {threads = threadsMsg def
+ ,method = enum
+ [Release &= help "Release build"
+ ,Debug &= help "Debug build"
+ ,Profile &= help "Profile build"]
+ ,files = def &= args
+ } &= help "Build the project" &= auto
+
+mode = cmdArgsMode $ modes [build,wipe,test_] &= help "Build helper program" &= program "maker" &= summary "Maker v1.0\nMake it"
+
+
+
+ Maker v1.0
+ Make it
+
+ maker [COMMAND] ... [OPTIONS]
+ Build helper program
+
+ Common flags:
+ -? --help Display help message
+ -V --version Print version information
+
+ maker [build] [OPTIONS] [ITEM]
+ Build the project
+
+ -j --threads=NUM Number of threads to use
+ -r --release Release build
+ -d --debug Debug build
+ -p --profile Profile build
+
+ maker wipe [OPTIONS]
+ Clean all build objects
+
+ maker test [OPTIONS] [ANY]
+ Run the test suite
+
+ -j --threads=NUM Number of threads to use
+
diff --git a/System/Console/CmdArgs/Explicit.hs b/System/Console/CmdArgs/Explicit.hs
--- a/System/Console/CmdArgs/Explicit.hs
+++ b/System/Console/CmdArgs/Explicit.hs
@@ -56,7 +56,7 @@
process, processArgs, processValue,
-- * Constructing command lines
module System.Console.CmdArgs.Explicit.Type,
- flagHelpSimple, flagHelpFormat, flagVersion, flagsVerbosity,
+ flagHelpSimple, flagHelpFormat, flagVersion, flagNumericVersion, flagsVerbosity,
-- * Displaying help
module System.Console.CmdArgs.Explicit.Help,
-- * Utilities for working with command lines
@@ -182,6 +182,10 @@
-- | Create a version flag triggered by @-V@/@--version@.
flagVersion :: (a -> a) -> Flag a
flagVersion f = flagNone ["version","V"] f "Print version information"
+
+-- | Create a version flag triggered by @--numeric-version@.
+flagNumericVersion :: (a -> a) -> Flag a
+flagNumericVersion f = flagNone ["numeric-version"] f "Print just the version number"
-- | Create verbosity flags triggered by @-v@/@--verbose@ and
diff --git a/System/Console/CmdArgs/GetOpt.hs b/System/Console/CmdArgs/GetOpt.hs
--- a/System/Console/CmdArgs/GetOpt.hs
+++ b/System/Console/CmdArgs/GetOpt.hs
@@ -48,7 +48,7 @@
-- the header (first argument) and the options described by the
-- second argument.
usageInfo :: String -> [OptDescr a] -> String
-usageInfo desc flags = show $ convert desc flags
+usageInfo desc flags = unlines $ desc : drop 2 (lines $ show $ convert "" flags)
-- | Process the command-line, and return the list of values that matched
diff --git a/System/Console/CmdArgs/Helper.hs b/System/Console/CmdArgs/Helper.hs
--- a/System/Console/CmdArgs/Helper.hs
+++ b/System/Console/CmdArgs/Helper.hs
@@ -172,8 +172,8 @@
deriving (Show,Read)
newtype NoShow a = NoShow a
-instance Show (NoShow a) where -- deliberately leave the methods unimplemented
-instance Read (NoShow a) where -- deliberately leave the methods unimplemented
+instance Show (NoShow a) where showsPrec = error "Cannot show value of type NoShow"
+instance Read (NoShow a) where readsPrec = error "Cannot read value of type NoShow"
transformM, descendM :: Monad m => (Pack -> m Pack) -> Pack -> m Pack
diff --git a/System/Console/CmdArgs/Implicit/Global.hs b/System/Console/CmdArgs/Implicit/Global.hs
--- a/System/Console/CmdArgs/Implicit/Global.hs
+++ b/System/Console/CmdArgs/Implicit/Global.hs
@@ -165,6 +165,8 @@
wrap x = def{flagFlag=x, flagExplicit=True, flagGroup=grp}
flags = changeBuiltin_ (progHelpArg p) (wrap $ flagHelpFormat $ error "flagHelpFormat undefined") ++
changeBuiltin_ (progVersionArg p) (wrap $ flagVersion vers) ++
+ concat [changeBuiltin_ (progVersionArg p) (wrap $ flagNumericVersion $ \x -> x{cmdArgsVersion = Just $ unlines v})
+ | Just v <- [progNumericVersionOutput p]] ++
changeBuiltin_ (fst $ progVerbosityArgs p) (wrap loud) ++
changeBuiltin_ (snd $ progVerbosityArgs p) (wrap quiet)
[loud,quiet] = flagsVerbosity verb
diff --git a/System/Console/CmdArgs/Implicit/Local.hs b/System/Console/CmdArgs/Implicit/Local.hs
--- a/System/Console/CmdArgs/Implicit/Local.hs
+++ b/System/Console/CmdArgs/Implicit/Local.hs
@@ -6,7 +6,7 @@
module System.Console.CmdArgs.Implicit.Local(
local, err,
Prog_(..), Builtin_(..), Mode_(..), Flag_(..), Fixup(..), isFlag_,
- progHelpOutput, progVersionOutput
+ progHelpOutput, progVersionOutput, progNumericVersionOutput
) where
import System.Console.CmdArgs.Implicit.Ann
@@ -21,6 +21,7 @@
import Data.Char
import Data.Generics.Any
import Data.Maybe
+import Data.List
data Prog_ = Prog_
@@ -41,6 +42,14 @@
progHelpOutput = progOutput progHelpArg
progVersionOutput = progOutput progVersionArg
+progNumericVersionOutput x = fmap return $ parseVersion =<< listToMaybe (progVersionOutput x)
+
+-- | Find numbers starting after space/comma, v
+parseVersion :: String -> Maybe String
+parseVersion xs = listToMaybe
+ [y | x <- words $ map (\x -> if x `elem` ",;" then ' ' else x) xs
+ , let y = fromMaybe x $ stripPrefix "v" x
+ , length (takeWhile isDigit y) >= 1]
data Builtin_ = Builtin_
diff --git a/System/Console/CmdArgs/Implicit/UI.hs b/System/Console/CmdArgs/Implicit/UI.hs
--- a/System/Console/CmdArgs/Implicit/UI.hs
+++ b/System/Console/CmdArgs/Implicit/UI.hs
@@ -129,7 +129,8 @@
-- | Modes: \"My program name\/version\/copyright is ...\"
--
-- One line summary of the entire program, the first line of
--- @--help@ and the only line of @--version@.
+-- @--help@ and the only line of @--version@. If the string contains a
+-- version number component will also provide @--numeric-version@.
--
-- > Sample{..} &= summary "CmdArgs v0.0, (C) Neil Mitchell 1981"
summary :: String -> Ann
diff --git a/System/Console/CmdArgs/Test/Implicit/Diffy.hs b/System/Console/CmdArgs/Test/Implicit/Diffy.hs
--- a/System/Console/CmdArgs/Test/Implicit/Diffy.hs
+++ b/System/Console/CmdArgs/Test/Implicit/Diffy.hs
@@ -54,6 +54,7 @@
isHelp ["diff","--help"] []
isHelpNot ["--help"] ["diffy"]
isVersion ["--version"] "Diffy v1.0"
+ isVersion ["--numeric-version"] "1.0"
["create"] === create
fails ["create","file1"]
fails ["create","--quiet"]
@@ -66,7 +67,7 @@
["diff","foo1","foo2"] === diff{old="foo1",new="foo2"}
fails ["diff","foo1"]
fails ["diff","foo1","foo2","foo3"]
- completion [] (0,0) [CompleteValue "create",CompleteValue "diff",CompleteValue "--out",CompleteValue "--help",CompleteValue "--version"]
+ completion [] (0,0) [CompleteValue "create",CompleteValue "diff",CompleteValue "--out",CompleteValue "--help",CompleteValue "--version",CompleteValue "--numeric-version"]
completion ["d"] (0,1) [CompleteValue "diff"]
completion ["dd"] (0,2) []
diff --git a/System/Console/CmdArgs/Test/Implicit/HLint.hs b/System/Console/CmdArgs/Test/Implicit/HLint.hs
--- a/System/Console/CmdArgs/Test/Implicit/HLint.hs
+++ b/System/Console/CmdArgs/Test/Implicit/HLint.hs
@@ -61,6 +61,9 @@
isVerbosity [] Normal
isHelp ["-?"] ["HLint v0.0.0, (C) Neil Mitchell"]
isHelp ["--help"] [" hlint src --report"]
+ isVersion ["--version"] "HLint v0.0.0, (C) Neil Mitchell"
+ isVersion ["-V"] "HLint v0.0.0, (C) Neil Mitchell"
+ isVersion ["--numeric-version"] "0.0.0"
["--colo"] === hlint{color=True}
["--colour","--colour=false"] === hlint
["--colour=true"] === hlint{color=True}
diff --git a/System/Console/CmdArgs/Test/Implicit/Tests.hs b/System/Console/CmdArgs/Test/Implicit/Tests.hs
--- a/System/Console/CmdArgs/Test/Implicit/Tests.hs
+++ b/System/Console/CmdArgs/Test/Implicit/Tests.hs
@@ -248,6 +248,7 @@
["test13c","--foo13=13"] === Test13C 13
isHelp ["--help"] ["Help text here"]
isVersion ["--version"] "Version text here"
+ fails ["--numeric-version"]
-- check a list becomes modes not an enum
data Test14 = Test14A | Test14B | Test14C deriving (Eq,Show,Data,Typeable)
@@ -292,11 +293,12 @@
data Test16 = Test16 {test16a :: MyInt, test16b :: [MyInt]} deriving (Eq,Show,Data,Typeable)
-mode16 = cmdArgsMode $ Test16 (MyInt 12) []
+mode16 = cmdArgsMode $ Test16 (MyInt 12) [] &= summary "The Glorious Glasgow Haskell Compilation System, version 7.6.3"
test16 = do
let Tester{..} = tester "Test16" mode16
[] === Test16 (MyInt 12) []
+ isVersion ["--numeric-version"] "7.6.3"
fails ["--test16a"]
["--test16a=5"] === Test16 (MyInt 5) []
["--test16b=5","--test16b=82"] === Test16 (MyInt 12) [MyInt 5, MyInt 82]
@@ -305,13 +307,14 @@
-- not actually checked because this path doesn't go through processArgs
data Test17 = Test17 {test17_ :: [String]} deriving (Eq,Show,Data,Typeable)
-mode17 = cmdArgsMode $ Test17 ([] &= args) &= noAtExpand
+mode17 = cmdArgsMode $ Test17 ([] &= args) &= noAtExpand &= summary "bzip2 3.5-windows version"
test17 = do
let Tester{..} = tester "Test17" mode17
[] === Test17 []
["test","of","this"] === Test17 ["test","of","this"]
["test","--","@foo"] === Test17 ["test","@foo"]
+ isVersion ["--numeric-version"] "3.5-windows"
data Debuggable = This | That deriving (Eq,Show,Data,Typeable)
diff --git a/System/Console/CmdArgs/Test/Implicit/Util.hs b/System/Console/CmdArgs/Test/Implicit/Util.hs
--- a/System/Console/CmdArgs/Test/Implicit/Util.hs
+++ b/System/Console/CmdArgs/Test/Implicit/Util.hs
@@ -82,8 +82,9 @@
_ -> failed "Failed on isHelpNot" args []
isVersion args want = f args $ \x -> case x of
- Right x | Just got <- cmdArgsVersion x, match [want] (lines got) -> success
- _ -> failed "Failed on isVersion" args [("Want",want)]
+ Right x | Just got <- cmdArgsVersion x, (want ++ "\n") == got -> success
+ _ -> failed "Failed on isVersion" args $
+ ("Want",want) : [("Got",got) | Right x <- [x], Just got <- [cmdArgsVersion x]]
isVerbosity args v = f args $ \x -> case x of
Right x | fromMaybe Normal (cmdArgsVerbosity x) == v -> success
diff --git a/cmdargs.cabal b/cmdargs.cabal
--- a/cmdargs.cabal
+++ b/cmdargs.cabal
@@ -1,13 +1,13 @@
cabal-version: >= 1.6
build-type: Simple
name: cmdargs
-version: 0.10.7
+version: 0.10.8
license: BSD3
license-file: LICENSE
category: Console
author: Neil Mitchell - by Neil Mitchell -
- -- CmdArgs is a library for defining and parsing command lines. The focus of CmdArgs is allowing the concise definition of fully-featured command line argument processors, in a mainly declarative manner (i.e. little coding needed). CmdArgs also supports multiple mode programs, for example as used in darcs and Cabal. -
- This document explains how to write the "hello world" of command line processors, then how to extend it with features into a complex command line processor. Finally this document gives three samples, which the cmdargs program can run. The three samples are: -
-- For each example you are encouraged to look at it's source (see the darcs repo, or the bottom of this document) and run it (try cmdargs hlint --help). The HLint program is fairly standard in terms of it's argument processing, and previously used the System.Console.GetOpt library. Using GetOpt required 90 lines and a reasonable amount of duplication. Using CmdArgs the code requires 30 lines, and the logic is much simpler. -
-- Thanks to Kevin Quick for substantial patches, and additional code contributions from Sebastian Fischer and Daniel Schoepe. -
- - -- The following code defines a complete command line argument processor: -
-
-{-# LANGUAGE DeriveDataTypeable #-}
-module Sample where
-import System.Console.CmdArgs
-
-data Sample = Sample {hello :: String}
- deriving (Show, Data, Typeable)
-
-sample = Sample{hello = def}
-
-main = print =<< cmdArgs sample
-
-- To use the CmdArgs library there are three steps: -
-- Now we have a reasonably functional command line argument processor. Some sample interactions are: -
-
-$ runhaskell Sample.hs --hello=world
-Sample {hello = "world"}
-
-$ runhaskell Sample.hs --version
-The sample program
-
-$ runhaskell Sample.hs --help
-The sample program
-
-sample [OPTIONS]
-
- -? --help Display help message
- -V --version Print version information
- -h --hello=ITEM
-
-- CmdArgs uses defaults to automatically infer a command line parser for a value, and provides annotations to override any of the the defaults. CmdArgs automatically supports --help and --version flags, and optionally supports verbosity flags. -
- -- In order to control the behaviour we can add attributes. For example to add an attribute specifying the help text for the --hello argument we can write: -
-
-sample = Sample{hello = def &= help "Who to say hello to"}
-
-- We can add additional attributes, for example to specify the type of the value expected by hello: -
-
-sample = Sample {hello = def &= help "Who to say hello to" &= typ "WORLD"}
-
-- Now when running --help the final line is: -
-- -h --hello=WORLD Who to say hello to --
- There are many more attributes, detailed in the Haddock documentation. -
- - -- To specify a program with multiple modes, similar to darcs, we can supply a data type with multiple constructors, for example: -
-
-data Sample = Hello {whom :: String}
- | Goodbye
- deriving (Show, Data, Typeable)
-
-hello = Hello{whom = def}
-goodbye = Goodbye
-
-main = print =<< cmdArgs (modes [hello,goodbye])
-
-- Compared to the first example, we now have multiple constructors, and a sample value for each constructor is passed to cmdArgs. Some sample interactions with this command line are: -
-
-$ runhaskell Sample.hs hello --whom=world
-Hello {whom = "world"}
-
-$ runhaskell Sample.hs goodbye
-Goodbye
-
-$ runhaskell Sample.hs --help
-The sample program
-
-sample [OPTIONS]
-
- Common flags
- -? --help Display help message
- -V --version Print version information
-
-sample hello [OPTIONS]
-
- -w --whom=ITEM
-
-sample goodbye [OPTIONS]
-
-- As before, the behaviour can be customised using attributes. -
- -- For each of the following examples we first explain the purpose of the program, then give the source code, and finally the output of --help=HTML. The programs are intended to show sample uses of CmdArgs, and are available to experiment with through cmdargs progname. -
- -- The HLint program analyses a list of files, using various options to control the analysis. The command line processing is simple, but a few interesting points are: -
-
-{-# LANGUAGE DeriveDataTypeable #-}
-module HLint where
-import System.Console.CmdArgs
-
-data HLint = HLint
- {report :: [FilePath]
- ,hint :: [FilePath]
- ,color :: Bool
- ,ignore_ :: [String]
- ,show_ :: Bool
- ,extension :: [String]
- ,language :: [String]
- ,utf8 :: Bool
- ,encoding :: String
- ,find :: [FilePath]
- ,test_ :: Bool
- ,datadir :: [FilePath]
- ,cpp_define :: [String]
- ,cpp_include :: [FilePath]
- ,files :: [FilePath]
- }
- deriving (Data,Typeable,Show,Eq)
-
-hlint = HLint
- {report = def &= opt "report.html" &= typFile &= help "Generate a report in HTML"
- ,hint = def &= typFile &= help "Hint/ignore file to use"
- ,color = def &= name "c" &= name "colour" &= help "Color the output (requires ANSI terminal)"
- ,ignore_ = def &= typ "MESSAGE" &= help "Ignore a particular hint"
- ,show_ = def &= help "Show all ignored ideas"
- ,extension = def &= typ "EXT" &= help "File extensions to search (defaults to hs and lhs)"
- ,language = def &= name "X" &= typ "LANG" &= help "Language extension (Arrows, NoCPP)"
- ,utf8 = def &= help "Use UTF-8 text encoding"
- ,encoding = def &= typ "ENC" &= help "Choose the text encoding"
- ,find = def &= typFile &= help "Find hints in a Haskell file"
- ,test_ = def &= help "Run in test mode"
- ,datadir = def &= typDir &= help "Override the data directory"
- ,cpp_define = def &= typ "NAME[=VALUE]" &= help "CPP #define"
- ,cpp_include = def &= typDir &= help "CPP include path"
- ,files = def &= args &= typ "FILES/DIRS"
- } &=
- verbosity &=
- help "Suggest improvements to Haskell source code" &=
- summary "HLint v0.0.0, (C) Neil Mitchell" &=
- details ["Hlint gives hints on how to improve Haskell code",""
- ,"To check all Haskell files in 'src' and generate a report type:"," hlint src --report"]
-
-mode = cmdArgsMode hlint
-
-
-
-| HLint v0.0.0, (C) Neil Mitchell | ||
| hlint [OPTIONS] [FILES/DIRS] | ||
| Suggest improvements to Haskell source code | ||
| Common flags: | ||
| -r | --report[=FILE] | Generate a report in HTML |
| -h | --hint=FILE | Hint/ignore file to use |
| -c | --colour --color | Color the output (requires ANSI terminal) |
| -i | --ignore=MESSAGE | Ignore a particular hint |
| -s | --show | Show all ignored ideas |
| --extension=EXT | File extensions to search (defaults to hs and lhs) | |
| -X | --language=LANG | Language extension (Arrows, NoCPP) |
| -u | --utf8 | Use UTF-8 text encoding |
| --encoding=ENC | Choose the text encoding | |
| -f | --find=FILE | Find hints in a Haskell file |
| -t | --test | Run in test mode |
| -d | --datadir=DIR | Override the data directory |
| --cpp-define=NAME[=VALUE] | CPP #define | |
| --cpp-include=DIR | CPP include path | |
| -? | --help | Display help message |
| -V | --version | Print version information |
| -v | --verbose | Loud verbosity |
| -q | --quiet | Quiet verbosity |
| Hlint gives hints on how to improve Haskell code | ||
| To check all Haskell files in 'src' and generate a report type: | ||
| hlint src --report | ||
- The Diffy sample is a based on the idea of creating directory listings and comparing them. The tool can operate in two separate modes, create or diff. This sample is fictional, but the ideas are drawn from a real program. A few notable features: -
-
-{-# LANGUAGE DeriveDataTypeable #-}
-module Diffy where
-import System.Console.CmdArgs
-
-data Diffy = Create {src :: Maybe FilePath, out :: FilePath}
- | Diff {old :: FilePath, new :: FilePath, out :: FilePath}
- deriving (Data,Typeable,Show,Eq)
-
-outFlags x = x &= help "Output file" &= typFile
-
-create = Create
- {src = def &= help "Source directory" &= typDir
- ,out = outFlags "ls.txt"
- } &= help "Create a fingerprint"
-
-diff = Diff
- {old = def &= typ "OLDFILE" &= argPos 0
- ,new = def &= typ "NEWFILE" &= argPos 1
- ,out = outFlags "diff.txt"
- } &= help "Perform a diff"
-
-mode = cmdArgsMode $ modes [create,diff] &= help "Create and compare differences" &= program "diffy" &= summary "Diffy v1.0"
-
-
-
-| Diffy v1.0 | ||
| diffy [COMMAND] ... [OPTIONS] | ||
| Create and compare differences | ||
| Common flags: | ||
| -o | --out=FILE | Output file |
| -? | --help | Display help message |
| -V | --version | Print version information |
| diffy create [OPTIONS] | ||
| Create a fingerprint | ||
| -s | --src=DIR | Source directory |
| diffy diff [OPTIONS] OLDFILE NEWFILE | ||
| Perform a diff | ||
- The Maker sample is based around a build system, where we can either build a project, clean the temporary files, or run a test. Some interesting features are: -
-
-{-# LANGUAGE DeriveDataTypeable #-}
-module Maker where
-import System.Console.CmdArgs
-
-data Method = Debug | Release | Profile
- deriving (Data,Typeable,Show,Eq)
-
-data Maker
- = Wipe
- | Test {threads :: Int, extra :: [String]}
- | Build {threads :: Int, method :: Method, files :: [FilePath]}
- deriving (Data,Typeable,Show,Eq)
-
-threadsMsg x = x &= help "Number of threads to use" &= name "j" &= typ "NUM"
-
-wipe = Wipe &= help "Clean all build objects"
-
-test_ = Test
- {threads = threadsMsg def
- ,extra = def &= typ "ANY" &= args
- } &= help "Run the test suite"
-
-build = Build
- {threads = threadsMsg def
- ,method = enum
- [Release &= help "Release build"
- ,Debug &= help "Debug build"
- ,Profile &= help "Profile build"]
- ,files = def &= args
- } &= help "Build the project" &= auto
-
-mode = cmdArgsMode $ modes [build,wipe,test_] &= help "Build helper program" &= program "maker" &= summary "Maker v1.0\nMake it"
-
-
-
-| Maker v1.0 | ||
| Make it | ||
| maker [COMMAND] ... [OPTIONS] | ||
| Build helper program | ||
| Common flags: | ||
| -? | --help | Display help message |
| -V | --version | Print version information |
| maker [build] [OPTIONS] [ITEM] | ||
| Build the project | ||
| -j | --threads=NUM | Number of threads to use |
| -r | --release | Release build |
| -d | --debug | Debug build |
| -p | --profile | Profile build |
| maker wipe [OPTIONS] | ||
| Clean all build objects | ||
| maker test [OPTIONS] [ANY] | ||
| Run the test suite | ||
| -j | --threads=NUM | Number of threads to use |