Up

Module Command

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
    

Signature

module Arg_type : sig .. end
module Flag : sig .. end
module Anons : sig .. end
module Param : sig .. end
This module is meant to eventually replace Command.Spec, because the types are easier to understand.
module Let_syntax : sig .. end
module Spec : sig .. end
type t

commands which can be combined into a hierarchy of subcommands

type ('main, 'result) basic_command = summary:string -> ?readme:(unit -> string) -> ('main, unit -> 'result) Spec.t -> 'main -> t
val basic : ('main, unit) basic_command

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.

type 'result basic_command' = summary:string -> ?readme:(unit -> string) -> (unit -> 'result) Param.t -> t
val basic' : unit basic_command'

Same general behavior as basic, but takes a command line specification built up using Params instead of Spec.

val group : summary:string -> ?readme:(unit -> string) -> ?preserve_subcommand_order:unit -> ?body:(path:string list -> unit) -> (string * t) list -> t

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.

val exec : summary:string -> ?readme:(unit -> string) -> path_to_exe:[
| `Absolute of string
| `Relative_to_me of string
] -> unit -> t

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).

val summary : t -> string

extract the summary string for a command

module Shape : sig .. end
val shape : t -> Shape.t

expose the shape of a command

val run : ?version:string -> ?build_info:string -> ?argv:string list -> ?extend:(string list -> string list) -> t -> unit

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.

module Deprecated : sig .. end
Deprecated should be used only by Core_extended.Deprecated_command.