Cmdliner

https://erratique.ch/software/cmdliner/doc
Admin
Cmdliner provides a simple and compositional mechanism to convert command line arguments to OCaml...
Tokens:33,750
Snippets:175
Trust Score:9.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Example Man Page Generated by Cmdliner

Source: https://erratique.ch/software/cmdliner/doc/tutorial

This is an example of the man page generated automatically by Cmdliner based on the provided command information, option definitions, and documentation strings. It includes sections for NAME, SYNOPSIS, ARGUMENTS, OPTIONS, COMMON OPTIONS, EXIT STATUS, ENVIRONMENT, and BUGS.

```text
> ocamlfind ocamlopt -linkpkg -package cmdliner -o chorus chorus.ml
> ./chorus --help
NAME
       chorus - Print a customizable message repeatedly

SYNOPSIS
       chorus [--count=COUNT] [OPTION]… [MSG]

ARGUMENTS
       MSG (absent=Revolt! or CHORUS_MSG env)
           The message to print.

OPTIONS
       -c COUNT, --count=COUNT (absent=10)
           Repeat the message COUNT times.

COMMON OPTIONS
       --help[=FMT] (default=auto)
           Show this help in format FMT. The value FMT must be one of auto,
           pager, groff or plain. With auto, the format is pager or plain
           whenever the TERM env var is dumb or undefined.

       --version
           Show version information.

EXIT STATUS
       chorus exits with the following status:

       0   on success.

       123 on indiscriminate errors reported on standard error.

       124 on command line parsing errors.

       125 on unexpected internal errors (bugs).

ENVIRONMENT
       These environment variables affect the execution of chorus:

       CHORUS_MSG
           Overrides the default message to print.

BUGS
       Email bug reports to <bugs@example.org>.

```

--------------------------------

### Opam Build Instruction for Cmdliner Tool Support

Source: https://erratique.ch/software/cmdliner/doc/cookbook

This snippet shows how to integrate the installation of completion scripts and manpages for a Cmdliner tool into an `opam` package's build instructions. It uses the `cmdliner install tool-support` command and specifies paths for the executable and installation directory. This ensures that support files are generated correctly during package installation.

```bash
build: [
  [ … ] # Your regular build instructions
  ["cmdliner" "install" "tool-support"
              "--update-opam-install=%{_:name}%.install"
              "$BUILD/tool" "_build/cmdliner-install"]]
```

--------------------------------

### Opam Install Instruction for Cmdliner

Source: https://erratique.ch/software/cmdliner/doc/cookbook

This snippet shows how to add the `cmdliner install` instruction to the `build:` field of an opam file for a tool named `tool`. It specifies build instructions for regular dune builds and the Cmdliner installation process, handling different operating systems.

```opam
build:
[
   [ "opam-as-root" "--destdir" "%{recipe}%/" "--install-dir" "%{recipe}%/" "--install-file" "%{recipe}%/lib/conf-foo/conf-foo.install" ]
   [ "dune" "build" "-p" name "--pkg" name ]
   [ "cmdliner" "install" "tool-support"
               "--update-opam-install=%{_:name}%.install"
               "_build/install/default/bin/tool" {os-family != "windows"}
               "_build/install/default/bin/tool.exe" {os-family = "windows"}
               "_build/cmdliner-install"]
]
```

--------------------------------

### Install Tool Manpages with Cmdliner

Source: https://erratique.ch/software/cmdliner/doc/cli

Shows how to install man pages for a tool and its subcommands to a specified man directory. It explains how to specify the tool by its name in the PATH or by its explicit file path.

```bash
cmdliner install tool-manpages thetool $MANDIR
```

--------------------------------

### Implement 'initialize' Subcommand with Cmdliner (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/examples

Implements the 'initialize' subcommand for the darcs command-line tool. It takes a repository directory as input and uses Cmdliner to parse the command-line arguments.

```OCaml
let initialize copts repodir = Printf.printf
    "%arepodir = %s\n" pr_copts copts repodir

let initialize_cmd =
  let repodir =
    let doc = "Run the program in repository directory $(docv)." in
    Arg.(value & opt file Filename.current_dir_name & info ["repodir"]
           ~docv:"DIR" ~doc)
  in
  let doc = "make the current directory a repository" in
  let man = [
    `S Manpage.s_description;
    `P "Turns the current directory into a Darcs repository. Any\n       existing files and subdirectories become …";
    `Blocks help_secs; ]
  in
  Cmd.make (Cmd.info "initialize" ~doc ~sdocs ~man) @@
  let+ copts_t and+ repodir in
  initialize copts_t repodir
```

--------------------------------

### Implement 'help' Subcommand with Cmdliner (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/examples

Implements the 'help' subcommand, which displays help information about commands or topics. It uses Cmdliner's `Cmdliner.Term.ret` to generate help messages.

```OCaml
let help copts man_format cmds topic = match topic with
| None -> `Help (`Pager, None) (* help about the program. *)
| Some topic ->
    let topics = "topics" :: "patterns" :: "environment" :: cmds in
    let conv = Cmdliner.Arg.enum (List.rev_map (fun s -> (s, s)) topics) in
    let parse = Cmdliner.Arg.Conv.parser conv in
    match parse topic with
    | Error e -> `Error (false, e)
    | Ok t when t = "topics" -> List.iter print_endline topics; `Ok ()
    | Ok t when List.mem t cmds -> `Help (man_format, Some t)
    | Ok t ->
        let page = (topic, 7, "", "", ""), [`S topic; `P "Say something";] in
        `Ok (Cmdliner.Manpage.print man_format Format.std_formatter page)
