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 2006-2010" &= 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 2006-2010 | ||
hlint [OPTIONS] [FILES/DIRS] | ||
Suggest improvements to Haskell source code | ||
-? | --help | Display help message |
-V | --version | Print version information |
-v | --verbose | Loud verbosity |
-q | --quiet | Quiet verbosity |
-r | --report[=FILE] | Generate a report in HTML (default=report.html) |
-h | --hint=FILE | Hint/ignore file to use |
-c | --color --colour | 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 | |
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 [OPTIONS] | ||
Create and compare differences | ||
Common flags | ||
-? | --help | Display help message |
-V | --version | Print version information |
diffy create [OPTIONS] | ||
Create a fingerprint | ||
-s | --src=DIR | Source directory |
-o | --out=FILE | Output file |
diffy diff [OPTIONS] OLDFILE NEWFILE | ||
Perform a diff | ||
-o | --out=FILE | Output file |
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"
Maker v1.0 | ||
maker [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 |