package ppx_deriving_cmdliner

  1. Overview
  2. Docs

Description

ppx_deriving_cmdliner is a ppx_deriving plugin that generates a Cmdliner Term.t for a record type.

Tags

syntax cli

Published: 04 Oct 2018

README

[@@deriving cmdliner]

deriving Cmdliner is the easiest way to get a command line interface.

It is also a ppx_deriving plugin that generates a Cmdliner Term for a given type.

Example

type params = {
  username: string;
  (** Your Github username *)

  api_key: string;
  (** Your Github API key *)

  command: string; [@pos 0] [@docv "CMD"]
  (** The Github API command to run *)

  dry_run: bool;
  (** Don't really run this command *)

  time_to_wait: float; [@default 0.]
  (** Just an example of another type *)
} [@@deriving cmdliner,show]

let _ =
  let term = Cmdliner.Term.(const show_params $ params_cmdliner_term ()) in
  let info = Cmdliner.Term.info Sys.argv.(0) in
  Cmdliner.Term.eval (term, info)

Which gives you a CLI like the following:

NAME
       awesome-cli

SYNOPSIS
       awesome-cli [OPTION]... CMD

ARGUMENTS
       CMD (required)
            The Github API command to run

OPTIONS
       --api-key=STRING (required)
            Your Github API key

       --dry-run
            Don't really run this command

       --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.

       --time-to-wait=FLOAT (absent=0.)
            Just an example of another type

       --username=STRING (required)
            Your Github username

Features

Custom type support

Ppx_deriving_cmdliner supports arbitrary types via a cmdliner_converter interface. For example, the below two methods work for supporting M.t (from test/tests.ml)

module M = struct
  type t = int * int
  let fst (f,_) = f
  let snd (_,s) = s
  let of_string s =
    try
      let sepi = String.index s '|' in
      let fst = String.sub s 0 sepi in
      let snd = String.sub s (sepi+1) ((String.length s)-sepi-1) in
      Result.Ok (int_of_string fst, int_of_string snd)
    with _ -> Result.Error (`Msg (Printf.sprintf "Couldn't parse `%s`" s))
  let to_string t =
    Printf.sprintf "%d|%d" (fst t) (snd t)
  let cmdliner_converter =
    of_string,
    (fun fmt t -> Format.fprintf fmt "%s" (to_string t))
end
type custom_types = {
  foo: M.t; [@conv M.cmdliner_converter]
  bar: M.t;
} [@@deriving cmdliner]

In short, a value of type string -> ('a, [ `Msg of string ]) Result.result) * 'a printer must be provided (or will be looked for under the name cmdliner_converter if the type is t, else type_name_cmdliner_converter) for the given type.

Attributes supported

  1. Docs: [@doc "Overwrites the docstring"], [@docs "SECTION TWO"], [@docv "VAL"]

  2. Environment variables: [@env "ENVNAME"], [@env.doc "Docs for the variable"], [@env.docs "SECTION ENVS"]

  3. Other: [@list_sep '@'], [@default 123], [@enum [("a", Foo); ("b", Bar)]], [@aka ["b";"another-flag-name"]], [@conv cmdliner_converter] (cf. required argument to conv in Cmdliner), [@opt_all] only on a' list fields, [@term cmdliner_term] for assiging an arbitrary Cmdliner.Term.t to a field.

Dependencies (8)

  1. cppo build
  2. ppxfind build
  3. ocamlfind build
  4. dune < "2.0"
  5. ppx_deriving >= "4.0" & < "5.0"
  6. result
  7. cmdliner >= "1.0.0"
  8. ocaml >= "4.03" & < "4.10"

Dev Dependencies (2)

  1. ppx_import with-test & >= "1.1" & < "2.0"
  2. alcotest with-test

Used by (1)

  1. ppx_subliner

Conflicts

None

OCaml

Innovation. Community. Security.