cmdargs
Command line argument processing
https://github.com/ndmitchell/cmdargs#readme
LTS Haskell 22.33: | 0.10.22 |
Stackage Nightly 2024-09-07: | 0.10.22 |
Latest on Hackage: | 0.10.22 |
cmdargs-0.10.22@sha256:0d1a33c3978fbcdda4f2543e62ac3ed8ad36152e141cdeebeece7e08d6529d63,4248
Module documentation for 0.10.22
CmdArgs: Easy Command Line Processing
![Build status](https://img.shields.io/github/workflow/status/ndmitchell/cmdargs/ci/master.svg)
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:
- It’s very concise to use. The HLint command line handling is three times shorter with CmdArgs.
- It supports programs with multiple modes, such as darcs or Cabal.
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:
$ runghc Sample.hs --hello=world
Sample {hello = "world"}
$ runghc 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)
User Manual
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:
hlint
- the HLint program.diffy
- a program to compare the differences between directories.maker
- a make style program.
For each example you are encouraged to look at it’s source (in the repo) 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.
Acknowledgements Thanks to Kevin Quick for substantial patches, and additional code contributions from Sebastian Fischer and Daniel Schoepe.
Hello World Example
The following code defines a complete command line argument processor:
{-# LANGUAGE DeriveDataTypeable #-}
{-# OPTIONS_GHC -fno-cse #-}
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:
- Define a record data type (
Sample
) that contains a field for each argument. This type needs to have instances forShow
,Data
andTypeable
. - Give a value of that type (
sample
) with default values (def
is a default value of any type, but I could also have written""
). This value is turned into a command line by calling thecmdArgs
function. - To ensure GHC evalutes attributes the right number of times we disable the CSE optimisation on this module.
Now we have a reasonably functional command line argument processor. Some sample interactions are:
$ runghc Sample.hs --hello=world
Sample {hello = "world"}
$ runghc Sample.hs --version
The sample program
$ runghc 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.
Specifying Attributes
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.
Multiple Modes
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:
$ runghc Sample.hs hello --whom=world
Hello {whom = "world"}
$ runghc Sample.hs goodbye
Goodbye
$ runghc 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.
Larger Examples
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
. The programs are intended to show sample uses of CmdArgs, and are available to experiment with through cmdargs progname
.
HLint
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:
- The
--report
flag can be used to output a report in a standard location, but giving the flag a value changes where the file is output. - The
color
field is assigned two flag aliases,--colour
and-c
. Assigning the-c
short flag explicitly stops either of the CPP fields using it. - The
show_
field would clash withshow
if given the expected name, but CmdArgs automatically strips the trailing underscore. - The
cpp_define
field has an underscore in it’s name, which is transformed into a hyphen for the flag name.
The code is:
{-# 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
Produces the --help
output:
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
Diffy
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:
- There are multiple modes of execution, creating and diffing.
- The diff mode takes exactly two arguments, the old file and the new file.
- Default values are given for the
out
field, which are different in both modes.
The code is:
{-# 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"
And --help
produces:
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
Maker
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:
- The build mode is the default, so
maker
on it’s own will be interpreted as a build command. - The build method is an enumeration.
- The
threads
field is in two of the constructors, but not all three. It is given the short flag-j
, rather than the default-t
.
The code is:
{-# 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"
And --help
produces:
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
Changes
0.10.22, released 2023-03-13
#68, support GHC 9.6
0.10.21, released 2021-02-14
Handle GHC 9.0 optimisations
Remove support for GHC 7.4 to 7.8
0.10.20, released 2018-01-22
#54, use the getopt data types from base
0.10.19, released 2018-01-01
#47, ensure Semigroup instance on all GHC versions
0.10.18, released 2017-09-24
#47, GHC 8.4 compatibility
0.10.17, released 2017-03-31
Add processValueIO for more controlled error messages
#529, don't include the stack trace in processValue
0.10.16, released 2017-03-22
Minor improvement to error messages
0.10.15, released 2017-03-06
#43, GHC 8.2 compatibility
0.10.14, released 2016-02-16
#39, ensure correct line breaks in HTML help output
#18, preserve manual \n in help messages
#25, reformat the README
0.10.13, released 2015-05-22
#24, support Ratio in some places
0.10.12, released 2014-10-27
GHC 7.2 compatibility
0.10.11, released 2014-10-12
#15, never put [brackets] around optional args in Explicit
0.10.10, released 2014-09-18
#14, fix @ file arguments
0.10.9, released 2014-07-22
#10, fix versionArgs (broken in 0.10.8)
0.10.8, released 2014-07-21
Avoid compilation warnings on GHC 7.8
#9, add --numeric-version flag
Update the copyright year
Change GetOpt.usageInfo to be more like GetOpt
0.10.7, released 2013-12-09
#1, fix timestamps in .tar.gz dist file
0.10.6, released 2013-12-05
#625, more documentation about args/argPos
#626, ensure initial lists don't get reversed (fix after #610)
0.10.5, released 2013-07-29
#615, support lists inside a newtype
0.10.4, released 2013-06-26
#610, make sure it is O(n) to append arguments, not O(n^2)
0.10.3, released 2013-04-05
Append list items under an enum
Support &= ignore on enum fields
0.10.2, released 2013-02-28
Relax upper bounds to be GHC 7.7 compatible
0.10.1, released 2012-11-17
#569, set the test program to off by default
Complete revamp of cmdargs-browser, far better Javascript
Add a missing case for Helper marshalling FlagNone
0.10, released 2012-08-09
Revert to 0.9.6, including modeExpandAt
0.9.7, released 2012-08-09
Revert to 0.9.5, to fix up PVP breakage
0.9.6, released 2012-07-29
#539, hopefully more fixes to compiling in profile mode
#522, add modeExpandAt and noAtExpand annotation
#522, don't @expand after --
0.9.5, released 2012-03-25
Don't specify TH extension unless quotation is true
0.9.4, released 2012-03-25
#539, specify the TH extension in the Cabal file
Allow transformers 0.3.*
Correct copyright in license and cabal file
0.9.3, released 2012-02-10
Add expandArgsAt and support for @ flag file directives
0.9.2, released 2012-01-07
Don't build the test program if quotation is turned off
0.9.1, released 2012-01-05
Improve the documentation for the Explicit module
#433, propagate groupname on modes in the Implicit code
0.9, released 2011-11-05
#467, add completions for people running bash
#334, add a Quote module, to write pure in the impure syntax
#482, fix the sample in Explicit, don't use def
#461, fix the translation for enum/enum_
Make showHelp take an argument for the prefix bits
Add Helper interface, and initial cmdargs-browser code
Add splitArgs/joinArgs
0.8, released 2011-08-13
#450, redo the manual generator so Maker example is not cut off
Support all the types in Data.Int/Data.Word
Make modeArgs take a list of arguments as well
0.7, released 2011-05-07
No changes, just a version bump to allow requiring the GHC fix
0.6.10, released 2011-05-07
Change the annotate module to cope better with GHC's CSE
0.6.9, released 2011-04-03
#422, support newtype value as the underlying type
0.6.8, released 2011-02-13
Allow versionArgs [summary] to override --version
Improve the documentation surrounding opt
Add modeReform to Mode
Add modeEmpty, to construct blank Mode values
Improve the documentation surrounding pure annotations.
0.6.7, released 2011-01-15
#395, don't put two newlines after --help or --version
0.6.6, released 2010-12-30
#392, support helpArgs [groupname "something"]
0.6.5, released 2010-12-15
Don't fail with ambiguous enum if you exactly match a value
Put errors on stderr
0.6.4, released 2010-11-20
Eliminate the filepath dependence
0.6.3, released 2010-11-10
Switch mtl for transformers
0.6.2, released 2010-11-10
Build on GHC 7.0 RC2, add an extra type signature
Add verbosityArgs to customise the verbose/quiet flags
Add helpArg/versionArg flags to customise those flags
Support multiline summary using \n escape codes
0.6.1, released 2010-10-04
Build on GHC 6.10, don't rely on record name disambiguation
0.6, released 2010-09-18
Add ignore annotation for modes and flags
#350, make top-level help appear properly
0.5, released 2010-09-15
#351, name/explicit attributes on mode were broken (regression)
0.4, released 2010-09-05
#342, display common fields only once
Raise errors if annotations are placed in invalid places
Rewrite the translation of annotation to explicit modes
Treat anything after -- as an argument
Add a pure annotation mechanism
Introduce System.Console.CmdArgs.Annotate
0.3, released 2010-08-23
Add a documentation example for the Explicit mode
Improve the purity and annotations a bit, try disabling CSE
Change the help format
Rename groupHiden to groupHidden, patch from Matthew Cox
Bug, missing fields and explicit enums didn't work together
0.2, released 2010-08-14
#252, add support for grouped flags/modes
#333, support missing fields
Add support for reading tuple values (including nested)
#292, add support for automatic enumerations
#221, make argpos work with non-string fields
#222, support opt and args together
#230, different modes can share short flags
#295, make verbosity flags explicit
#231, add support for Maybe
#256, add --option=false support
Complete rewrite to introduce Explicit module
0.1, released 2009-09-12
Start of changelog