The options package lets library and application developers easily work with command-line options.
This document discusses a handful of the utilities in this package. See the API documentation for the Options module for more.
Introductory example
The following example is a full program that can accept two options, --message and --quiet:
import Control.Applicative import Options data MainOptions = MainOptions { optMessage :: String , optQuiet :: Bool } . instance Options MainOptions where defineOptions = pure MainOptions <*> simpleOption "message" "Hello world!" "A message to show the user." <*> simpleOption "quiet" False "Whether to be quiet." main :: IO () main = runCommand $ \opts args -> if optQuiet opts then return () else putStrLn (optMessage opts)
$ ./hello Hello world! $ ./hello --message='ciao mondo' ciao mondo $ ./hello --quiet $
In addition, this library will automatically create documentation options such as --help and --help-all:
$ ./hello --help Help Options: -h, --help Show option summary. --help-all Show all help options. Application Options: --message :: text A message to show the user. default: "Hello world!" --quiet :: bool Whether to be quiet. default: false
Defining options
optionType_bool
optionType_bool stores an option as a Bool. The option's value must be either "true" or "false".
Boolean options are unary, which means that their value is optional when specified on the command line. If a flag is present, the option is set to True.
$ ./app -q $ ./app --quiet
Boolean options may still be specified explicitly by using long flags with the --flag=value format. This is the only way to set a unary flag to "false".
$ ./app --quiet=true $ ./app --quiet=false
optionType_enum
optionType_enum store an option as one of a set of possible values. The type must be a bounded enumeration, and the type's Show instance will be used to implement the parser.
This is a simplistic implementation, useful for quick scripts. Users with more complex requirements for enum parsing are encouraged to define their own option types using optionType.
Example:
data Action = Hello | Goodbye deriving (Bounded, Enum, Show) data MainOptions = MainOptions { optAction :: Action } instance Options MainOptions where defineOptions = pure MainOptions <*> defineOption (optionType_enum "action") (\o -> o { optionLongFlags = ["action"] , optionDefault = Hello }) main = runCommand $ \opts args -> do putStrLn ("Running action " ++ show (optAction opts))
$ ./app Running action Hello $ ./app --action=Goodbye Running action Goodbye
Parsing argument lists
parseOptions
parseOptions attempts to convert a list of command-line arguments into an options value. This can be used by application developers who want finer control over error handling, or who want to perform additional validation on the options value.
The argument list must be in the same encoding as the result of System.Environment.getArgs.
Use parsedOptions, parsedArguments, parsedError, and parsedHelp to inspect the result of parseOptions.
Example:
getOptionsOrDie :: Options a => IO a getOptionsOrDie = do argv <- System.Environment.getArgs let parsed = parseOptions argv case parsedOptions parsed of Just opts -> return opts Nothing -> case parsedError parsed of Just err -> do hPutStrLn stderr (parsedHelp parsed) hPutStrLn stderr err exitFailure Nothing -> do hPutStr stdout (parsedHelp parsed) exitSuccess
parseSubcommand
parseSubcommand attempts to convert a list of command-line arguments into a subcommand action. This can be used by application developers who want finer control over error handling, or who want subcommands that run in an unusual monad.
The argument list must be in the same encoding as the result of System.Environment.getArgs.
Use parsedSubcommand, parsedError, and parsedHelp to inspect the result of parseSubcommand.
Example:
runSubcommand :: Options cmdOpts => [Subcommand cmdOpts (IO a)] -> IO a runSubcommand subcommands = do argv <- System.Environment.getArgs let parsed = parseSubcommand subcommands argv case parsedSubcommand parsed of Just cmd -> cmd Nothing -> case parsedError parsed of Just err -> do hPutStrLn stderr (parsedHelp parsed) hPutStrLn stderr err exitFailure Nothing -> do hPutStr stdout (parsedHelp parsed) exitSuccess
Running main with options
runCommand
runCommand retrieves System.Environment.getArgs and attempts to parse it into a valid value of an Options type plus a list of left-over arguments.
The options and arguments are then passed to the provided computation.
If parsing fails, this computation will print an error and call exitFailure.
If parsing succeeds, and the user has passed a --help flag, and the developer is using the default help flag definitions, then this computation will print documentation and call exitSuccess.
runSubcommand
runSubcommand is used to run applications that are split into subcommands. Use subcommand to define available commands and their actions, then pass them to this computation to select one and run it.
If the user specifies an invalid subcommand, this computation will print an error and call exitFailure. In handling of invalid flags or --help, runSubcommand acts like runCommand.
Example:
import Control.Applicative import Control.Monad (unless) import Options data MainOptions = MainOptions { optQuiet :: Bool } instance Options MainOptions where defineOptions = pure MainOptions <*> simpleOption "quiet" False "Whether to be quiet." data HelloOpts = HelloOpts { optHello :: String } instance Options HelloOpts where defineOptions = pure HelloOpts <*> simpleOption "hello" "Hello!" "How to say hello." data ByeOpts = ByeOpts { optName :: String } instance Options ByeOpts where defineOptions = pure ByeOpts <*> simpleOption "name" "" "The user's name." hello :: MainOptions -> HelloOpts -> [String] -> IO () hello mainOpts opts args = unless (optQuiet mainOpts) $ do putStrLn (optHello opts) bye :: MainOptions -> ByeOpts -> [String] -> IO () bye mainOpts opts args = unless (optQuiet mainOpts) $ do putStrLn ("Good bye " ++ optName opts) main :: IO () main = runSubcommand [ subcommand "hello" hello , subcommand "bye" bye ]
$ ./app hello Hello! $ ./app hello --hello='Allo!' Allo! $ ./app bye Good bye $ ./app bye --name='Alice' Good bye Alice
