hammerlab/ppx_deriving_cmdliner

Name: ppx_deriving_cmdliner

Owner: Hammer Lab

Description: Ppx_deriving plugin for generating command line interfaces from types (Cmdliner.Term.t)

Created: 2017-03-10 02:50:53.0

Updated: 2017-11-03 07:19:29.0

Pushed: 2017-06-28 01:09:11.0

Homepage:

Size: 34

Language: OCaml

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

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

 params = {
ername: string;
* Your Github username *)

i_key: string;
* Your Github API key *)

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

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

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

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

Which gives you a CLI like the following:

   awesome-cli

PSIS
   awesome-cli [OPTION]... CMD

MENTS
   CMD (required)
        The Github API command to run

ONS
   --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)

le M = struct
pe t = int * int
t fst (f,_) = f
t snd (_,s) = s
t 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))
t to_string t =
Printf.sprintf "%d|%d" (fst t) (snd t)
t cmdliner_converter =
of_string,
(fun fmt t -> Format.fprintf fmt "%s" (to_string t))

 custom_types = {
o: M.t; [@conv M.cmdliner_converter]
r: 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.