```

--------------------------------

### Cmdliner Completion Protocol Example

Source: https://erratique.ch/software/cmdliner/doc/cli

Demonstrates how to invoke a Cmdliner-based tool to inspect its command-line completions.

```shell
cmdliner --__complete --__complete=
```

--------------------------------

### Install Tool-Specific Completion Scripts with Cmdliner

Source: https://erratique.ch/software/cmdliner/doc/cli

Instructions for installing completion definitions for a specific tool (e.g., 'thetool') that uses Cmdliner. These commands generate and install tool-specific scripts, relying on the generic scripts to be present.

```bash
cmdliner tool-completion zsh thetool  # Output tool zsh script on stdout.
cmdliner install tool-completion thetool $SHAREDIR             # All shells
cmdliner install tool-completion --shell zsh thetool $SHAREDIR # Only zsh
```

--------------------------------

### Define 'help' command for documentation (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/examples

Defines the 'help' command, which displays help about 'darcs' and its subcommands. It allows users to specify a topic for detailed information or list available topics. This command is crucial for user guidance and understanding the system's capabilities.

```ocaml
let help_cmd = 
  let topic = 
    let doc = "The topic to get help on. $(b,topics) lists the topics." in
    Arg.(value & pos 0 (some string) None & info [] ~docv:"TOPIC" ~doc)
  in
  let doc = "display help about darcs and darcs commands" in
  let man = 
    [`S Manpage.s_description;
     `P "Prints help about darcs commands and other subjects...";
     `Blocks help_secs; ]
  in
  Cmd.make (Cmd.info "help" ~doc ~man) @@
  Term.ret @@
  let+ copts_t and+ man_format = Arg.man_format
  and+ choice_names = Term.choice_names and+ topic in
  help copts_t man_format choice_names topic
```

--------------------------------

### OCaml Tail Command Implementation

Source: https://erratique.ch/software/cmdliner/doc/examples

The core OCaml implementation of the tail command, defining data types for options and the main function that processes parsed arguments. It prints the received arguments to standard output.

```ocaml
(* Implementation of the command, we just print the args. *)

type loc = bool * int
type verb = Verbose | Quiet
type follow = Name | Descriptor

let str = Printf.sprintf
let opt_str sv = function None -> "None" | Some v -> str "Some(%s)" (sv v)
let loc_str (rev, k) = if rev then str "%d" k else str "+%d" k
let follow_str = function Name -> "name" | Descriptor -> "descriptor"
let verb_str = function Verbose -> "verbose" | Quiet -> "quiet"

let tail ~lines ~follow ~verb ~pid files =
  Printf.printf
    "lines = %s\nfollow = %s\nverb = %s\npid = %s\nfiles = %s\n"
    (loc_str lines) (opt_str follow_str follow) (verb_str verb)
    (opt_str string_of_int pid) (String.concat ", " files)

```

--------------------------------

### Define a simple command using Cmdliner term syntax (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/tutorial

This snippet demonstrates a more concise way to define a Cmdliner command using OCaml's `let+` binding syntax. It achieves the same result as the previous example: printing 'Revolt!' to standard output.

```ocaml
let revolt () = print_endline "Revolt!"

open Cmdliner
open Cmdliner.Term.Syntax

let cmd_revolt = 
  Cmd.make (Cmd.info "revolt") @@
  let+ () = Term.const () in
  revolt () 

let main () = Cmd.eval cmd_revolt
let () = if !Sys.interactive then () else exit (main ())
```

--------------------------------

### Install Generic Completion Scripts with Cmdliner

Source: https://erratique.ch/software/cmdliner/doc/cli

Commands to inspect and install generic completion scripts for various shells using the `cmdliner generic-completion` command. These scripts should be installed in subdirectories of a designated share directory (`$SHAREDIR`).

```bash
SHAREDIR="$DESTDIR/$PREFIX/share"
cmdliner generic-completion zsh   # Output generic zsh script on stdout
cmdliner install generic-completion $SHAREDIR             # All shells
cmdliner install generic-completion --shell zsh $SHAREDIR # Only zsh
```

--------------------------------

### Implement 'record' Subcommand with Cmdliner (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/examples

Defines the 'record' subcommand, which captures patch metadata such as name, author, whether to apply to all files, and whether to ask for extra dependencies. Uses Cmdliner to define and parse the command line arguments.

```OCaml
let record copts name email all ask_deps files = Printf.printf
    "%aname = %s\nemail = %s\nall = %B\nask-deps = %B\nfiles = %s\n"
    pr_copts copts (opt_str_str name) (opt_str_str email) all ask_deps
    (String.concat ", " files)

let record_cmd =
  let pname =
    let doc = "Name of the patch." in
    Arg.(value & opt (some string) None & info ["m"; "patch-name"] ~docv:"NAME"
           ~doc)
  in
  let author =
    let doc = "Specifies the author's identity." in
    Arg.(value & opt (some string) None & info ["A"; "author"] ~docv:"EMAIL"
           ~doc)
  in
  let all =
    let doc = "Answer yes to all patches." in
    Arg.(value & flag & info ["a"; "all"] ~doc)
  in
  let ask_deps =
    let doc = "Ask for extra dependencies." in
    Arg.(value & flag & info ["ask-deps"] ~doc)
  in
```

--------------------------------

### Define Common Options for Darcs Command (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/examples

Defines a record type `copts` to store common command-line options like debug, verbosity, and prehook. It also defines a term `copts_t` to represent these options in Cmdliner.

```OCaml
type verb = Normal | Quiet | Verbose
type copts = { debug : bool; verb : verb; prehook : string option }

let str = Printf.sprintf
let opt_str sv = function None -> "None" | Some v -> str "Some(%s)" (sv v)
let opt_str_str = opt_str (fun s -> s)
let verb_str = function
  | Normal -> "normal" | Quiet -> "quiet" | Verbose -> "verbose"

let pr_copts oc copts = Printf.fprintf oc
    "debug = %B\nverbosity = %s\nprehook = %s\n"
    copts.debug (verb_str copts.verb) (opt_str_str copts.prehook)

let copts debug verb prehook = { debug; verb; prehook }
let copts_t =
  let docs = Manpage.s_common_options in
  let debug = 
    let doc = "Give only debug output." in
    Arg.(value & flag & info ["debug"] ~docs ~doc)
  in
  let verb =
    let doc = "Suppress informational output." in
    let quiet = Quiet, Arg.info ["q"; "quiet"] ~docs ~doc in
    let doc = "Give verbose output." in
    let verbose = Verbose, Arg.info ["v"; "verbose"] ~docs ~doc in
    Arg.(last & vflag_all [Normal] [quiet; verbose])
  in
  let prehook =
    let doc = "Specify command to run before this $(tool) command." in
    Arg.(value & opt (some string) None & info ["prehook"] ~docs ~doc)
  in
  Term.(const copts $ debug $ verb $ prehook)
```

--------------------------------

### Entry point for executing the main command (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/examples

Provides the main entry point for executing the 'darcs' command-line interface. It uses 'Cmd.eval' to process the 'main_cmd' definition and handles the program's exit status. This is the standard way to launch applications defined with the cmdliner library.

```ocaml
let main () = Cmd.eval main_cmd
let () = if !Sys.interactive then () else exit (main ())
```

--------------------------------

### OCaml cp command implementation and CLI definition

Source: https://erratique.ch/software/cmdliner/doc/examples

This OCaml code defines the implementation logic and command-line interface for a `cp` command using the Cmdliner library. It parses verbose, recursive, and force flags, along with source files and a destination. The implementation includes a check to ensure the destination is a directory when multiple sources are provided. Dependencies include the `Cmdliner` library and `Sys` module.

```ocaml
(* Implementation, we check the dest argument and print the args *)

let cp ~verbose ~recurse ~force srcs dest = 
  let many = List.length srcs > 1 in
  if many && (not (Sys.file_exists dest) || not (Sys.is_directory dest))
  then `Error (false, dest ^ ": not a directory") else
  `Ok (Printf.printf
         "verbose = %B\nrecurse = %B\nforce = %B\nsrcs = %s\ndest = %s\n"
         verbose recurse force (String.concat ", " srcs) dest)

(* Command line interface *)

open Cmdliner
open Cmdliner.Term.Syntax

let verbose = 
  let doc = "Print file names as they are copied." in
  Arg.(value & flag & info ["v"; "verbose"] ~doc)

let recurse = 
  let doc = "Copy directories recursively." in
  Arg.(value & flag & info ["r"; "R"; "recursive"] ~doc)

let force = 
  let doc = "If a destination file cannot be opened, remove it and try again."in
  Arg.(value & flag & info ["f"; "force"] ~doc)

let srcs = 
  let doc = "Source file(s) to copy." in
  Arg.(non_empty & pos_left ~rev:true 0 file [] & info [] ~docv:"SOURCE" ~doc)

let dest = 
  let doc = "Destination of the copy. Must be a directory if there is more \n             than one $(i,SOURCE)." in
  let docv = "DEST" in
  Arg.(required & pos ~rev:true 0 (some string) None & info [] ~docv ~doc)

let cp_cmd = 
  let doc = "Copy files" in
  let man_xrefs = 
    [`Tool "mv"; `Tool "scp"; `Page ("umask", 2); `Page ("symlink", 7)]
  in
  let man = [
    `S Manpage.s_bugs;
    `P "Email them to <bugs@example.org>."; ]
  in
  Cmd.make (Cmd.info "cp" ~version:"%%VERSION%%" ~doc ~man ~man_xrefs) @@
  Term.ret @@
  let+ verbose and+ recurse and+ force and+ srcs and+ dest in
  cp ~verbose ~recurse ~force srcs dest

let main () = Cmd.eval cp_cmd
let () = if !Sys.interactive then () else exit (main ())
```

--------------------------------

### Define 'record' command for patch creation (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/examples

Defines the 'record' command, which creates a patch from unrecorded changes in the working tree. It accepts file arguments and uses a set of options for customization. The command is part of a larger command-line interface structure.

```ocaml
let files = Arg.(value & (pos_all file) [] & info [] ~docv:"FILE or DIR") in
let doc = "create a patch from unrecorded changes" in
let man = 
  [`S Manpage.s_description;
   `P "Creates a patch from changes in the working tree. If you specify
       a set of files...";
   `Blocks help_secs; ]
