Purely functional command line parsing.
Here is a simple example:
let () =
Command.basic
~summary:"cook eggs"
Command.Spec.(
empty
+> flag "num-eggs" (required int) ~doc:"COUNT cook this many eggs"
+> flag "style" (required (Arg_type.create Egg_style.of_string))
~doc:"OVER-EASY|SUNNY-SIDE-UP style of eggs"
+> anon ("recipient" %: string))
(fun num_eggs style recipient ->
(* CR-someday dhouse: implement egg-cooking in ocaml *)
failwith "no eggs today")
|> Command.run
Command.Spec
, because the types are
easier to understand.
basic ~summary ?readme spec main
is a basic command that executes a function main
which is passed parameters parsed from the command line according to spec
.
summary
is to contain a short one-line description of its behavior. readme
is to
contain any longer description of its behavior that will go on that commands' help
screen.
Same general behavior as basic
, but takes a command line specification built up
using Params
instead of Spec
.
group ~summary subcommand_alist
is a compound command with named
subcommands, as found in subcommand_alist
. summary
is to contain
a short one-line description of the command group. readme
is to
contain any longer description of its behavior that will go on that
command's help screen.
NOTE: subcommand names containing underscores will be rejected. Use dashes instead.
body
is called when no additional arguments are passed -- in particular, when no
subcommand is passed. Its path
argument is the subcommand path by which the group
command was reached.
exec ~summary ~path_to_exe
runs exec
on the executable at path_to_exe
. If
path_to_exe
is `Absolute path
then path
is executed without any further
qualification. If it is `Relative_to_me path
then Filename.dirname
Sys.executable_name ^ "/" ^ path
is executed instead. All of the usual caveats about
Sys.executable_name
apply: specifically, it may only return an absolute path in
Linux. On other operating systems it will return Sys.argv.(0)
.
Care has been taken to support nesting multiple executables built with Command. In particular, recursive help and autocompletion should work as expected.
NOTE: non-Command executables can be used with this function but will still be
executed when help -recursive
is called or autocompletion is attempted (despite the
fact that neither will be particularly helpful in this case). This means that if you
have a shell script called "reboot-everything.sh" that takes no arguments and reboots
everything no matter how it is called, you shouldn't use it with exec
.
Additionally, no loop detection is attempted, so if you nest an executable within
itself, help -recursive
and autocompletion will hang forever (although actually
running the subcommand will work).
extract the summary string for a command
Run a command against Sys.argv
, or argv
if it is specified.
extend
can be used to add extra command line arguments to basic subcommands of the
command. extend
will be passed the (fully expanded) path to a command, and its
output will be appended to the list of arguments being processed. For example,
suppose a program like this is compiled into exe
:
let bar = Command.basic ...
let foo = Command.group ~summary:... ["bar", bar]
let main = Command.group ~summary:... ["foo", foo]
Command.run ~extend:(fun _ -> ["-baz"]) main
Then if a user ran exe f b
, extend
would be passed ["foo"; "bar"]
and "-baz"
would be appended to the command line for processing by bar
. This can be used to
add a default flags section to a user config file.