Module Arg.Completion

Argument completion.

This module provides a type to describe how positional and optional argument values described by argument converters can be completed. It defines which completion directives from the protocol get emitted by your tool for the argument.

Note. Subcommand and option name completion is done automatically by the library itself. Prefined argument converters already have completions built-in whenever appropriate.

Completion directives

type 'a directive

The type for a completion directive for values of type 'a.

val value : ?doc:string -> 'a -> 'a directive

value v ~doc indicates that the token to complete could be replaced by the value v as serialized by the argument's formatter Conv.pp. doc is ANSI styled UTF-8 text documenting the value, defaults to "".

val string : ?doc:string -> string -> 'a directive

string s ~doc indicates that the token to complete could be replaced by the string s. doc is ANSI styled UTF-8 text documenting the value, defaults to "".

val files : 'a directive

files indicates that the token to complete could be replaced with files that the shell deems suitable.

val dirs : 'a directive

dirs indicates that the token to complete could be replaced with directories that the shell deems suitable.

val restart : 'a directive

restart indicates that the shell should restart the completion after the positional disambiguation token --.

This is typically used for tools that end-up invoking other tools like sudo -- TOOL [ARG]…. For the latter a restart completion should be added on all positional arguments. If you allow TOOL to be only a restricted set of tools known to your program you'd eschew restart on the first postional argument but add it to the remaining ones.

Warning. A restart directive is eventually emited only if the completion is requested after a -- token. In this case other completions returned alongside by func are ignored. Educate your users to use the --, for example mention them in user defined synopses. It is good cli specification hygiene anyways as it properly delineates argument scopes.

val raw : string -> 'a directive

raw s takes over the whole protocol output (including subcommand and option name completion) with s, you are in charge. Any other directive in the result of func is ignored.

Warning. The protocol is unstable, it is not advised to output it yourself.

Completion

type ('ctx, 'a) func = 'ctx option -> token:string -> ('a directive list, string) Stdlib.result

The type for completion functions.

Given an optional context determined from a partial command line parse and a token to complete it returns a list of completion directives or an error which is reported to end-users via the protocol.

type 'a complete =
  1. | Complete : 'ctx Term.t option * ('ctx, 'a) func -> 'a complete

The type for completing.

A completion context specification which captures a partial command line parse (for example the path to a configuration file) and a completion function.

type 'a t

The type for completing values parsed into values of type 'a.

val make : ?context:'ctx Term.t -> ('ctx, 'a) func -> 'a t

make ~context func uses func to complete.

context defines a commmand line fragment that is evaluated before performing the completion. It the evaluation is successful the result is given to the completion function otherwise None is given.

Warning. context must be part of the term of the command in which you use the completion otherwise the context will always be None in the function.

val complete : 'a t -> 'a complete

complete c completes with c.

val complete_files : 'a t

complete_files holds a context insensitive function that always returns Ok [files].

val complete_dirs : 'a t

complete_dirs holds a context insensitive function that always returns Ok [dirs].

val complete_paths : 'a t

complete_paths holds a context insensitive function that always returns Ok [files;dirs

\]].
val complete_restart : 'a t

complete_dirs holds a context insensitive function that always returns Ok [restart].