module Spec: sig .. end

composable command-line specifications

type 'a param 

specification of an individual parameter to the command's main function

val const : 'a -> 'a param

a hard-coded parameter

val map : 'a param -> f:('a -> 'b) -> 'b param

parameter transformation

val help : string Lazy.t param

the help text for the command

val path : string list param

the subcommand path of the command

val args : string list param

the arguments passed to the command

type ('main_in, 'main_out) t 

composable command-line specifications

Ultimately one forms a base command by combining a spec of type ('main, unit) t with a main function of type 'main; see the basic function below. Combinators in this library incrementally build up the type of main according to what command-line parameters it expects, so the resulting type of main is something like:

arg1 -> ... -> argN -> unit

It may help to think of ('a, 'b) t as a function space 'a -> 'b embellished with information about:

• how to parse command line
• what the command does and how to call it
• how to auto-complete a partial command line

One can view a value of type ('main_in, 'main_out) t as function that transforms a main function from type 'main_in to 'main_out, typically by supplying some arguments. E.g. a value of type Spec.t might have type:

| (arg1 -> ... -> argN -> 'r, 'r) Spec.t

Such a value can transform a main function of type arg1 -> ... -> argN -> 'r by supplying it argument values of type arg1, ..., argn, leaving a main function whose type is 'r. In the end, Command.basic takes a completed spec where 'r = unit, and hence whose type looks like:

| (arg1 -> ... -> argN -> unit, unit) Spec.t

A value of this type can fully apply a main function of type arg1 -> ... -> argN -> unit to all its arguments.

The view of ('main_in, main_out) Spec.t as a function from 'main_in to 'main_out is directly reflected by the step function, whose type is:

| val step : ('m1 -> 'm2) -> ('m1, 'm2) t

val empty : ('m, 'm) t

the empty command-line spec

val (++) : ('m1, 'm2) t ->
       ('m2, 'm3) t -> ('m1, 'm3) t

command-line spec composition

val (+>) : ('m1, 'a -> 'm2) t ->
       'a param -> ('m1, 'm2) t

add a rightmost parameter onto the type of main

val (+<) : ('m1, 'm2) t ->
       'a param -> ('a -> 'm1, 'm2) t

add a leftmost parameter onto the type of main

this function should only be used as a workaround in situations where the order of composition is at odds with the order of anonymous arguments due to factoring out some common spec

val step : ('m1 -> 'm2) -> ('m1, 'm2) t

combinator for patching up how parameters are obtained or presented

Here are a couple examples of some of its many uses

• introducing labeled arguments

  step (fun m v -> m ~foo:v)
                 +> flag "-foo" no_arg : (foo:bool -> 'm, 'm) t

• prompting for missing values

  step (fun m user -> match user with
                   | Some user -> m user
                   | None -> print_string "enter username: "; m (read_line ()))
                 +> flag "-user" (optional string) ~doc:"USER to frobnicate"
                 : (string -> 'm, 'm) t

A use of step might look something like:

| step (fun main -> let ... in main x1 ... xN) : (arg1 -> ... -> argN -> 'r, 'r) t

Thus, step allows one to write arbitrary code to decide how to transform a main function. As a simple example:

| step (fun main -> main 13.) : (float -> 'r, 'r) t

This spec is identical to const 13.; it transforms a main function by supplying it with a single float argument, 13.. As another example:

| step (fun m v -> m ~foo:v) : (foo:'foo -> 'r, 'foo -> 'r) t

This spec transforms a main function that requires a labeled argument into a main function that requires the argument unlabeled, making it easily composable with other spec combinators.

val wrap : (run:('m1 -> 'r1) -> main:'m2 -> 'r2) ->
       ('m1, 'r1) t -> ('m2, 'r2) t

combinator for defining a class of commands with common behavior

Here are two examples of command classes defined using wrap

• print top-level exceptions to stderr

  wrap (fun ~run ~main ->
                   Exn.handle_uncaught ~exit:true (fun () -> run main)
                 ) : ('m, unit) t -> ('m, unit) t
              

• iterate over lines from stdin

  wrap (fun ~run ~main ->
                   In_channel.iter_lines stdin ~f:(fun line -> run (main line))
                 ) : ('m, unit) t -> (string -> 'm, unit) t
              

module Arg_type: sig .. end

val string : string Arg_type.t

val int : int Arg_type.t

val float : float Arg_type.t

val bool : bool Arg_type.t

val date : Date.t Arg_type.t

val time_span : Span.t Arg_type.t

val file : string Arg_type.t

type 'a flag 

a flag specification

val flag : ?aliases:string list ->
       string -> 'a flag -> doc:string -> 'a param

flag name spec ~doc specifies a command that, among other things, takes a flag named name on its command line. doc indicates the meaning of the flag.

NOTE: the doc for a flag which takes an argument should be of the form arg_name ^ " " ^ description where arg_name describes the argument and description describes the meaning of the flag.

NOTE: flag names (including aliases) containing underscores will be rejected. Use dashes instead.

val required : 'a Arg_type.t -> 'a flag

required flags must be passed exactly once

val optional : 'a Arg_type.t -> 'a option flag

optional flags may be passed at most once

val optional_with_default : 'a -> 'a Arg_type.t -> 'a flag

optional_with_default flags may be passed at most once, and default to a given value

val listed : 'a Arg_type.t -> 'a list flag

listed flags may be passed zero or more times

val no_arg : bool flag

no_arg flags may be passed at most once. The boolean returned is true iff the flag is passed on the command line

val no_arg_register : key:'a Univ_map.With_default.Key.t -> value:'a -> bool flag

no_arg_register ~key ~value is like no_arg, but associates value with key in the in the auto-completion environment

val no_arg_abort : exit:(unit -> Std_internal.never_returns) -> unit flag

no_arg_abort ~exit is like no_arg, but aborts command-line parsing by calling exit. This flag type is useful for "help"-style flags that just print something and exit.

val escape : string list option flag

escape flags may be passed at most once. They cause the command line parser to abort and pass through all remaining command line arguments as the value of the flag.

type 'a anons 

a specification of some number of anonymous arguments

val anon : 'a anons -> 'a param

anon spec specifies a command that, among other things, takes the anonymous arguments specified by spec.

val (%:) : string -> 'a Arg_type.t -> 'a anons

(name %: typ) specifies a required anonymous argument of type typ. The name is mentioned in the generated help for the command.

val sequence : 'a anons -> 'a list anons

sequence anons specifies a sequence of anonymous arguments. An exception will be raised if anons matches anything other than a fixed number of anonymous arguments

val maybe : 'a anons -> 'a option anons

(maybe anons) indicates that some anonymous arguments are optional

val maybe_with_default : 'a -> 'a anons -> 'a anons

(maybe_with_default default anons) indicates an optional anonymous argument with a default value

val t2 : 'a anons ->
       'b anons -> ('a * 'b) anons

val t3 : 'a anons ->
       'b anons ->
       'c anons -> ('a * 'b * 'c) anons

val t4 : 'a anons ->
       'b anons ->
       'c anons ->
       'd anons -> ('a * 'b * 'c * 'd) anons