package ez_cmdliner

  1. Overview
  2. Docs
Easy interface to Cmdliner à la Arg.parse with sub-commands

Install 

dune-project
 Dependency

ocamlpro.github.io Readme Changelog LGPL-2.1-only WITH OCaml-LGPL-linking-exception License Edit opam file Versions (5)

Authors

  1. F
    Fabrice Le Fessant <fabrice.le_fessant@ocamlpro.com>

Maintainers

  1. F
    Fabrice Le Fessant <fabrice.le_fessant@ocamlpro.com>

Sources

v0.4.3.tar.gz
sha256=a4aaa008bf2bf29189e3c66c9481aab5d2e12b20c0b769a484df5dc07d68961d

doc/ez_cmdliner/Ezcmd/V2/EZCMD/index.html

Module V2.EZCMDSource

Sourcemodule TYPES : sig ... end

Specification of Arguments

Sourcetype spec = TYPES.Arg.spec =
  1. | Unit of unit -> unit
  2. | Bool of bool -> unit
  3. | Set_bool of bool ref
  4. | Set of bool ref
  5. | Clear of bool ref
  6. | String of string -> unit
  7. | Set_string of string ref
  8. | Int of int -> unit
  9. | Set_int of int ref
  10. | Float of float -> unit
  11. | Set_float of float ref
  12. | Symbol of string list * string -> unit
  13. | File of string -> unit
  14. | Anon of int * string -> unit
  15. | Anons of string list -> unit

Type spec specifies kinds and actions for every argument. It is close to the Arg.spec type in the standard library. One main difference with Arg.spec is that these arguments should only appear once on the command-line, otherwise cmdliner is going to complain.

Anonymous arguments are treated a bit differently. Anon(n,f) means the anonymous argument at position n (starting from position 0). Anons f means all the anonymous arguments, provided as a list of strings to f.

Sourceval env : ?docs:string -> ?doc:string -> string -> TYPES.env

EZCMD.env ~docs ~doc var describes an environment variable var. doc is the man page information of the environment variable, defaults to "undocumented". docs is the title of the man page section in which the environment variable will be listed, it defaults to Manpage.s_environment.

In doc the documentation markup language can be used with following variables:

  • $(env), the value of var.
  • The variables mentioned in info
Sourceval info : ?docs:string -> ?docv:string -> ?env:TYPES.env -> ?version:string -> string -> TYPES.info

EZCMD.info docs docv env doc defines information for an argument.

  • env defines the name of an environment variable which is looked up for defining the argument if it is absent from the command line. See environment variables for details.

  • doc is the man page information of the argument. The documentation language can be used and the following variables are recognized:

    • "$(docv)" the value of docv (see below).
    • "$(opt)", one of the options of names, preference is given to a long one.
    • "$(env)", the environment var specified by env (if any).

    These functions can help with formatting argument values.

  • docv is for positional and non-flag optional arguments. It is a variable name used in the man page to stand for their value.
  • docs is the title of the man page section in which the argument will be listed. For optional arguments this defaults to Manpage.s_options. For positional arguments this defaults to Manpage.s_arguments. However a positional argument is only listed if it has both a doc and docv specified.
Sourceval sub : string -> doc:string -> ?args:TYPES.arg_list -> ?man:TYPES.block list -> ?version:string -> (unit -> unit) -> TYPES.sub

EZCMD.sub name action associates the action action with the subcommand name. This module supports only one level of sub-commands, unless you are using the MAKE functor. With the MAKE functor, subcommand names can contain spaces.

main functions

Sourceval main : ?version:string -> ?argv:string array -> TYPES.sub -> unit

EZCMD.main sub can be used when there is only one command in the executable. Arguments are defined in the sub-command definition.

Sourceval main_with_subcommands : name:string -> ?version:string -> ?default:TYPES.sub -> doc:string -> ?man:TYPES.block list -> ?topics:(string * Cmdliner.Manpage.block list) list -> ?common_args:TYPES.arg_list -> ?argv:string array -> TYPES.sub list -> unit

EZCMD.main_with_subcommands ~name ~doc subcommands parses the arguments and calls the action of the selected sub-command.

Multi-level subcommands

The functor MAKE can be used to define a main function, supporting multi-level sub-commands.

It takes a list of subcommands, defined for example with:

open Ezcmd.V2

module MAIN = EZCMD.MAKE(struct
   ...
end)

let cmd1 = (* define one sub-command *)
  let files = ref [] in
  EZCMD.sub
    "parse this file" (* with spaces !! *)
    (fun () ->
     ... (* action to perform after parsing options of the sub-command *)
    )
    ~args:
      [
        [ "a"; "after" ],
        EZCMD.String (fun s -> ... ),
        EZCMD.info ~docv:"STRING" "I use this string";

        [],
        EZCMD.Anons (fun args -> ... ),
        EZCMD.info ~docv:"FILE" "I use these arguments" ;
      ]
    ~doc: "..."
    ~man:[
      `S "DESCRIPTION";
      `Blocks [
        `P "..."
      ];
    ]
let cmd2 = ...
let cmd3 = ...

let () = MAIN.main [ cmd1 ; cmd2 ; cmd3 ]

Default options provided by this functor:

  • -v | --verbose : increase verbosity and backtraces
  • -q | --quiet : set verbosity to 0
  • --version : print M.version
  • --about : print M.about
  • --echo : print command with current arguments
  • rst : output a .rst file with all subcommands
Sourcemodule MAKE (M : sig ... end) : sig ... end
Sourcemodule MANPAGE = Cmdliner.Manpage

Compatibility with Stdlib Arg

Sourceval parse : ?name:string -> ?version:string -> ?man:TYPES.block list -> (string * TYPES.Arg.spec * string) list -> (string -> unit) -> string -> unit

EZCMD.parse is mostly equivalent to Stdlib Arg.parse

Sourceval translate : ?docs:string -> (string * TYPES.Arg.spec * string) list -> (string list * TYPES.Arg.spec * TYPES.info) list

EZCMD.translate args can be used to provide a list of arguments, à la Arg.parse, to other EZCMD commands.

Sourceval translate_anon : (string -> unit) -> (string list * TYPES.Arg.spec * TYPES.info) list

EZCMD.translate_anon f returns a specification that will call f on every anonymous argument.

Sourceval to_rst : ?name:string -> TYPES.sub list -> TYPES.arg_list -> string

Deprecated

Sourcemodule RAWTYPES = TYPES
Sourceval raw_env : TYPES.env -> RAWTYPES.env
Sourceval raw_sub : TYPES.sub -> RAWTYPES.sub