in
Cmd.make (Cmd.info "record" ~doc ~sdocs ~man) @@
let+ copts_t and+ pname and+ author and+ all and+ ask_deps and+ files in
record copts_t pname author all ask_deps files
```

--------------------------------

### Define main command group for 'darcs' (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/examples

Defines the main command group for the 'darcs' revision control system. It includes the 'darcs' command information and sets a default action to display help if no subcommand is provided. This structure integrates 'initialize_cmd', 'record_cmd', and 'help_cmd'.

```ocaml
let main_cmd = 
  let doc = "a revision control system" in
  let man = help_secs in
  let info = Cmd.info "darcs" ~version:"%%VERSION%%" ~doc ~sdocs ~man in
  let default = Term.(ret (const (fun _ -> `Help (`Pager, None)) $ copts_t)) in
  Cmd.group info ~default [initialize_cmd; record_cmd; help_cmd]
```

--------------------------------

### OCaml Cmdliner Command Definition for Tail

Source: https://erratique.ch/software/cmdliner/doc/examples

Defines the Cmdliner command structure for the tail program, including its name, version, documentation, and man page sections. It associates the command information with the term that parses and collects the arguments.

```ocaml
let tail_cmd =
  let doc = "Display the last part of a file" in
  let man = [
    `S Manpage.s_description;
    `P "$(cmd) prints the last lines of each $(i,FILE) to standard output.
        If no file is specified reads standard input. The number of printed
        lines can be  specified with the $(b,-n) option.";
    `S Manpage.s_bugs;
    `P "Report them to <bugs@example.org>.";
    `S Manpage.s_see_also;
    `P "$(b,cat)(1), $(b,head)(1)" ]
  in
  Cmd.make (Cmd.info "tail" ~version:"%%VERSION%%" ~doc ~man) @@
  let+ lines and+ follow and+ verb and+ pid and+ files in
  tail ~lines ~follow ~verb ~pid files

