options
Powerful and easy command-line option parser
https://github.com/typeclasses/options/
LTS Haskell 22.37: | 1.2.1.2@rev:1 |
Stackage Nightly 2024-10-11: | 1.2.1.2@rev:1 |
Latest on Hackage: | 1.2.1.2@rev:1 |
options-1.2.1.2@sha256:2c86ea06767c8b4d2710508fa7efa9fee5820135ab79928a4bb7e9534f37998c,1571
Module documentation for 1.2.1.2
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
Changes
1.2.1.2
The test framework is changed from chell
to hspec
.
This avoids a cyclic dependency between the options
and chell
packages.
Various documentation adjustments. Notably, some of the larger parts of the
documentation are moved from the API documentation to a readme.md
file.
The package is now tested with GHC versions 9.2, 9.4, and 9.6.
Requires an upgrade of the dependency monads-tf
from 0.1
to 0.3
.
Published by: Chris Martin
Date: 2023-07-11
1.2.1.1
Published by: John Millikin
Date: 2015-01-13
1.2.1
Published by: John Millikin
Date: 2014-12-14
1.2
Published by: John Millikin
Date: 2014-05-17
1.1
Published by: John Millikin
Date: 2014-05-17
1.0
Published by: John Millikin
Date: 2014-03-02
0.1.1
Published by: John Millikin
Date: 2012-04-08
0.1
Published by: John Millikin
Date: 2012-03-24