Module `Command.Param`

Command-line parameter specification.

This module replaces Command.Spec, and should be used in all new code. Its types and compositional rules are much easier to understand.

module type S = sig ... end

include S

type +'a t

Command.Param is intended to be used with the [%map_open] syntax defined in ppx_let, like so:

let command =
  Command.basic ~summary:"..."
    [%map_open
      let count  = anon ("COUNT" %: int)
      and port   = flag "port" (optional int) ~doc:"N listen on this port"
      and person = person_param
      in
      (* ... Command-line validation code, if any, goes here ... *)
      fun () ->
        (* The body of the command *)
        do_stuff count port person
    ]

One can also use [%map_open] to define composite command line parameters, like person_param in the previous snippet:

type person = { name : string; age : int }

let person_param : person Command.Param.t =
  [%map_open
    let name = flag "name" (required string) ~doc:"X name of the person"
    and age  = flag "age"  (required int)    ~doc:"N how many years old"
    in
    {name; age}
  ]

The right-hand sides of [%map_open] definitions have Command.Param in scope.

Alternatively, you can say:

let open Foo.Let_syntax in
[%map_open
  let x ...
]

if Foo follows the same conventions as Command.Param.

See example/command/main.ml for more examples.

include Core_kernel__.Import.Applicative.S with type 'a t := 'a t

include Base__.Applicative_intf.For_let_syntax

type 'a t

val return : 'a -> 'a t
val map : 'a t -> f:('a -> 'b) -> 'b t
val both : 'a t -> 'b t -> ('a * 'b) t

include Base__.Applicative_intf.Applicative_infix with type 'a t := 'a t

type 'a t

val (<*>) : ('a -> 'b) t -> 'a t -> 'b t: same as apply

val (<*) : 'a t -> unit t -> 'a t
val (*>) : unit t -> 'a t -> 'a t
val (>>|) : 'a t -> ('a -> 'b) -> 'b t

val apply : ('a -> 'b) t -> 'a t -> 'b t
val map2 : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t
val map3 : 'a t -> 'b t -> 'c t -> f:('a -> 'b -> 'c -> 'd) -> 'd t
val all : 'a t list -> 'a list t
val all_unit : unit t list -> unit t

module Applicative_infix : Base__.Applicative_intf.Applicative_infix with type 'a t := 'a t

Various internal values

val help : Core_kernel__.Import.string Core_kernel.Lazy.t t: The help text for the command.

val path : Core_kernel__.Import.string Core_kernel__.Import.list t: The subcommand path of the command.

val args : Core_kernel__.Import.string Core_kernel__.Import.list t: The arguments passed to the command.

val flag : ?⁠aliases:Core_kernel__.Import.string Core_kernel__.Import.list -> ?⁠full_flag_required:Core_kernel__.Import.unit -> Core_kernel__.Import.string -> 'a Flag.t -> doc:Core_kernel__.Import.string -> 'a t

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.

All flags must have a dash at the beginning of the name. If name is not prefixed by "-", it will be normalized to "-" ^ name.

Unless full_flag_required is used, one doesn't have to pass name exactly on the command line, but only an unambiguous prefix of name (i.e., a prefix which is not a prefix of any other flag's name).

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.

NOTE: "-" by itself is an invalid flag name and will be rejected.

val flag_optional_with_default_doc : ?⁠aliases:Core_kernel__.Import.string Core_kernel__.Import.list -> ?⁠full_flag_required:Core_kernel__.Import.unit -> Core_kernel__.Import.string -> 'a Arg_type.t -> ('a -> Core_kernel.Sexp.t) -> default:'a -> doc:Core_kernel__.Import.string -> 'a t

flag_optional_with_default_doc name arg_type sexp_of_default ~default ~doc is a shortcut for flag, where:

The Flag.t is optional_with_default default arg_type
The doc is passed through with an explanation of what the default value appended.

val anon : 'a Anons.t -> 'a t: anon spec specifies a command that, among other things, takes the anonymous arguments specified by spec.

module If_nothing_chosen : sig ... end