```

--------------------------------

### Cmdliner Argument Definitions for File Paths with Stdin/Stdout

Source: https://erratique.ch/software/cmdliner/doc/cookbook

These examples define `infile` and `outfile` arguments using Cmdliner. They demonstrate how to use `filepath` and specify `-` as a convention for stdin/stdout, providing user-friendly documentation strings.

```ocaml
let infile =
  let doc = "$(docv) is the file to read from. Use $(b,-) for $(b,stdin)" in
  Arg.(value & opt filepath "-" & info ["i", "input-file"] ~doc ~docv:"FILE")

let outfile =
  let doc = "$(docv) is the file to write to. Use $(b,-) for $(b,stdout)" in
  Arg.(value & opt filepath "-" & info ["o", "output-file"] ~doc ~docv:"FILE")
```

--------------------------------

### Implement `rm` command with Cmdliner

Source: https://erratique.ch/software/cmdliner/doc/examples

This snippet shows how to implement an `rm` command using Cmdliner. It defines argument parsing for prompt behavior (`-f`, `-i`, `-I`), recursive removal (`-r`), and file arguments. The implementation maps flags to a `prompt` type and handles recursive flags.

```ocaml
(* Implementation of the command, we just print the args. *)

type prompt = Always | Once | Never
let prompt_str = function
| Always -> "always" | Once -> "once" | Never -> "never"

let rm ~prompt ~recurse files = 
  Printf.printf "prompt = %s\nrecurse = %B\nfiles = %s\n" 
    (prompt_str prompt) recurse (String.concat ", " files)

(* Command line interface *)

open Cmdliner
open Cmdliner.Term.Syntax

let files = Arg.(non_empty & pos_all file [] & info [] ~docv:"FILE")
let prompt = 
  let always = 
    let doc = "Prompt before every removal." in 
    Always, Arg.info ["i"] ~doc 
  in 
  let never = 
    let doc = "Ignore nonexistent files and never prompt." in 
    Never, Arg.info ["f"; "force"] ~doc 
  in 
  let once = 
    let doc = "Prompt once before removing more than three files, or when\n               removing recursively. Less intrusive than $(b,-i), while\n               still giving protection against most mistakes." 
    in 
    Once, Arg.info ["I"] ~doc 
  in 
  Arg.(last & vflag_all [Always] [always; never; once])

let recursive = 
  let doc = "Remove directories and their contents recursively." in 
  Arg.(value & flag & info ["r"; "R"; "recursive"] ~doc)

