1module Options.Applicative (
2  -- * Applicative option parsers
3  --
4  -- | This module exports all one should need for defining and using
5  -- optparse-applicative command line option parsers.
6  --
7  -- See <https://github.com/pcapriotti/optparse-applicative> for a tutorial,
8  -- and a general introduction to applicative option parsers.
9  --
10  -- See the sections below for more detail
11
12  -- * Exported modules
13  --
14  -- | The standard @Applicative@ module is re-exported here for convenience.
15  module Control.Applicative,
16
17  -- * Option Parsers
18  --
19  -- | A 'Parser' is the core type in optparse-applicative. A value of type
20  -- @Parser a@ represents a specification for a set of options, which will
21  -- yield a value of type a when the command line arguments are successfully
22  -- parsed.
23  --
24  -- There are several types of primitive 'Parser'.
25  --
26  -- * Flags: simple no-argument options. When a flag is encountered on the
27  -- command line, its value is returned.
28  --
29  -- * Options: options with an argument. An option can define a /reader/,
30  -- which converts its argument from String to the desired value, or throws a
31  -- parse error if the argument does not validate correctly.
32  --
33  -- * Arguments: positional arguments, validated in the same way as option
34  -- arguments.
35  --
36  -- * Commands. A command defines a completely independent sub-parser. When a
37  -- command is encountered, the whole command line is passed to the
38  -- corresponding parser.
39  --
40  -- See the "Parser Builders" section for how to construct and customise
41  -- these parsers.
42  Parser,
43
44  -- ** Parser builders
45  --
46  -- | This section contains utility functions and combinators to create parsers
47  -- for individual options.
48  --
49  -- Each parser builder takes an option modifier. A modifier can be created by
50  -- composing the basic modifiers provided by here using the 'Monoid' operations
51  -- 'mempty' and 'mappend', or their aliases 'idm' and '<>'.
52  --
53  -- For example:
54  --
55  -- > out = strOption
56  -- >     ( long "output"
57  -- >    <> short 'o'
58  -- >    <> metavar "FILENAME" )
59  --
60  -- creates a parser for an option called \"output\".
61  flag,
62  flag',
63  switch,
64
65  strOption,
66  option,
67
68  strArgument,
69  argument,
70
71  subparser,
72  hsubparser,
73
74  abortOption,
75  infoOption,
76  helper,
77
78  -- ** Modifiers
79  --
80  -- | 'Parser' builders take a modifier, which represents a modification of the
81  -- properties of an option, and can be composed as a monoid.
82  --
83  -- Contraints are often used to ensure that the modifiers can be sensibly applied.
84  -- For example, positional arguments can't be specified by long or short names,
85  -- so the 'HasName' constraint is used to ensure we have a flag or option.
86  Mod,
87
88  short,
89  long,
90  help,
91  helpDoc,
92  value,
93  showDefaultWith,
94  showDefault,
95  metavar,
96  noArgError,
97  hidden,
98  internal,
99  style,
100  command,
101  commandGroup,
102  completeWith,
103  action,
104  completer,
105  idm,
106  mappend,
107
108  OptionFields,
109  FlagFields,
110  ArgumentFields,
111  CommandFields,
112
113  HasName,
114  HasCompleter,
115  HasValue,
116  HasMetavar,
117  -- ** Readers
118  --
119  -- | A reader is used by the 'option' and 'argument' builders to parse
120  -- the data passed by the user on the command line into a data type.
121  --
122  -- The most common are 'str' which is used for 'String' like types,
123  -- including 'ByteString' and 'Text'; and 'auto', which uses the 'Read'
124  -- typeclass, and is good for simple types like 'Int' or 'Double'.
125  --
126  -- More complex types can use the 'eitherReader' or 'maybeReader'
127  -- functions to pattern match or use a more expressive parser like a
128  -- member of the 'Parsec' family.
129  ReadM,
130
131  auto,
132  str,
133  maybeReader,
134  eitherReader,
135  disabled,
136  readerAbort,
137  readerError,
138
139  -- * Program descriptions
140  --
141  -- ** 'ParserInfo'
142  --
143  -- | A 'ParserInfo' describes a command line program, used to generate a help
144  -- screen. Two help modes are supported: brief and full. In brief mode, only
145  -- an option and argument summary is displayed, while in full mode each
146  -- available option and command, including hidden ones, is described.
147  --
148  -- A 'ParserInfo' should be created with the 'info' function and a set of
149  -- 'InfoMod' modifiers.
150  --
151  info,
152
153  ParserInfo(..),
154
155  InfoMod,
156  fullDesc,
157  briefDesc,
158  header,
159  headerDoc,
160  footer,
161  footerDoc,
162  progDesc,
163  progDescDoc,
164  failureCode,
165  noIntersperse,
166  forwardOptions,
167
168  -- * Running parsers
169  --
170  -- | The execParser family of functions are used to run parsers
171  execParser,
172  customExecParser,
173  execParserPure,
174
175  -- ** Handling parser results manually
176  getParseResult,
177  handleParseResult,
178  parserFailure,
179  renderFailure,
180  overFailure,
181
182  -- ** 'ParserPrefs'
183  --
184  -- | A 'ParserPrefs' contains general preferences for all command-line
185  -- options, and should be built with the 'prefs' function.
186  prefs,
187
188  ParserPrefs(..),
189
190  PrefsMod,
191  multiSuffix,
192  disambiguate,
193  showHelpOnError,
194  showHelpOnEmpty,
195  noBacktrack,
196  subparserInline,
197  columns,
198  helpLongEquals,
199  defaultPrefs,
200
201  -- * Completions
202  --
203  -- | optparse-applicative supplies a rich completion system for bash,
204  -- zsh, and fish shells.
205  --
206  -- 'Completer' functions are used for option and argument to complete
207  -- their values.
208  --
209  -- Use the 'completer' builder to use these.
210  -- The 'action' and 'completeWith' builders are also provided for
211  -- convenience, to use 'bashCompleter' and 'listCompleter' as a 'Mod'.
212  Completer,
213  mkCompleter,
214  listIOCompleter,
215
216  listCompleter,
217  bashCompleter,
218
219  -- * Types
220  ParseError(..),
221  ParserHelp(..),
222  ParserFailure(..),
223  ParserResult(..),
224  CompletionResult(..)
225
226  ) where
227
228-- reexport Applicative here for convenience
229import Control.Applicative
230
231import Options.Applicative.Common
232import Options.Applicative.Builder
233import Options.Applicative.Builder.Completer
234import Options.Applicative.Extra
235import Options.Applicative.Types
236