val choose_one : 'a Core_kernel__.Import.option t Core_kernel__.Import.list -> if_nothing_chosen:('a, 'b) If_nothing_chosen.t -> 'b t: choose_one clauses ~if_nothing_chosen expresses a sum type. It raises if more than one of clauses is Some _. When if_nothing_chosen = `Raise, it also raises if none of clauses is Some _.

val and_arg_names : 'a t -> ('a * Core_kernel__.Import.string Core_kernel__.Import.list) t: and_arg_names t returns both the value of t and the names of the arguments that went into t. Useful for errors that reference multiple params.

val and_arg_name : 'a t -> ('a * Core_kernel__.Import.string) t: Like and_arg_names, but asserts that there is exactly one name.

module Arg_type : module type of Arg_type with type 'a Arg_type.t = 'a Arg_type.t

include module type of Arg_type.Export

val string : Core_kernel__.Import.string Arg_type.t
val int : Core_kernel__.Import.int Arg_type.t: Beware that an anonymous argument of type int cannot be specified as negative, as it is ambiguous whether -1 is a negative number or a flag. (The same applies to float, time_span, etc.) You can use the special built-in "-anon" flag to force a string starting with a hyphen to be interpreted as an anonymous argument rather than as a flag, or you can just make it a parameter to a flag to avoid the issue.

val char : Core_kernel__.Import.char Arg_type.t
val float : Core_kernel__.Import.float Arg_type.t
val bool : Core_kernel__.Import.bool Arg_type.t
val date : Core_kernel.Date.t Arg_type.t
val percent : Core_kernel.Percent.t Arg_type.t
val host_and_port : Core_kernel.Host_and_port.t Arg_type.t
val sexp : Core_kernel.Sexp.t Arg_type.t
val sexp_conv : (Core_kernel.Sexp.t -> 'a) -> 'a Arg_type.t

include module type of Flag with type 'a Flag.t := 'a Flag.t

type 'a t

val required : 'a Arg_type.t -> 'a t: Required flags must be passed exactly once.

val optional : 'a Arg_type.t -> 'a Core_kernel__.Import.option t: Optional flags may be passed at most once.

val optional_with_default : 'a -> 'a Arg_type.t -> 'a t: optional_with_default flags may be passed at most once, and default to a given value.

val listed : 'a Arg_type.t -> 'a Core_kernel__.Import.list t: listed flags may be passed zero or more times.

val one_or_more : 'a Arg_type.t -> ('a * 'a Core_kernel__.Import.list) t: one_or_more flags must be passed one or more times.

val no_arg : Core_kernel__.Import.bool t: 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 Core_kernel.Univ_map.With_default.Key.t -> value:'a -> Core_kernel__.Import.bool t: no_arg_register ~key ~value is like no_arg, but associates value with key in the autocomplete environment.

val no_arg_some : 'a -> 'a Core_kernel__.Import.option t: no_arg_some value is like no_arg, but will return Some value if the flag is passed on the command line, and return None otherwise.

val no_arg_abort : exit:(Core_kernel__.Import.unit -> Core_kernel__.Std_internal.never_returns) -> Core_kernel__.Import.unit t: 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 : Core_kernel__.Import.string Core_kernel__.Import.list Core_kernel__.Import.option t

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.

A standard choice of flag name to use with escape is "--".

val map_flag : 'a t -> f:('a -> 'b) -> 'b t: map_flag flag ~f transforms the parsed result of flag by applying f.

include module type of Anons with type 'a Anons.t := 'a Anons.t

type +'a t

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

(name %: typ) specifies a required anonymous argument of type typ.

The name must not be surrounded by whitespace; if it is, an exn will be raised.

If the name is surrounded by a special character pair (<>, {}, [] or (),) name will remain as-is, otherwise, name will be uppercased.

In the situation where name is only prefixed or only suffixed by one of the special character pairs, or different pairs are used (e.g., "<ARG]"), an exn will be raised.

The (possibly transformed) name is mentioned in the generated help for the command.

val sequence : 'a t -> 'a Core_kernel__.Import.list t: 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 non_empty_sequence_as_pair : 'a t -> ('a * 'a Core_kernel__.Import.list) t: non_empty_sequence_as_pair anons and non_empty_sequence_as_list anons are like sequence anons except that an exception will be raised if there is not at least one anonymous argument given.

val non_empty_sequence_as_list : 'a t -> 'a Core_kernel__.Import.list t
val maybe : 'a t -> 'a Core_kernel__.Import.option t: (maybe anons) indicates that some anonymous arguments are optional.

val maybe_with_default : 'a -> 'a t -> 'a t: (maybe_with_default default anons) indicates an optional anonymous argument with a default value.

t2, t3, and t4 each concatenate multiple anonymous argument specs into a single one. The purpose of these combinators is to allow for optional sequences of anonymous arguments. Consider a command with usage:

        main.exe FOO [BAR BAZ]

where the second and third anonymous arguments must either both be there or both not be there. This can be expressed as:

t2 ("FOO" %: foo) (maybe (t2 ("BAR" %: bar) ("BAZ" %: baz)))]

Sequences of 5 or more anonymous arguments can be built up using nested tuples:

maybe (t3 a b (t3 c d e))

val t2 : 'a t -> 'b t -> ('a * 'b) t
val t3 : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t
val t4 : 'a t -> 'b t -> 'c t -> 'd t -> ('a * 'b * 'c * 'd) t
val map_anons : 'a t -> f:('a -> 'b) -> 'b t: map_anons anons ~f transforms the parsed result of anons by applying f.