docopt
A command-line interface parser that will make you smile
https://github.com/docopt/docopt.hs
| LTS Haskell 24.16: | 0.7.0.8@rev:2 |
| Stackage Nightly 2025-10-24: | 0.7.0.8@rev:2 |
| Latest on Hackage: | 0.7.0.8@rev:2 |
docopt-0.7.0.8@sha256:db1c1d94e04231d296443915d24c2aed71ed881e5688f7e9a431206b132e791f,3505Module documentation for 0.7.0.8
- System
- System.Console
Docopt.hs
A Haskell port of python’s docopt.
Want a command-line interface without building a parser?
How about writing your help text first, and getting a parser for free!
Save your help text to a file (i.e. USAGE.txt):
Usage:
myprog cat <file>
myprog echo [--caps] <string>
Options:
-c, --caps Caps-lock the echoed argument
Then, in your Myprog.hs:
{-# LANGUAGE QuasiQuotes #-}
import Control.Monad (when)
import Data.Char (toUpper)
import System.Environment (getArgs)
import System.Console.Docopt
patterns :: Docopt
patterns = [docoptFile|USAGE.txt|]
getArgOrExit = getArgOrExitWith patterns
main = do
args <- parseArgsOrExit patterns =<< getArgs
when (args `isPresent` (command "cat")) $ do
file <- args `getArgOrExit` (argument "file")
putStr =<< readFile file
when (args `isPresent` (command "echo")) $ do
let charTransform = if args `isPresent` (longOption "caps")
then toUpper
else id
string <- args `getArgOrExit` (argument "string")
putStrLn $ map charTransform string
That’s it! No Template Haskell, no unreadable syntax, no learning yet another finicky API. Write the usage patterns you support, and docopt builds the appropriate option parser for you (internally using parsec). If your user invokes your program correctly, you query for the arguments they provided. If the arguments provided do not match a supported usage pattern, you guessed it: docopt automatically prints the help text and exits!
Installation
cabal sandbox init
cabal install docopt
API Reference
Help text format
Docopt only cares about 2 parts of your help text:
-
Usage patterns, e.g.:
Usage: my_program [-hs] [-o=<file>] [--quiet | --verbose] [<input>...]These begin with
Usage:(case-insensitive), and end with a blank line. -
Option descriptions, e.g.:
Options: -h --help show this -s --sorted sorted output -o=<file> specify output file [default: ./test.txt] --quiet print less text --verbose print more textAny line after the usage patterns that begins with a
-is treated as an option description (though an option’s default may be on a different line).
Usage Patterns
-
<argument>orARGUMENTPositional arguments. Constructed via
argument, i.e.argument "arg"matches an<arg>element in the help text, andargument "ARG"matches anARGelement. -
--flagor--option=<arg>Options are typically optional (though this is up to you), and can be either boolean (present/absent), as in
--flag, or expect a trailing argument, as in--option=<arg>or--option=ARG. Arguments can be separated from the option name by an=or a single space, and can be specified as<arg>orARG(consistency of style is recommended, but it is not enforced).Short-style options, as in
-for-f ARGor-f=<arg>, are also allowed. Synonyms between different spellings of the same option (e.g.-vand--verbose) can be established in the option descriptions (see below). Short-style options can also be stacked, as in-rfA. When options are stacked,-rfAis effectively equivalent to(-r | -f | -A)...to the argument parser.You can match a long-style option
--optionor--option=<arg>withlongOption "option", and a short-style option-for -f=<arg>withshortOption 'f'. Note that neither--option=<arg>nor-f=<arg>would be matched byargument "arg". -
commandAnything not recognized as a positional argument or a short or long option is treated as a command (or subcommand, same thing to docopt). A command named
pullcan be matched withcommand "pull". -
[](brackets) e.g.command [--option]Patterns inside brackets are optional.
-
()(parens)Patterns inside parens are required (the same as patterns not in
()are required). Parens are useful if you need to group some elements, either for use with|or.... -
|(pipe) e.g.command [--quiet | --verbose]A pipe
|separates mutually exclusive elements in a group. A group could be elements inside[],(), or the whole usage line.Usage: myprog command [--opt1 | --opt2] # valid myprog go (left | right) # valid myprog -v | -h # validWhen elements are separated by a pipe, the elements are tried from left to right until one succeeds. At least one of the elements are required unless in an eplicitly optional group surrounded by
[]. -
...(ellipsis) e.g.command <file>...An ellipsis can trail any element or group to make it repeatable. Repeatable elements will be accumulated into a list of occurrences.
-
[options](case sensitive)The string
[options]is a shortcut to match any options specified in your option descriptions. -
[-]and[--]Single hyphen
-is used by convention to specify usingstdinas input instead of reading a file. Double hyphen--is typically used to manually separate leading options from trailing positional arguments. Both of these are treated ascommands, and so are perfectly legal in usage patterns. They are typically optional elements, but can be required if you drop the[]. These are treated as commands and can be matched withcommand "-"orcommand "--", whether they’re wrapped[-]or not.
Option descriptions
Option descriptions establish:
- which short and long options are synonymous
- whether an option expects an argument or is a simple flag
- if an option’s argument has a default value
Rules:
-
Any line after the usage patterns whose first non-space character is a
-is treated as an option description. (Options:prefix line not required).Options: --help # invalid: line does not start with '-' --verbose # good -
Options on the same line will be treated by the parser as synonyms (everywhere interchangeable). Synonymous options are separated by a space (with optional comma):
Usage: myprog --help | --verbose Options: -h, --help Print help text -v --verbose Print help text twiceHere,
myprog --helpandmyprog -hwill both work the same, as willmyprog --verboseandmyprog -v. -
If any synonymous options are specified in the description with an argument, the option parser will expect an argument for all synonyms. If not, all synonyms will be treated as flags.
Usage: myprog analyze [--verbose] <file> Options: --verbose, -v LEVEL The level of output verbosity.Here, in the arguments
myprog analyze --verbose ./file1.txtwould be invalid, because-vand its synonyms expect an argument, so./file1.txtis captured as the argument of--verbose, not as the positional argument<file>. Be careful!Options can be separated from arguments with a single space or a
=, and arguments can have the form<arg>orARG. Just be sure to separate synonyms and arguments from the beginning of the description by at least 2 spaces.--opt1 ARG1 Option 1. --opt2=<arg2> Option 2. # BAD: use 2 spaces -a <arg3> Option 3. -b=ARG4 Option 4. -
Options that expect arguments can be given a default value, in the form
[default: <default-val>]. Default values do not need to be on the same line--host=NAME Host to listen on. [default: localhost] --port=PORT Port number [default: 8080] --directory=DIR This option has an especially long description explaining its meaning. [default: ./]
Differences from reference python implementation:
-
does not automatically exclude from the
[options]shortcut options that are already used elsewhere in the usage pattern (e.g.usage: prog [options] -awill try to parse-atwice). -
does not automatically resolve partially-specified arguments, e.g.
--verbdoes not match where--verboseis expected. This is planned to be deprecated in future versions of docopt, and will likely not be implemented in docopt.hs -
is not insensitive to the ordering of adjacent options, e.g.
usage: prog -a -bdoes not allowprog -b -a(reference implementation currently does).
Changes
0.7.0.8
-
Extend Template Haskell Quasi-quotation support to GHC 8.0-8.6. Template Haskell support is no longer optional. The package now supports all GHC’s from 8.0 to 9.8. #56, #58
0.7.0.7
- update bounds, fix warnings, require ghc 8.0+
0.7.0.6
0.7.0.5
- Fix an issue where in some cases pattern lines were matched out of order #16
- Strip leading & trailing newlines from usage, for quasiquoter ease #28
- Fix tests run against latest aeson 1.0.2.0 #29
0.7.0.4
- Fix the test suite when run from a distributed tarball #21
- Make the test suite more developer-friendly
0.7.0.3
- Fix
isPresenttreatment of repeatable arguments/options #15 - Fix build failure for stackage inclusion #20
0.7.0.2
- Minor docs/README tweaks #13
0.7.0.1
- Fix docs in README and in Docopt.hs
0.7.0.0
- Add usage parsing QuasiQuoters #7
- Add
docoptusage parsing QuasiQuoter - Add
docoptFileusage parsing QuasiQuoter - Add
System.Docopt.NoTHmodule- Add
parseUsage - Add
parseUsageOrExit
- Add
- Add
- New API organization #10
- Remove
optionsWithUsage - Remove
optionsWithUsageDebug - Remove
optionsWithUsageFile - Remove
optionsWithUsageFileDebug - Add
Docopttype to represent a parsed usage string - Add
usage - Add
parseArgs - Add
parseArgsOrExit - Add
exitWithUsage - Add
exitWithUsageMessage - Monomorphize
getArgfromMonad mtoMaybe - Add
getArgOrExitWith - Deprecate
getAllArgsM - Deprecate
notPresentM - Deprecate
isPresentM - Deprecate
getFirstArg
- Remove
- Add thorough haddock API documentation
0.6.0.2
0.6.0.1
- Fix haddock docs.
0.6.0.0
First release! Tracks features of reference Python implementation at version 0.6.