This file describes an example interaction with example
First, without any arguments
> ./example
no command specified Use -h option for detailed help Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options]
It tells us to try the -h option, so we do
> ./example -h
-- end options
-D display default values
-L display available commands
-V print version and exit
-a, --alpha ALPHA Assign integer ALPHA to alpha
-b, --bravo BRAVO Assign string BRAVO to bravo
-c, --charlie CHARLIE Assign float CHARLIE to charlie
-d, --delta DELTA Assign boolean DELTA to delta
-e, --echo Take action echo
-f, --foxtrot FOXTROT Assign ecks|why|zee FOXTROT to foxtrot
-g, --golf Store 6 in golf (default 3)
-h, -help, display this help
--help, -?
-i, --india Clear india (default true)
-j ILLINOIS Assign string ILLINOIS to illinois
-k, --kilo KILO Assign float KILO to kilo
-l, --lima Set lima (default false)
-m, --mike MIKE Convert MIKE and store in mike (default 0, 0)
-n, --november NOVEMBER Assign ecks|you|vee NOVEMBER to november (default
ecks)
-o, --oscar Store on in oscar (default off)
-p, --print display received opts, args
-t, --tango an Arg parser
-v, --verbosity increase verbosity level
The main program is set up to allow GNU/UNIX-style collapsed arguments (-lip is equivalent to -l -i -p).
> ./example -lipa 123 -b hello -vvv this is a test
really verbose! Received options: alpha = 123 bravo = hello charlie = None delta = None echo = None foxtrot = None golf = 3 india = true illinois = None kilo = None lima = false mike = 0,0 november = ecks oscar = off verbosity = 3 print = true tango = None Received anonymous arguments: this is a test no command specified Use -h option for detailed help Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options]
We can also use GNU-style -- options
> ./example --lima --alpha 123 --print
Received options: alpha = 123 bravo = None charlie = None delta = None echo = None foxtrot = None golf = 3 india = true illinois = None kilo = None lima = false mike = 0,0 november = ecks oscar = off verbosity = 0 print = true tango = None Received anonymous arguments: no command specified Use -h option for detailed help Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options]
The first anonymous argument terminates option processing
> ./example -lipa 123 -b hello this is a test -v
Received options: alpha = 123 bravo = hello charlie = None delta = None echo = None foxtrot = None golf = 3 india = true illinois = None kilo = None lima = false mike = 0,0 november = ecks oscar = off verbosity = 0 print = true tango = None Received anonymous arguments: this is a test -v no command specified Use -h option for detailed help Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options]
... as does --
> ./example -lipa 123 -b hello -- -v more args
Received options: alpha = 123 bravo = hello charlie = None delta = None echo = None foxtrot = None golf = 3 india = true illinois = None kilo = None lima = false mike = 0,0 november = ecks oscar = off verbosity = 0 print = true tango = None Received anonymous arguments: -v more args no command specified Use -h option for detailed help Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options]
Using the -p option with no other arguments prints the default values. The
-D option also does this (using a handler method)
> ./example -p
Received options: alpha = None bravo = None charlie = None delta = None echo = None foxtrot = None golf = 3 india = true illinois = None kilo = None lima = false mike = 0,0 november = ecks oscar = off verbosity = 0 print = true tango = None Received anonymous arguments: no command specified Use -h option for detailed help Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options]
> ./example -D
Default values: alpha = None bravo = None charlie = None delta = None echo = None foxtrot = None golf = 3 india = true illinois = None kilo = None lima = false mike = 0,0 november = ecks oscar = off verbosity = 0 print = false tango = None
Note that options without a specified default have None as their value,
whereas e.g. golf defaults to 3 and india defaults to true.
If an option value is specified that's of the wrong type, a conversion error message is printed:
> ./example -a one
Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options] Conversion failure; error converting one to type int for option alpha
> ./example -f vee
Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options] Conversion failure; error converting vee to type ecks|why|zee for option foxtrot
Another error that can occur is when an option key that requires an argument isn't given one:
> ./example -a
Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options] Missing argument to option -a
Finally, if something that looks like an option (begins with '-') isn't a recognized one, this error is given:
> ./example -z
Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options] Unknown option -z
Subcommands and parse variants
Some programs, like cvs or ocamlfind, have "subcommands", which can have
their own sets of options. Pa_arg offers rudimentary support for subcommands
(if someone has an idea about a better way of integrating them, I'd like to
hear it). This also offers us an opportunity to show some of the flexibility
of pa_arg in this example.
This command (as described in the help above) lists the available subcommands.
> ./example -L
Available commands: tag log
We can use the standard help option on the subcommand to see what commands are available for it.
> ./example log -h
-- end options -d, -date DATE Assign string DATE to date -h, -help, display this help --help, -? -l, -log Set log (default false)
... and then try out some of the options
> ./example log -l -d 1992
Received suboptions: date = 1992 log = true Received subarguments
The subcommands are configured with the default parsing parameters, unlike the main program. This has several effects:
The subcommand doesn't accept GNU-style collapsed arguments (parsetype=Caml)
> ./example log -l -d 1992
Received suboptions: date = 1992 log = true Received subarguments
> ./example log -ld 1992
Usage: ./example log [-d DATE] [-l] Unknown option -ld
The subcommand does allow interspersing arguments and options (keepgoing=true)
> ./example log -l this is -d 1992 a test
Received suboptions: date = 1992 log = true Received subarguments this is a test
Finally, the subcommand forms long options with a Caml-style single hyphen
(keyspecs=["Short";"Long1"]).
> ./example log -log -date 1992
Received suboptions: date = 1992 log = true Received subarguments
Note that you can have options both to the main command and to subcommands
> ./example -lip tag -a -t version1
Received options: alpha = None bravo = None charlie = None delta = None echo = None foxtrot = None golf = 3 india = true illinois = None kilo = None lima = false mike = 0,0 november = ecks oscar = off verbosity = 0 print = true tango = None Received anonymous arguments: tag -a -t version1 Received suboptions: all_users = true tag = version1 Received subarguments
Handlers
As a catch-all ability, pa_arg allows options to take over parsing the
command-line. It's not incredibly realistic, but the -t option in
example does this, passing off parsing to the standard Arg module.
> ./example -p -t -a something -beta 123
Received options: alpha = None bravo = None charlie = None delta = None echo = None foxtrot = None golf = 3 india = true illinois = None kilo = None lima = false mike = 0,0 november = ecks oscar = off verbosity = 0 print = true tango = something/0000007B Received anonymous arguments: no command specified Use -h option for detailed help Usage: ./example [-D] [-L] [-V] [-a ALPHA] [-b BRAVO] [-c CHARLIE] [-d DELTA] [-e] [-f FOXTROT] [-g] [-i] [-j ILLINOIS] [-k KILO] [-l] [-m MIKE] [-n NOVEMBER] [-o] [-p] [-t] [-v] command [sub-options]