Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 368 lines (269 sloc) 11.475 kb
95712a2 @pcapriotti Add README.
authored
1 # Applicative option parser
2
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
3 This package contains utilities and combinators to define command line option
4 parsers.
5
284b203 @pcapriotti Add Travis CI configuration and status.
authored
6 [![Continuous Integration status][status-png]][status]
a64910c @pcapriotti Add hackage badge and use svg badge for travis
authored
7 [![Hackage page (downloads and API reference)][hackage-png]][hackage]
7b550b9 @jstasiak Link to Hackage page and builder documentation
jstasiak authored
8
b278f71 @pcapriotti Add table of contents to README.md
authored
9 **Table of Contents**
10
11 - [Getting started](#getting-started)
12 - [Supported options](#supported-options)
13 - [Regular options](#regular-options)
14 - [Flags](#flags)
15 - [Arguments](#arguments)
16 - [Commands](#commands)
17 - [Option builders](#option-builders)
18 - [Advanced features](#advanced-features)
19 - [How it works](#how-it-works)
20
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
21 ## Getting started
22
dd71eeb @ryantm Add quick installation and import instructions
ryantm authored
23 Install with
24
25 ```sh
26 cabal install optparse-applicative
27 ```
28
43d0275 @pcapriotti Move import statement into sample parser code block
authored
29 Here is a simple example of an applicative option parser:
dd71eeb @ryantm Add quick installation and import instructions
ryantm authored
30
31 ```haskell
32 import Options.Applicative
33
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
34 data Sample = Sample
35 { hello :: String
36 , quiet :: Bool }
37
38 sample :: Parser Sample
39 sample = Sample
40 <$> strOption
41 ( long "hello"
45d3954 @pcapriotti Replace (&) with (<>) in the README (#37).
authored
42 <> metavar "TARGET"
43 <> help "Target for the greeting" )
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
44 <*> switch
45 ( long "quiet"
45d3954 @pcapriotti Replace (&) with (<>) in the README (#37).
authored
46 <> help "Whether to be quiet" )
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
47 ```
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
48
49 The parser is built using [applicative style][applicative] starting from a set
50 of basic combinators. In this example, `hello` is defined as an option with a
51 `String` argument, while `quiet` is a boolean flag (called `switch`).
52
53 A parser can be used like this:
54
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
55 ```haskell
56 greet :: Sample -> IO ()
4bee34a @pcapriotti Fix greet function in Hello example.
authored
57 greet (Sample h False) = putStrLn $ "Hello, " ++ h
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
58 greet _ = return ()
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
59
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
60 main :: IO ()
61 main = execParser opts >>= greet
62 where
63 opts = info (helper <*> sample)
64 ( fullDesc
45d3954 @pcapriotti Replace (&) with (<>) in the README (#37).
authored
65 <> progDesc "Print a greeting for TARGET"
66 <> header "hello - a test for optparse-applicative" )
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
67 ```
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
68
69 The `greet` function is the entry point of the program, while `opts` is a
70 complete description of the program, used when generating a help text. The
b23c57b @pcapriotti Update docs after error handling changes.
authored
71 `helper` combinator takes any parser, and adds a `help` option to it.
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
72
73 The `hello` option in this example is mandatory (since it doesn't have a
b23c57b @pcapriotti Update docs after error handling changes.
authored
74 default value), so running the program without any argument will display a
75 short option summary:
76
77 Usage: hello --hello TARGET [--quiet]
78
79 Running the program with the `--help` option will display the full help text:
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
80
81 hello - a test for optparse-applicative
82
83 Usage: hello --hello TARGET [--quiet]
84 Print a greeting for TARGET
85
0915084 @pcapriotti Replace "Common" with "Available" in help text.
authored
86 Available options:
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
87 -h,--help Show this help text
88 --hello TARGET Target for the greeting
89 --quiet Whether to be quiet
90
b23c57b @pcapriotti Update docs after error handling changes.
authored
91 containing a detailed list of options with descriptions.
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
92
cf9bbb5 @pcapriotti Document metavars (fixes #86).
authored
93 The specified metavars are used as placeholders for the option arguments, and
94 can be referred to in the program description. This makes it possible to
95 explicitly describe the connection between the options and the behaviour of the
96 program.
97
e7cc156 @pcapriotti Add example of using the 'optional' combinator (fixes #25).
authored
98 Parsers are instances of both `Applicative` and `Alternative`, and work with
99 any generic combinator, like `many` and `some`. For example, to make a option
100 return `Nothing` instead of failing when it's not supplied, you can use the
101 `optional` combinator in `Control.Applicative`:
102
103 ```haskell
104 optional $ strOption
c85bd49 @akc Fix a few small issues with the documentation
akc authored
105 ( long "output"
106 <> metavar "DIRECTORY" )
e7cc156 @pcapriotti Add example of using the 'optional' combinator (fixes #25).
authored
107 ```
108
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
109 [applicative]: http://www.soi.city.ac.uk/~ross/papers/Applicative.html
110
e90c579 @pcapriotti Add more documentation to README.
authored
111 ## Supported options
112
113 `optparse-applicative` supports four kinds of options: regular options, flags,
114 arguments and commands.
115
116 ### Regular options
117
118 A **regular option** is an option which takes a single argument, parses it, and
119 returns a value.
120
121 A regular option can have a default value, which is used as the result if the
122 option is not found in the command line. An option without a default value is
123 considered mandatory, and produces an error when not found.
124
125 Regular options can have **long** names, or **short** (one-character) names,
126 which determine when the option matches and how the argument is extracted.
127
128 An option with a long name (say "output") is specified on the command line as
129
130 --output filename.txt
131
132 or
133
134 --output=filename.txt
135
136 while a short name option (say "o") can be specified with
137
138 -o filename.txt
139
140 or
141
142 -ofilename.txt
143
144 Options can have more than one name, usually one long and one short, although
145 you are free to create options with an arbitrary combination of long and short
146 names.
147
148 Regular options returning strings are the most common, and they can be created
149 using the `strOption` builder. For example,
150
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
151 ```haskell
152 strOption
cb9af6b @pcapriotti Remove all mentions to (&) from the README (#37).
authored
153 ( long "output"
154 <> short 'o'
155 <> metavar "FILE"
156 <> help "Write output to FILE" )
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
157 ```
e90c579 @pcapriotti Add more documentation to README.
authored
158
159 creates a regular option with a string argument (which can be referred to as
07a94c1 @pcapriotti Fix typos in README.md.
authored
160 `FILE` in the help text and documentation), a long name "output" and a short
e90c579 @pcapriotti Add more documentation to README.
authored
161 name "o". See below for more information on the builder syntax and modifiers.
162
9091b11 @pcapriotti Make `option` take the reader as a parameter (fixes #63)
authored
163 A regular option can return an object of any type, and takes a *reader*
164 parameter which specifies how the argument should be parsed. A common reader is
165 `auto`, which assumes a `Read` instance for the return type and uses it to parse
166 its argument. For example:
e90c579 @pcapriotti Add more documentation to README.
authored
167
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
168 ```haskell
169 lineCount :: Parser Int
9091b11 @pcapriotti Make `option` take the reader as a parameter (fixes #63)
authored
170 lineCount = option auto
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
171 ( long "lines"
45d3954 @pcapriotti Replace (&) with (<>) in the README (#37).
authored
172 <> short 'n'
173 <> metavar "K"
174 <> help "Output the last K lines" )
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
175 ```
e90c579 @pcapriotti Add more documentation to README.
authored
176
177 specifies a regular option with an `Int` argument. We added an explicit type
178 annotation here, since without it the parser would have been polymorphic in the
179 output type. There's usually no need to add type annotations, however, because
180 the type will be normally inferred from the context in which the parser is
181 used.
182
9091b11 @pcapriotti Make `option` take the reader as a parameter (fixes #63)
authored
183 You can also create a custom reader that doesn't use the `Read` typeclass, and
c0aa50a @pcapriotti Update documentation of readers
authored
184 use it to parse option arguments. A custom reader is a value in the `ReadM`
185 monad.
e90c579 @pcapriotti Add more documentation to README.
authored
186
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
187 ```haskell
188 data FluxCapacitor = ...
e90c579 @pcapriotti Add more documentation to README.
authored
189
2b1cb0c @pcapriotti Update custom reader example in the README (fixes #41).
authored
190 parseFluxCapacitor :: Monad m => String -> m FluxCapacitor
e90c579 @pcapriotti Add more documentation to README.
authored
191
c0aa50a @pcapriotti Update documentation of readers
authored
192 option (str >>= parseFluxCapacitor)
9091b11 @pcapriotti Make `option` take the reader as a parameter (fixes #63)
authored
193 ( long "flux-capacitor" )
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
194 ```
e90c579 @pcapriotti Add more documentation to README.
authored
195
c0aa50a @pcapriotti Update documentation of readers
authored
196 Use `readerAbort` or `readerError` within the `ReadM` monad to exit with an
197 error message.
198
e90c579 @pcapriotti Add more documentation to README.
authored
199 ### Flags
200
201 A **flag** is just like a regular option, but it doesn't take any arguments: it is
202 either present in the command line or not.
203
204 A flag has a default value and an **active value**. If the flag is found on the
205 command line, the active value is returned, otherwise the default value is
206 used. For example:
207
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
208 ```haskell
209 data Verbosity = Normal | Verbose
e90c579 @pcapriotti Add more documentation to README.
authored
210
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
211 flag Normal Verbose
cb9af6b @pcapriotti Remove all mentions to (&) from the README (#37).
authored
212 ( long "verbose"
213 <> short 'v'
c85bd49 @akc Fix a few small issues with the documentation
akc authored
214 <> help "Enable verbose mode" )
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
215 ```
e90c579 @pcapriotti Add more documentation to README.
authored
216
217 is a flag parser returning a `Verbosity` value.
218
219 Simple boolean flags can be specified using the `switch` builder, like so:
220
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
221 ```haskell
222 switch
cb9af6b @pcapriotti Remove all mentions to (&) from the README (#37).
authored
223 ( long "keep-tmp-files"
224 <> help "Retain all intermediate temporary files" )
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
225 ```
e90c579 @pcapriotti Add more documentation to README.
authored
226
50e1014 @pcapriotti Add example for flag' (fixes #34).
authored
227 There is also a `flag'` builder, which has no default value. For example, to
228 add a `--version` switch to a program, you could write:
229
230 ```haskell
231 flag' Nothing (long "version" <> hidden) <|> (Just <$> normal_options)
232 ```
233
e90c579 @pcapriotti Add more documentation to README.
authored
234 ### Arguments
235
236 An **argument** parser specifies a positional command line argument.
237
238 The `argument` builder takes a reader parameter, and creates a parser which
239 will return the parsed value every time it is passed a command line argument
240 for which the reader succeeds. For example
241
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
242 ```haskell
d4b0097 @pcapriotti Deprecate `arguments` and `arguments1`.
authored
243 argument str (metavar "FILE")
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
244 ```
e90c579 @pcapriotti Add more documentation to README.
authored
245
d4b0097 @pcapriotti Deprecate `arguments` and `arguments1`.
authored
246 creates an argument accepting any string. To accept an arbitrary number of
247 arguments, combine the `argument` builder with either the `many` or `some`
248 combinator:
249
250 ```haskell
251 some (argument str (metavar "FILES..."))
252 ```
e90c579 @pcapriotti Add more documentation to README.
authored
253
254 Arguments are only displayed in the brief help text, so there's no need to
96e1d42 @pcapriotti Fix typos in README.
authored
255 attach a description to them. They should be manually documented in the program
e90c579 @pcapriotti Add more documentation to README.
authored
256 description.
257
b09fb36 @pcapriotti Update README.
authored
258 Note that arguments starting with `-` are considered options by default, and
259 will not be considered by an `argument` parser.
260
261 However, parsers always accept a special argument: `--`. When a `--` is found on
262 the command line, all the following words are considered by `argument` parsers,
263 regardless of whether they start with `-` or not.
264
e90c579 @pcapriotti Add more documentation to README.
authored
265 ### Commands
266
267 A **command** can be used to specify a sub-parser to be used when a certain
268 string is encountered in the command line.
269
270 Commands are useful to implement command line programs with multiple functions,
271 each with its own set of options, and possibly some global options that apply
272 to all of them. Typical examples are version control systems like `git`, or
273 build tools like `cabal`.
274
275 A command can be created using the `subparser` builder, and commands can be
276 added with the `command` modifier. For example
277
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
278 ```haskell
279 subparser
cb9af6b @pcapriotti Remove all mentions to (&) from the README (#37).
authored
280 ( command "add" (info addOptions
281 ( progDesc "Add a file to the repository" ))
282 <> command "commit" (info commitOptions
283 ( progDesc "Record changes to the repository" ))
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
284 )
285 ```
e90c579 @pcapriotti Add more documentation to README.
authored
286
287 Each command takes a full `ParserInfo` structure, which will be used to extract
288 a description for this command when generating a help text.
289
290 Note that all the parsers appearing in a command need to have the same type.
291 For this reason, it is often best to use a sum type which has the same
292 structure as the command itself. For example, for the parser above, you would
293 define a type like:
294
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
295 ```haskell
296 data Options = Options
185a7d4 @pcapriotti Revisit "commands" section in the tutorial.
authored
297 { optGlobalOpt :: String
298 , optGlobalFlag :: Bool
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
299 ...
185a7d4 @pcapriotti Revisit "commands" section in the tutorial.
authored
300 , optCommand :: Command }
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
301
185a7d4 @pcapriotti Revisit "commands" section in the tutorial.
authored
302 data Command
303 = Add AddOptions
304 | Commit CommitOptions
a2ba8bd @pcapriotti Add syntax highlighting to README.md.
authored
305 ...
306 ```
e90c579 @pcapriotti Add more documentation to README.
authored
307
185a7d4 @pcapriotti Revisit "commands" section in the tutorial.
authored
308 Alternatively, you can directly return an `IO` action from a parser, and
309 execute it using `join` from `Control.Monad`.
310
311 ```haskell
312 start :: String -> IO ()
313 stop :: IO ()
314
315 opts :: Parser (IO ())
316 opts = subparser
317 ( command "start" (info (start <$> argument str idm) idm)
45d3954 @pcapriotti Replace (&) with (<>) in the README (#37).
authored
318 <> command "stop" (info (pure stop) idm) )
185a7d4 @pcapriotti Revisit "commands" section in the tutorial.
authored
319
320 main :: IO ()
321 main = join $ execParser (info opts idm)
322 ```
323
07a94c1 @pcapriotti Fix typos in README.md.
authored
324 ## Option builders
e90c579 @pcapriotti Add more documentation to README.
authored
325
326 Builders allow you to define parsers using a convenient combinator-based
327 syntax. Each builder takes a **modifier** as parameter, and returns a parser.
328
329 A modifier is a composition of functions which act on the option, setting
330 values for properties or adding features, and is used to build the option from
331 scratch and finally lift it to a single-option parser, which can then be
332 combined with other parsers using normal `Applicative` combinators.
333
53e780f @pcapriotti Update builder documentation.
authored
334 Modifiers are instances of the `Monoid` typeclass, so they can be combined
cb9af6b @pcapriotti Remove all mentions to (&) from the README (#37).
authored
335 using the composition function `mappend` (or simply `(<>)`).
e90c579 @pcapriotti Add more documentation to README.
authored
336
7b550b9 @jstasiak Link to Hackage page and builder documentation
jstasiak authored
337 See the [haddock documentation][builder-documentation] for `Options.Applicative.Builder`
338 for a full list of builders and modifiers.
e90c579 @pcapriotti Add more documentation to README.
authored
339
36c3f9e @pcapriotti Links to wiki pages.
authored
340 ## Advanced features
e4a4d54 @pcapriotti Add a README paragraph about the arrow interface.
authored
341
a6090e5 @pcapriotti Link to documentation of Disambiguation (fixes #83).
authored
342 * [Bash completion]
343 * [Arrow interface]
344 * [Disambiguation]
e4a4d54 @pcapriotti Add a README paragraph about the arrow interface.
authored
345
a6090e5 @pcapriotti Link to documentation of Disambiguation (fixes #83).
authored
346 [Bash completion]: https://github.com/pcapriotti/optparse-applicative/wiki/Bash-Completion
347 [Arrow interface]: https://github.com/pcapriotti/optparse-applicative/wiki/Arrows
348 [Disambiguation]: https://github.com/pcapriotti/optparse-applicative/wiki/Disambiguation
8fdc854 @pcapriotti Improve docs for the `Arrow` interface (fixes #26).
authored
349
409eeb1 @pcapriotti Add a "Getting started" section to README.
authored
350 ## How it works
351
352 A `Parser a` is essentially a heterogeneous list of `Option`s, implemented with
353 existential types.
354
355 All options are therefore known statically (i.e. before parsing, not
356 necessarily before runtime), and can, for example, be traversed to generate a
357 help text.
358
359 See [this blog post][blog] for a more detailed explanation based on a
360 simplified implementation.
361
a64910c @pcapriotti Add hackage badge and use svg badge for travis
authored
362 [status-png]: https://api.travis-ci.org/pcapriotti/optparse-applicative.svg
284b203 @pcapriotti Add Travis CI configuration and status.
authored
363 [status]: http://travis-ci.org/pcapriotti/optparse-applicative?branch=master
6a29e32 @michaelt wrong link to your blogpost
michaelt authored
364 [blog]: http://paolocapriotti.com/blog/2012/04/27/applicative-option-parser/
7b550b9 @jstasiak Link to Hackage page and builder documentation
jstasiak authored
365 [builder-documentation]: http://hackage.haskell.org/package/optparse-applicative/docs/Options-Applicative-Builder.html
a64910c @pcapriotti Add hackage badge and use svg badge for travis
authored
366 [hackage-png]: http://img.shields.io/hackage/v/optparse-applicative.svg
f19b5ef @pcapriotti Point to latest hackage page
authored
367 [hackage]: http://hackage.haskell.org/package/optparse-applicative
Something went wrong with that request. Please try again.