[@@deriving subliner] and [%%subliner]

[@@deriving] plugin to generate Cmdliner sub-commands groups, and rewriter to generate Cmdliner evaluations.

Usage

To use [@@deriving subliner] or [%%subliner], add (preprocess (pps ppx_subliner)) to the library or executable configuration in dune file.

Syntax

Group of Sub-commands

A group of sub-commands can be generated by tagging [@@deriving subliner] to a variant type and providing a handling function for that variant.

For variant type params, function params_cmdliner_group_cmds with type (params -> 'a) -> 'a Cmdliner.Cmd.t list will be generated. Each constructor of the variant can only have one or no parameter. If a constructor has a parameter with type p, function p_cmdliner_term with type unit -> p Cmdliner.Term.t is required. The function can be either obtained by tagging a supported record with [@@deriving cmdliner] or constructed manually. Each constructor can be tagged with Cmd.info Attributes to modify the behavior the corresponding sub-command.

type foo = { my_arg : string }
val foo_cmdliner_term : unit -> foo Cmdliner.Term,t

type params =
  | Foo of foo
  | Bar
[@@deriving_inline subliner]
include
  sig
    [@@@ocaml.warning "-32"]
    val params_cmdliner_group_cmds : (params -> 'a) -> 'a Cmdliner.Cmd.t list
  end[@@ocaml.doc "@inline"]
[@@@end]

The derived function can be used with [%%subliner.cmds] extension to generate Cmdliner evaluation. The extension can be tagged with Cmd.info Attributes and Default Term.t Attribute to modify the behavior the command line tool.

let handle_params = function
  | Foo f -> handle_foo f
  | Bar -> handle_bar ()

[%%subliner.cmds eval.params <- handle_params]

Different evaluation function can be used and optional parameters can be applied.

[%%subliner.cmds (eval_result ~catch:false).params <- handle_params_result]

Cmd.info Attributes

Attributes may be prefixed with subliner. to avoid conflicts with other extensions.

[@name]

Set the name of the command. If not provided, the lower case of the constructor name will be used (i.e. constructor Foo will have name "foo" by default) for sub-commands, and the executable name will be used for command line tools.

type params = Foo [@name "my-cmd-name"]

[@doc]

Set the one line description of the command. If not provided, the doc string will be used.

type params = Foo (** This is a short description of My_cmd. *)

Other

[@version], [@deprecated], [@docs], [@sdocs], [@exits], [@envs], [@envs], [@man] and [@man_xrefs] are also supported. For their exact usage, please refer to the documentation of Cmdliner.Cmd.info.

Default Term.t Attribute

For sub-command groups, [@@default] can be used to change the command line syntax to parse if no sub command is specified. By default, it will show the default help page.

let default = Cmdliner.Term.(ret (const (`Error (true, "Some error messages"))))

[%%subliner.cmds eval.params <- handle]
[@@default default]