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
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 Base.Applicative.S with type 'a t := '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
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 : sig ... end

Various internal values

The help text for the command.

The subcommand path of the command.

The arguments passed to the command.

val flag : ?aliases:Base.string Base.list -> ?full_flag_required:Base.unit -> Base.string -> 'a Flag.t -> doc:Base.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:Base.string Base.list -> ?full_flag_required:Base.unit -> Base.string -> 'a Arg_type.t -> ('a -> Base.Sexp.t) -> default:'a -> doc:Base.string -> 'a t

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

  1. The Flag.t is optional_with_default default arg_type
  2. 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.

val escape_anon : final_anon:'a Anons.t -> ('a * Base.string Base.list) t

escape_anon ~final_anon parses anon and then stops parsing. Remaining command line arguments are collected in the string list, even if they start with dashes.

See escape for the flag version of this behavior.

The final anon is required to indicate when to stop parsing.

module If_nothing_chosen : sig ... end
val choose_one : 'a Base.option t Base.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 choose_one_non_optional : 'a t Base.list -> if_nothing_chosen:('a, 'b) If_nothing_chosen.t -> 'b t

choose_one_non_optional clauses ~if_nothing_chosen expresses a sum type. It raises if more than one of the clauses has any flags given on the command-line, and returns the value parsed from the clause that's given.

When if_nothing_chosen = Raise, it also raises if none of the clauses are given.

val and_arg_names : 'a t -> ('a * Base.string Base.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 * Base.string) t

Like and_arg_names, but asserts that there is exactly one name.

val arg_names : 'a t -> Base.string Base.list
val optional_to_required : 'a Base.option t -> 'a t

If None is returned, then the param acts as a required flag that was omitted. This is intended to be used with choose_one_non_optional.

Values included for convenience so you can specify all command line parameters inside a single local open of Param.

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

Values to include in other namespaces.

val string : Base.string 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 sexp_conv : ?complete:Auto_complete.t -> (Base.Sexp.t -> 'a) -> 'a Arg_type.t
include module type of Flag with type 'a t := 'a Flag.t

Command-line flag specifications.

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

Required flags must be passed exactly once.

val optional : 'a Arg_type.t -> 'a Base.option Flag.t

Optional flags may be passed at most once.

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

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

val listed : 'a Arg_type.t -> 'a Base.list Flag.t

listed flags may be passed zero or more times.

val one_or_more_as_pair : 'a Arg_type.t -> ('a * 'a Base.list) Flag.t

one_or_more_as_pair flags must be passed one or more times.

val one_or_more_as_list : 'a Arg_type.t -> 'a Base.list Flag.t

Like one_or_more_as_pair, but returns the flag values as a list.

val no_arg : Base.bool Flag.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 Univ_map.With_default.Key.t -> value:'a -> Base.bool Flag.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 Base.option Flag.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_required : 'a -> 'a Flag.t

no_arg_some value is like no_arg, but the argument is required. This is useful in combination with choose_one_non_optional.

val no_arg_abort : exit:(Base.unit -> Base.Nothing.t) -> Base.unit Flag.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.

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 escape_with_autocomplete : complete:Auto_complete.For_escape.t -> Base.string Base.list Base.option Flag.t
val map_flag : 'a Flag.t -> f:('a -> 'b) -> 'b Flag.t

map_flag flag ~f transforms the parsed result of flag by applying f.

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

Anonymous command-line argument specification.

val (%:) : Base.string -> 'a Arg_type.t -> 'a Anons.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 Anons.t -> 'a Base.list Anons.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 Anons.t -> ('a * 'a Base.list) Anons.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 Anons.t -> 'a Base.list Anons.t
val maybe : 'a Anons.t -> 'a Base.option Anons.t

(maybe anons) indicates that some anonymous arguments are optional.

val maybe_with_default : 'a -> 'a Anons.t -> 'a Anons.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 Anons.t -> 'b Anons.t -> ('a * 'b) Anons.t
val t3 : 'a Anons.t -> 'b Anons.t -> 'c Anons.t -> ('a * 'b * 'c) Anons.t
val t4 : 'a Anons.t -> 'b Anons.t -> 'c Anons.t -> 'd Anons.t -> ('a * 'b * 'c * 'd) Anons.t
val map_anons : 'a Anons.t -> f:('a -> 'b) -> 'b Anons.t

map_anons anons ~f transforms the parsed result of anons by applying f.

val parse : 'a t -> Base.string Base.list -> 'a Base.Or_error.t

parse t cmdline will attempt to parse t out of cmdline. Beware there is nothing stopping effectful operations in t from being performed.