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