Climate

A declarative command-line parser for OCaml.

The API is documented here.

About

A library for parsing command-line arguments in a declarative style, where specifying the parser spec and assigning parsed arguments to variables in your program is done with the same code. Climate supports CLIs with nested subcommands, and can automatically generate help messages, manpages, and shell completion scripts.

Here's a tiny example:

letopenArg_parserinlet+ flag_foo = flag [ "foo" ] ~doc:"some flag"and+ value_bar = named_opt [ "bar" ] string~doc:"some string value"in(* ...do something with the parsed values... *)

Full Example

Here's a complete example program with built-in support for generating its own completion script.

openClimatemoduleColor=structtypet =
| Red
| Green
| Blue(* Tell climate how to handle colours *)let conv =letopenArg_parserin
enum ~default_value_name:"COLOR" [ "red", Red; "green", Green; "blue", Blue ]
;;
end(* Ansi escape sequence to reset the termminal style *)let ansi_reset ="\x1b[0m"(* Returns the escape sequence to set the terminal style *)letansi_style~bold~underline~color=let effects =List.append (if bold then [ ";1" ] else[]) (if underline then [ ";4" ] else[])
inlet color_code =match (color : Color.t option) with|None -> 0|SomeRed -> 31|SomeGreen -> 32|SomeBlue -> 34inPrintf.sprintf "\x1b[%d%sm" color_code (String.concat "" effects)
;;
(* Print the words in the given style *)letmain~bold~underline~colorwords=
print_string (ansi_style ~bold~underline~color);
print_string (String.concat "" words);
print_string ansi_reset;
print_newline ()
;;
let()=let command =Command.singleton ~doc:"Echo with style!"@@letopenArg_parserin(* Describe and parse the command line arguments: *)let+ bold = flag [ "bold" ] ~doc:"Make the text bold"and+ underline = flag [ "underline" ] ~doc:"Underline the text"and+ color = named_opt [ "color" ] Color.conv ~doc:"Set the text color"and+ words = pos_all stringand+ completion =
flag [ "completion" ] ~doc:"Print this program's completion script and exit"inif completion
then`Completionelse`Main (fun() -> main ~bold~underline~color words)
in(* Run the parser yielding either a main function to call or an indication that we should print the completion script. *)let help_style =letopenHelp_stylein
{ program_doc = { ansi_style_plain with color =Some`Green }
; usage = { ansi_style_plain with color =Some`Yellow }
; section_heading = { ansi_style_plain with color =Some`Red }
; arg_name = { ansi_style_plain with color =Some`Blue }
; arg_doc = { ansi_style_plain with color =Some`Cyan }
; error = { ansi_style_plain with color =Some`Red }
}
inmatchCommand.run ~program_name:(Literal"echo-ansi") ~version:"0.0.1"~help_style command
with|`Completion -> print_endline (Command.completion_script_bash command)
|`Mainmain -> main ()
;;

This program lives in examples/echo_ansi.ml. Run it with dune exec examples/echo_ansi.exe -- <ARGS>. E.g.

$ dune exec examples/echo_ansi.exe -- --help
Echo with style!
Usage: echo-ansi [OPTION]… [STRING]…
Arguments:
[STRING]...
Options:
--bold Make the text bold
--underline Underline the text
--color <COLOR> Set the text color
--completion Print this program's completion script and exit
-h, --help Show this help message.

Shell Completion

The easiest way to setup the completion script is to first put the executable in a directory in your PATH. E.g.

$ mkdir -p ~/bin
$ export PATH=$HOME/bin:$PATH
$ dune build
$ cp _build/default/examples/echo_ansi.exe ~/bin/echo_ansi

You can ask echo_ansi to print out its own completion script with:

$ echo_ansi --completion
#!/usr/bin/env bash
# Completion script for echo_ansi. Generated by climate.
__climate_complete_1184462387__complete() {
__climate_complete_1184462387__comp_words_traverse_init
if [ "$COMP_CWORD" == "0" ]; then
...

Put the completion script in a file and then source that file in your shell to enable completions for echo_ansi:

$ echo_ansi --completion > /tmp/echo_ansi_completions.sh
$ source /tmp/echo_ansi_completions.sh
$ echo_ansi --color <TAB>
blue green red

Currently only bash is supported, though it also works in zsh if bash compatibility is enabled:

# put this in your ~/.zshrc
autoload -Uz compinit bashcompinit
compinit
bashcompinit

Manpages

To generate a manpage for a command, run the command with the hidden flag --manpage. This command will print the manpage in the troff format to stdout. To render the manpage during development, pipe the output to man -l -. E.g. dune exec myprog.exe -- --manpage | man -l -.