File: README.md

package info (click to toggle)
haskell-cmdargs 0.10.20-3
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, sid
  • size: 356 kB
  • sloc: haskell: 2,970; makefile: 3
file content (364 lines) | stat: -rw-r--r-- 14,105 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
# CmdArgs: Easy Command Line Processing [![Hackage version](https://img.shields.io/hackage/v/cmdargs.svg?label=Hackage)](https://hackage.haskell.org/package/cmdargs) [![Build Status](https://img.shields.io/travis/ndmitchell/cmdargs.svg)](https://travis-ci.org/ndmitchell/cmdargs)

CmdArgs is a Haskell library for defining command line parsers. The two features that make it a better choice than the standard [getopt library](http://haskell.org/ghc/docs/latest/html/libraries/base/System-Console-GetOpt.html) 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](http://darcs.net) or [Cabal](http://haskell.org/cabal/).

A very simple example of a command line processor is:
```haskell
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)

## 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](https://github.com/ndmitchell/hlint#readme) 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](https://github.com/ndmitchell/cmdargs/tree/master/System/Console/CmdArgs/Test/Implicit)) 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](http://haskell.org/ghc/docs/latest/html/libraries/base/System-Console-GetOpt.html) 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:
```haskell
{-# 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 for `Show`, `Data` and `Typeable`.
* 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 the `cmdArgs` 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:

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

## 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:
```haskell
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:
```haskell
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](http://hackage.haskell.org/packages/archive/cmdargs/latest/doc/html/System-Console-CmdArgs.html#2).


## Multiple Modes

To specify a program with multiple modes, similar to [darcs](http://darcs.net/), we can supply a data type with multiple constructors, for example:
```haskell
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.


## 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](https://github.com/ndmitchell/hlint#readme) 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 with `show` 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:
```haskell
{-# 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:
```haskell
{-# 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:
```haskell
{-# 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