let rm_cmd = 
  let doc = "Remove files or directories" in 
  let man = [
    `S Manpage.s_description;
    `P "$(cmd) removes each specified $(i,FILE). By default it does not
        remove directories, to also remove them and their contents, use the
        option $(b,--recursive) ($(b,-r) or $(b,-R)).";
    `P "To remove a file whose name starts with a $(b,-), for example
        $(b,-foo), use one of these commands:";
    `Pre "$(cmd) $(b,-- -foo)"; `Noblank;
    `Pre "$(cmd) $(b,./-foo)";
    `P "$(cmd.name) removes symbolic links, not the files referenced by the
        links.";
    `S Manpage.s_bugs; `P "Report bugs to <bugs@example.org>.";
    `S Manpage.s_see_also; `P "$(b,rmdir)(1), $(b,unlink)(2)" ]
  in 
  Cmd.make (Cmd.info "rm" ~version:"%%VERSION%%" ~doc ~man) @@ 
  let+ prompt and+ recursive and+ files in 
  rm ~prompt ~recurse:recursive files

let main () = Cmd.eval rm_cmd
let () = if !Sys.interactive then () else exit (main ())
```

--------------------------------

### OCaml Cmdliner Main Execution Entry Point

Source: https://erratique.ch/software/cmdliner/doc/examples

Provides the main entry point for the OCaml program. It evaluates the defined Cmdliner command and exits with the appropriate status code. This function is typically called only when the script is run directly, not when loaded interactively.

```ocaml
let main () = Cmd.eval tail_cmd
let () = if !Sys.interactive then () else exit (main ())
```

--------------------------------

### Configure Bash Command Line Completion

Source: https://erratique.ch/software/cmdliner/doc/cli

Details the steps for end-users to enable command-line completion for Cmdliner-based tools in bash, assuming `bash-completion` is installed. It covers setting `XDG_DATA_DIRS` and testing the completion loader.

```bash
XDG_DATA_DIRS="$(opam var share):${XDG_DATA_DIRS}"
```

```bash
> _completion_loader _cmdliner_generic
> declare -F _cmdliner_generic &>/dev/null && echo "Found" || echo "Not found"
Found!
```

```bash
_completion_loader _cmdliner_generic
complete -F _cmdliner_generic thetool
```

--------------------------------

### OCaml Cmdliner Argument Parsers for Tail Command

Source: https://erratique.ch/software/cmdliner/doc/examples

Defines custom argument converters and option definitions for the tail command using Cmdliner. This includes parsing for the --lines option (handling '+' prefix), the --follow option with an enumerated type, verbosity flags, and PID tracking.

```ocaml
(* Command line interface *)

open Cmdliner
open Cmdliner.Term.Syntax

let loc_arg =
  let parser s =
    try
      if s <> "" && s.[0] <> '+'
      then Ok (true, int_of_string s)
      else Ok (false, int_of_string (String.sub s 1 (String.length s - 1)))
    with Failure _ -> Error "unable to parse integer"
  in
  let pp ppf p = Format.fprintf ppf "%s" (loc_str p) in
  Arg.Conv.make ~docv:"N" ~parser ~pp ()

let lines =
  let doc = "Output the last $(docv) lines or use $(i,+)$(docv) to start \n             output after the $(i,N)-1th line." in
  Arg.(value & opt loc_arg (true, 10) & info ["n"; "lines"] ~docv:"N" ~doc)

let follow =
  let doc = "Output appended data as the file grows. $(docv) specifies how \n             the file should be tracked, by its $(b,name) or by its \n             $(b,descriptor)." in
  let follow = Arg.enum ["name", Name; "descriptor", Descriptor] in
  Arg.(value & opt (some follow) ~vopt:(Some Descriptor) None &
       info ["f"; "follow"] ~docv:"ID" ~doc)

let verb =
  let quiet =
    let doc = "Never output headers giving file names." in
    Quiet, Arg.info ["q"; "quiet"; "silent"] ~doc
  in
  let verbose =
    let doc = "Always output headers giving file names." in
    Verbose, Arg.info ["v"; "verbose"] ~doc
  in
  Arg.(last & vflag_all [Quiet] [quiet; verbose])

let pid =
  let doc = "With -f, terminate after process $(docv) dies." in
  Arg.(value & opt (some int) None & info ["pid"] ~docv:"PID" ~doc)

let files = Arg.(value & (pos_all non_dir_file []) & info [] ~docv:"FILE")

```

--------------------------------

### Documenting Command Exit Codes in Cmdliner

Source: https://erratique.ch/software/cmdliner/doc/cookbook

This example demonstrates how to document command exit codes using `Cmdliner.Cmd.Exit.info` and providing them to the command's `Cmdliner.Cmd.info` via the `exits` argument. This allows users to understand the meaning of different exit statuses returned by a command.

```ocaml
let conf_not_found = 1
let tool … = 
let tool_cmd = 
  let exits = 
    Cmd.Exit.info conf_not_found "if no configuration could be found." :: 
    Cmd.Exit.defaults 
  in 
  Cmd.make (Cmd.info "mycmd" ~exits) @@ 
  …
```

--------------------------------

### Cmdliner Positional Argument Definition

Source: https://erratique.ch/software/cmdliner/doc/cookbook

This OCaml example defines a positional argument `msg` using Cmdliner. It specifies the documentation string and an optional default value "Revolt!" if the argument is not provided on the command line.

```ocaml
let msg = 
  let doc = "$(docv) is the message to utter." and docv = "MSG" in
  Arg.(value & pos 0 string "Revolt!" & info [] ~doc ~docv)
```

--------------------------------

### Generate Help and Man Pages with Cmdliner

Source: https://erratique.ch/software/cmdliner/doc/cli

Demonstrates how to generate help and man pages for a tool or subcommand using the `--help` flag. It shows basic usage and how to redirect output to a file in groff format.

```bash
tool --help
tool cmd --help
tool --help=groff > tool.1
```

--------------------------------

### Get Command Name

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Cmd/index

The `name` function retrieves the string name associated with a given command.

```ocaml
val name : 'a t -> string
```

--------------------------------

### OCaml Function to Extract Minimum Exit Code

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Cmd/Exit/index

The 'info_code' function extracts the minimum exit code from an 'info' record. This is useful for retrieving the starting value of a defined range of exit statuses.

```ocaml
val info_code : info -> code
```

--------------------------------

### Hiding Items in Cmdliner Manpages

Source: https://erratique.ch/software/cmdliner/doc/cookbook

This example shows how to prevent an item from being automatically listed in a command's manpage by using the special `Cmdliner.Manpage.s_none` section name. This is useful for hiding internal or non-user-facing options.

```ocaml
let secret = Arg.(value & flag & info ["super-secret"] ~docs:Manpage.s_none)
```

--------------------------------

### Define a simple command with Cmdliner (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/tutorial

This snippet defines a basic command-line tool using Cmdliner. It shows how to create a term for a function and associate it with a command, then evaluates the command. The output is 'Revolt!'.

```ocaml
let revolt () = print_endline "Revolt!"

open Cmdliner

let revolt_term = Term.app (Term.const revolt) (Term.const ()) 
let cmd_revolt = Cmd.make (Cmd.info "revolt") revolt_term

let main () = Cmd.eval cmd_revolt
let () = if !Sys.interactive then () else exit (main ())
```

--------------------------------

### Create Cmdliner Command for Chorus Function

Source: https://erratique.ch/software/cmdliner/doc/tutorial

This OCaml code constructs the main command `chorus_cmd` using Cmdliner. It integrates the `count` and `msg` terms with the `chorus` function, providing metadata for the command's info and man page, and includes version information.

```ocaml
open Cmdliner

let chorus_cmd = 
  let doc = "Print a customizable message repeatedly" in 
  let man = [
    `S Manpage.s_bugs;
    `P "Email bug reports to <bugs@example.org>." ]
  in 
  Cmd.make (Cmd.info "chorus" ~version:"%%VERSION%%" ~doc ~man) @@
  let+ count and+ msg in
  chorus ~count msg
```

--------------------------------

### Cmdliner Flag Argument Definition

Source: https://erratique.ch/software/cmdliner/doc/cookbook

This OCaml example defines a command-line flag `loud` using Cmdliner. It corresponds to the `-l` and `--loud` options and evaluates to `true` if present on the command line, `false` otherwise.

```ocaml
let loud = 
  let doc = "Say the message loudly." in
  Arg.(value & flag & info ["l"; "loud"] ~doc)
```

--------------------------------

### Cmdliner Optional String Argument Definition

Source: https://erratique.ch/software/cmdliner/doc/cookbook

This OCaml example defines an optional string argument `msg` using Cmdliner. It corresponds to the `-m` and `--message` options and defaults to "Revolt!" if not specified on the command line.

```ocaml
let msg = 
  let doc = "$(docv) is the message to utter." and docv = "MSG" in
  Arg.(value & opt string "Revolt!" & info ["m"; "message"] ~doc ~docv)
```

--------------------------------

### Predefined Context-Insensitive Completions

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Arg/Completion/index

Provides predefined completion types that are context-insensitive, meaning they do not depend on the current command-line parsing state. These are useful for common completion scenarios like suggesting files, directories, or restarting the completion.

```ocaml
val complete_files : 'a t
val complete_dirs : 'a t
val complete_paths : 'a t
val complete_restart : 'a t
```

--------------------------------

### Configure Zsh Command Line Completion

Source: https://erratique.ch/software/cmdliner/doc/cli

Provides instructions for end-users to set up command-line completion for Cmdliner-based tools in zsh. It includes steps for configuring `FPATH`, initializing completion, and testing the generic completion function.

```zsh
FPATH="$(opam var share)/zsh/site-functions:${FPATH}"
autoload -Uz compinit
compinit -u
```

```zsh
> autoload _cmdliner_generic
> _cmdliner_generic
_cmdliner_generic:1: words: assignment to invalid subscript range
```

```zsh
autoload _cmdliner_generic
compdef _cmdliner_generic thetool
```

--------------------------------

### Opening Cmdliner and Syntax - OCaml

Source: https://erratique.ch/software/cmdliner/doc/cookbook

This snippet demonstrates how to open the main Cmdliner module and its Term.Syntax submodule, which is a prerequisite for using many of Cmdliner's features for defining command-line arguments and options.

```ocaml
open Cmdliner
open Cmdliner.Term.Syntax

```

--------------------------------

### Evaluate Cmdliner Command and Handle Execution

Source: https://erratique.ch/software/cmdliner/doc/tutorial

This OCaml code defines the `main` function to evaluate the `chorus_cmd` using `Cmd.eval`. It also includes a standard OCaml entry point that calls `main` and exits with the appropriate status code, preventing execution in interactive mode.

```ocaml
let main () = Cmd.eval chorus_cmd
let () = if !Sys.interactive then () else exit (main ())
```

--------------------------------

### Optional Argument Value Specification

Source: https://erratique.ch/software/cmdliner/doc/cli

Illustrates the different ways to specify a value for an optional argument, including as a separate token, glued to a short name, or glued to a long name with an equal sign. Glued forms are useful for values starting with a dash.

```shell
-o a.out, --output a.out
-oa.out
--output=a.out
--min=-10
```

--------------------------------

### OCaml: Predefined Argument Terms

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Arg/index

Provides predefined terms for common command-line options. 'man_format' defines a --man-format option for Manpage printing.

```ocaml
val man_format : Manpage.format Term.t
(* man_format is a term that defines a --man-format option and evaluates to a value that can be used with Manpage.print. *)

```

--------------------------------

### Cmdliner Command Metadata Terms (OCaml)

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Term/index

These terms provide access to command-line metadata. `main_name` retrieves the name of the main executable, `choice_names` gets the names of subcommands, and `with_used_args` returns a term's evaluated value along with the list of command-line arguments that were consumed during its evaluation.

```ocaml
val main_name : string t
val choice_names : string list t
val with_used_args : 'a t -> ('a * string list) t
```

--------------------------------

### Create a Basic Command

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Cmd/index

The `make` function (or its alias `v`) constructs a command. It takes command information and a `Term.t` value that defines the command's command-line syntax. The result is a command that can be evaluated.

```ocaml
val make : info -> 'a Term.t -> 'a t
```

```ocaml
val v : info -> 'a Term.t -> 'a t
```

--------------------------------

### Completion Functions and Types

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Arg/Completion/index

Types and functions for defining and managing completion logic.

```APIDOC
## Completion

### Type `('ctx, 'a) func`

#### Description
The type for completion functions. It takes an optional context and a token to complete, returning a list of completion directives or an error.

### Type `'a complete`

#### Description
The type for completing values. It captures a partial command line parse and a completion function.

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

### Type `'a t`

#### Description
The type for completing values parsed into type `'a`.

### Function `make`

#### Description
Creates a completion context using a given function.

#### Parameters
- `~context` ('ctx Term.t option) - Optional - A command line fragment evaluated before completion.
- `func` (('ctx, 'a) func) - The completion function to use.

### Function `complete`

#### Description
Completes with the given completion context.

#### Parameters
- `c` ('a t) - The completion context.

### Value `complete_files`

#### Description
A context-insensitive function that always returns `Ok [``files``]`.

### Value `complete_dirs`

#### Description
A context-insensitive function that always returns `Ok [``dirs``]`.

### Value `complete_paths`

#### Description
A context-insensitive function that always returns `Ok [``files``;``dirs``]`.

### Value `complete_restart`

#### Description
A context-insensitive function that always returns `Ok [``restart``]`.

```

--------------------------------

### OCaml Source Code Structure for Cmdliner Tools

Source: https://erratique.ch/software/cmdliner/doc/cookbook

This snippet illustrates the recommended source code organization for Cmdliner applications, separating the core tool implementation from the command-line interface logic. It promotes a single exit point and facilitates REPL usage. Dependencies include `Cmdliner` and `Stdlib`.

```ocaml
(* Implementation of your command. Except for exit codes does not deal with
   command line interface related matters and is independent from
   Cmdliner. *)

let exit_ok = 0
let tool … = …; exit_ok

(* Command line interface. Adds metadata to your [tool] function arguments
   so that they can be parsed from the command line and documented. *)

open Cmdliner
open Cmdliner.Term.Syntax

let cmd = … (* Has a term that invokes [tool] *)
let main () = Cmd.eval' cmd
let () = if !Sys.interactive then () else exit (main ())
```

--------------------------------

### Define Command Information

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Cmd/index

The `info` function creates information for a command. It allows specifying documentation, version, deprecation status, exit codes, environment variables, and man page details. The `name` argument is mandatory.

```ocaml
val info :    ?deprecated:string -> ?man_xrefs:Manpage.xref list -> ?man:Manpage.block list -> ?envs:Env.info list -> ?exits:Exit.info list -> ?sdocs:Manpage.section_name -> ?docs:Manpage.section_name -> ?doc:string -> ?version:string -> string -> info
```

--------------------------------

### Showing Help in Cmdliner Command Group Default

Source: https://erratique.ch/software/cmdliner/doc/cookbook

This snippet illustrates how to configure a default command within a group to display generated help information using `Cmdliner.Term.ret`. This is useful for command groups where a default action might be to show the help message.

```ocaml
let group_cmd = 
  let default = Term.(ret (const (`Help (`Auto, None)))) (* show help *) in 
  Cmd.group (Cmd.info "group") ~default @@ 
  [first_cmd; second_cmd]
```

--------------------------------

### Manpage Output Format Specification in OCaml

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Manpage/index

Defines the `format` type, specifying how a man page should be rendered. Options include automatic selection between pager and plain text based on the `TERM` environment variable, using a pager, formatting to plain text, or formatting to `groff` commands for further processing.

```ocaml
type format = [
  | `Auto
(*
Format like ``Pager` or ``Plain` whenever the `TERM` environment variable is `dumb` or unset.
*)
  | `Pager
(*
Tries to use a pager or falls back to ``Plain`.
*)
  | `Plain
(*
Format to plain text.
*)
  | `Groff
(*
Format to groff commands.
*)

]
```

--------------------------------

### Positional Argument Delimitation

Source: https://erratique.ch/software/cmdliner/doc/cli

Demonstrates the use of the '--' token to ensure that all subsequent arguments are treated as positional, even if they resemble option names.

```shell
tool --option -- but --now we -are --all positional --argu=ments
```

--------------------------------

### Define Completion Functions and Types

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Arg/Completion/index

Defines the core types and functions for creating and managing argument completion logic. This includes the 'func' type for custom completion logic, and 'complete' type and 'make' function for associating completion logic with command-line terms.

```ocaml
type ('ctx, 'a) func =   'ctx option -> token:string -> ('a directive list, string) Stdlib.result
type 'a complete =  | Complete : 'ctx Term.t option * ('ctx, 'a) func -> 'a complete

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

--------------------------------

### Define OCaml Function for Repetitive Printing

Source: https://erratique.ch/software/cmdliner/doc/tutorial

This OCaml function, `chorus`, takes a count and a message, and prints the message repeatedly. It serves as the core logic for the command-line tool.

```ocaml
let chorus ~count msg = for i = 1 to count do print_endline msg done
```

--------------------------------

### Tool Invocation: With Subcommands

Source: https://erratique.ch/software/cmdliner/doc/cli

This is the invocation form for tools that evaluate commands with subcommands. Command strings must precede optional arguments. Subcommands also automatically respond to the '--help' option.

```shell
tool [COMMAND]… [OPTION]… [ARG]…
```

--------------------------------

### Simple Cmdliner Tool with Flag and Input File in OCaml

Source: https://erratique.ch/software/cmdliner/doc/cookbook

An OCaml tool using Cmdliner that includes a boolean flag and an optional positional argument for an input file. It also handles the `--version` option and defines custom exit codes. Dependencies include the 'cmdliner' package.

```ocaml
let exit_todo = 1
let tool ~flag ~infile = exit_todo

open Cmdliner
open Cmdliner.Term.Syntax

let flag = Arg.(value & flag & info ["flag"] ~doc:"The flag")
let infile = 
  let doc = "$(docv) is the input file. Use $(b,-) for $(b,stdin)." in
  Arg.(value & pos 0 filepath "-" & info [] ~doc ~docv:"FILE")

let cmd = 
  let doc = "The tool synopsis is TODO" in
  let man = [
    `S Manpage.s_description;
    `P "$(cmd) does TODO" ]
  in 
  let exits = 
    Cmd.Exit.info exit_todo ~doc:"When there is stuff todo" ::
    Cmd.Exit.defaults
  in 
  Cmd.make (Cmd.info "TODO" ~version:"%%VERSION%%" ~doc ~man ~exits) @@
  let+ flag and+ infile in 
  tool ~flag ~infile

let main () = Cmd.eval' cmd
let () = if !Sys.interactive then () else exit (main ())
```

--------------------------------

### Define Completion Directives

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Arg/Completion/index

Defines types and values for completion directives, which specify how argument values should be completed. These include replacing tokens with specific values, suggesting files or directories, restarting the completion process, or displaying messages.

```ocaml
type 'a directive

val value : ?doc:string -> 'a -> 'a directive
val string : ?doc:string -> string -> 'a directive
val files : 'a directive
val dirs : 'a directive
val restart : 'a directive
val message : string -> 'a directive
val raw : string -> 'a directive
```

--------------------------------

### Completion Directives

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Arg/Completion/index

Defines various directives that specify how argument values should be completed by the shell.

```APIDOC
## Completion Directives

### Description
Defines directives for completing argument values.

### Value `value`

#### Description
Specifies a value that can replace the token to complete.

#### Parameters
- `~doc` (string) - Optional - ANSI styled UTF-8 text documenting the value.
- `v` ('a) - The value to complete, serialized by the argument's formatter.

### Value `string`

#### Description
Specifies a string that can replace the token to complete.

#### Parameters
- `~doc` (string) - Optional - ANSI styled UTF-8 text documenting the value.
- `s` (string) - The string to complete.

### Value `files`

#### Description
Indicates that the token to complete can be replaced with files.

### Value `dirs`

#### Description
Indicates that the token to complete can be replaced with directories.

### Value `restart`

#### Description
Indicates that the shell should restart completion after the `--` token. This is useful for tools that invoke other tools.

### Value `message`

#### Description
Specifies a multi-line, ANSI styled, UTF-8 message to be reported to end-users.

#### Parameters
- `s` (string) - The message content.

### Value `raw`

#### Description
Takes over the entire protocol output with a custom string. Use with caution as the protocol is unstable.

#### Parameters
- `s` (string) - The raw protocol output.

```

--------------------------------

### OCaml: Define argument information for command-line arguments

Source: https://erratique.ch/software/cmdliner/doc/Cmdliner/Arg/index

The `info` function constructs metadata for command-line arguments, including documentation, variable names, environment variable mappings, and deprecation warnings. It supports various optional parameters to customize argument presentation in help messages.

```ocaml
val info :    ?deprecated:string -> ?absent:string -> ?docs:Manpage.section_name -> ?doc_envs:Cmd.Env.info list -> ?docv:string -> ?doc:string -> ?env:Cmd.Env.info -> string list -> info
let info ?deprecated ?absent ?docs ?doc_envs ?docv ?doc ?env names = ...
(* Example usage: *
let count_arg = Arg.info ~doc:"Number of times to repeat." ~docv:"N" ["-c"; "--count"] 
*) 
```
Tokens:
Raw