Module Cmdliner.Term

Contents

Instructions: Use this module in your project

In the IDE (CLion, Visual Studio Code, Xcode, etc.) you use for your DkSDK project:

  1. Add the following to your project's dependencies/CMakeLists.txt:

    Copy
    DkSDKProject_DeclareAvailable(cmdliner
    CONSTRAINT "= 1.1.1+dune"
    FINDLIBS cmdliner)
DkSDKProject_MakeAvailable(cmdliner)

  2. Add the Findlib::cmdliner library to any desired targets in src/*/CMakeLists.txt:

    Copy
    target_link_libraries(YourPackage_YourLibraryName
     # ... existing libraries, if any ...
     Findlib::cmdliner)

  3. Click your IDE's Build button

Not using DkSDK?

FIRST, do one or all of the following:

  1. Run:

    Copy
    opam install cmdliner.1.1.1+dune

  2. Edit your dune-project and add:

    Copy
    (package
  (name YourExistingPackage)
  (depends
  ; ... existing dependenices ...
  (cmdliner (>= 1.1.1+dune))))

    Then run:

    Copy
    dune build *.opam # if this fails, run: dune build

  3. Edit your <package>.opam file and add:

    Copy
    depends: [
  # ... existing dependencies ...
  "cmdliner" {>= "1.1.1+dune"}
]

    Then run:

    Copy
    opam install . --deps-only

FINALLY, add the cmdliner library to any desired (library)and/or (executable) targets in your **/dune files:

Copy
(library
  (name YourLibrary)
  ; ... existing library options ...
  (libraries
    ; ... existing libraries ...
    cmdliner))

(executable
  (name YourExecutable)
  ; ... existing executable options ...
  (libraries
    ; ... existing libraries ...
    cmdliner))

Terms

type ``+'a t

The type for terms evaluating to values of type 'a.

valconst :'a -> 'a t

const v is a term that evaluates to v.

val ($) : ``('a -> 'b)`` t -> 'a t -> 'b t

f $ v is a term that evaluates to the result of applying the evaluation of v to the one of f.

val app : ``('a -> 'b)`` t -> 'a t -> 'b t

app is ($).

\Interacting with Cmdliner's evaluation

valterm_result : ``?usage:bool-> ``('a, ``[ ``` Msg of string ``` ]) [result](../../ocaml/Stdlib/#type-result) [t](#type-t) `-> 'a [t\](#type-t)

term_result ~usage t evaluates to

  • `Ok v if t evaluates to Ok v
  • `Error `Term with the error message e and usage shown according to usage (defaults to false), if t evaluates to Error (`Msg e).

See also term_result'.

valterm_result' : ``?usage:bool-> ``('a, string)`` result t -> 'a t

term_result' is like term_result but with a string error case.

val cli_parse_result : ``('a, ``[ ``` Msg of string ``` ]) [result](../../ocaml/Stdlib/#type-result) [t](#type-t) `-> 'a [t\](#type-t)

cli_parse_result t is a term that evaluates to:

  • `Ok v if t evaluates to Ok v.
  • `Error `Parse with the error message e if t evaluates to Error (`Msg e).

See also cli_parse_result'.

val cli_parse_result' : ``('a, string)`` result t -> 'a t

cli_parse_result' is like cli_parse_result but with a string error case.

valmain_name : ``stringt

main_name is a term that evaluates to the main command name; that is the name of the tool.

valchoice_names : ``string list``t

choice_names is a term that evaluates to the names of the commands that are children of the main command.

valwith_used_args :'a t -> ``('a* ``string list``)``t

with_used_args t is a term that evaluates to t tupled with the arguments from the command line that where used to evaluate t.

type``'a ret`` = ``[

    

  1. 

| ``` Help  `of`` `[`Manpage.format`](../Cmdliner-Manpage/#type-format)` * string option`
    

  1. 

| ``` Error  ``of bool * string
    

  1. 

| ``` Ok  ``of 'a ]

The type for command return values. See ret.

valret :'a ret t -> 'a t

ret v is a term whose evaluation depends on the case to which v evaluates. With :

  • `Ok v, it evaluates to v.
  • `Error (usage, e), the evaluation fails and Cmdliner prints the error e and the term's usage if usage is true.
  • `Help (format, name), the evaluation fails and Cmdliner prints a manpage in format format. If name is None this is the the main command's manpage. If name is Some c this is the man page of the sub command c of the main command.

Note. While not deprecated you are encouraged not use this API.

Deprecated Term evaluation interface

This interface is deprecated in favor of Cmdliner.Cmd. Follow the compiler deprecation warning hints to transition.

Term information

Term information defines the name and man page of a term. For simple evaluation this is the name of the program and its man page. For multiple term evaluation, this is the name of a command and its man page.

type exit_info

The type for exit status information.

  • deprecated Use Cmd.Exit.info instead.
valexit_info : ``?docs:string->``?doc:string->``?max:int->``int-> exit_info

exit_info ~docs ~doc min ~max describe the range of exit statuses from min to max (defaults to min). doc is the man page information for the statuses, defaults to "undocumented". docs is the title of the man page section in which the statuses will be listed, it defaults to Manpage.s_exit_status.

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

  • $(status), the value of min.

  • $(status_max), the value of max.

  • The variables mentioned in info

  • deprecated Use Cmd.Exit.info instead.

valdefault_exits :exit_info list

default_exits is information for exit status exit_status_success added to default_error_exits.

  • deprecated Use Cmd.Exit.defaults or Cmd.info's defaults ~exits value instead.
valdefault_error_exits :exit_info list

default_error_exits is information for exit statuses exit_status_cli_error and exit_status_internal_error.

  • deprecated List.filter the Cmd.Exit.defaults value instead.
type env_info

The type for environment variable information.

  • deprecated Use Cmd.Env.info instead.
valenv_info : ``?docs:string->``?doc:string->``string-> env_info

env_info ~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 Cmdliner.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

  • deprecated Use Cmd.Env.info instead.

type info

The type for term information.

  • deprecated Use Cmd.info instead.
val info : ``?man_xrefs:Manpage.xreflist``-> ``?man:Manpage.blocklist``-> ``?envs:env_infolist``-> ``?exits:exit_infolist``->``?sdocs:string->``?docs:string->``?doc:string->``?version:string->``string-> info

info sdocs man docs doc version name is a term information such that:

  • name is the name of the program or the command.
  • version is the version string of the program, ignored for commands.
  • doc is a one line description of the program or command used for the NAME section of the term's man page. For commands this description is also used in the list of commands of the main term's man page.
  • docs, only for commands, the title of the section of the main term's man page where it should be listed (defaults to Manpage.s_commands).
  • sdocs defines the title of the section in which the standard --help and --version arguments are listed (defaults to Manpage.s_options).
  • exits is a list of exit statuses that the term evaluation may produce.
  • envs is a list of environment variables that influence the term's evaluation.
  • man is the text of the man page for the term.
  • man_xrefs are cross-references to other manual pages. These are used to generate a Manpage.s_see_also section.

doc, man, envs support the documentation markup language in which the following variables are recognized:

  • $(tname) the term's name.

  • $(mname) the main term's name.

  • deprecated Use Cmd.info instead.

valname :info -> string

name ti is the name of the term information.

  • deprecated Use Cmd.info_name instead.

Evaluation

type``'a result`` = ``[

    

  1. 

| ``` Ok  ``of 'a
    

  1. 

| ``` Error  ``of``` [Parse  ```` | Term ``` ``` | Exn ``` ]`
    

  1. 

| ``` Version ``
    

  1. 

| ``` Help `` ]

The type for evaluation results.

  • `Ok v, the term evaluated successfully and v is the result.
  • `Version, the version string of the main term was printed on the help formatter.
  • `Help, man page about the term was printed on the help formatter.
  • `Error `Parse, a command line parse error occurred and was reported on the error formatter.
  • `Error `Term, a term evaluation error occurred and was reported on the error formatter (see Term.ret').
  • `Error `Exn, an exception e was caught and reported on the error formatter (see the ~catch parameter of eval).
val eval : ``?help:Stdlib.Format.formatter -> ``?err:Stdlib.Format.formatter ->``?catch:bool->``?env:``(``string->``string option``)``->``?argv:``string array``-> ``('a t*info)`` -> 'a result

eval help err catch argv (t,i) is the evaluation result of t with command line arguments argv (defaults to Sys.argv).

If catch is true (default) uncaught exceptions are intercepted and their stack trace is written to the err formatter.

help is the formatter used to print help or version messages (defaults to Format.std_formatter). err is the formatter used to print error messages (defaults to Format.err_formatter).

env is used for environment variable lookup, the default uses Sys.getenv.

  • deprecated Use Cmd.v and one of Cmd.eval* instead.
val eval_choice : ``?help:Stdlib.Format.formatter -> ``?err:Stdlib.Format.formatter ->``?catch:bool->``?env:``(``string->``string option``)``->``?argv:``string array``-> ``('a t*info)`` -> ``('a t*info)`` list`` -> 'a result

eval_choice help err catch argv (t,i) choices is like eval except that if the first argument on the command line is not an option name it will look in choices for a term whose information has this name and evaluate it.

If the command name is unknown an error is reported. If the name is unspecified the "main" term t is evaluated. i defines the name and man page of the program.

  • deprecated Use Cmd.group and one of Cmd.eval* instead.
valeval_peek_opts : ``?version_opt:bool->``?env:``(``string->``string option``)``->``?argv:``string array``-> 'a t -> 'aoption`` *'a result

eval_peek_opts version_opt argv t evaluates t, a term made of optional arguments only, with the command line argv (defaults to Sys.argv). In this evaluation, unknown optional arguments and positional arguments are ignored.

The evaluation returns a pair. The first component is the result of parsing the command line argv stripped from any help and version option if version_opt is true (defaults to false). It results in:

  • Some _ if the command line would be parsed correctly given the partial knowledge in t.
  • None if a parse error would occur on the options of t

The second component is the result of parsing the command line argv without stripping the help and version options. It indicates what the evaluation would result in on argv given the partial knowledge in t (for example it would return `Help if there's a help option in argv). However in contrasts to eval and eval_choice no side effects like error reporting or help output occurs.

Note. Positional arguments can't be peeked without the full specification of the command line: we can't tell apart a positional argument from the value of an unknown optional argument.

  • deprecated Use Cmd.eval_peek_opts instead.

Turning evaluation results into exit codes

Note. If you are using the following functions to handle the evaluation result of a term you should add default_exits to the term's information ~exits argument.

WARNING. You should avoid status codes strictly greater than 125 as those may be used by some shells.

val exit_status_success : int

exit_status_success is 0, the exit status for success.

  • deprecated Use Cmd.Exit.ok instead.
val exit_status_cli_error : int

exit_status_cli_error is 124, an exit status for command line parsing errors.

  • deprecated Use Cmd.Exit.cli_error instead.
val exit_status_internal_error : int

exit_status_internal_error is 125, an exit status for unexpected internal errors.

  • deprecated Use Cmd.Exit.internal_error instead.
valexit_status_of_result : ``?term_err:int->``unitresult -> int

exit_status_of_result ~term_err r is an exit(3) status code determined from r as follows:

valexit_status_of_status_result : ``?term_err:int->``intresult -> int

exit_status_of_status_result is like exit_status_of_result except for `Ok n where n is used as the status exit code.

  • deprecated Use Cmd.eval' instead.
valexit : ``?term_err:int->``unitresult -> unit

exit ~term_err r is Stdlib.exit @@ exit_status_of_result ~term_err r

  • deprecated Use Stdlib.exit and Cmd.eval instead.
valexit_status : ``?term_err:int->``intresult -> unit

exit_status ~term_err r is Stdlib.exit @@ exit_status_of_status_result ~term_err r

  • deprecated Use Stdlib.exit and Cmd.eval' instead.

More from the DkSDK Book

    1. DkSDK
      1. Package capnp
        1. Module Capnp
            1. Module type MessageSig.MESSAGE
            1. Module type MessageSig.S
              1. Module S.ListStorage
              1. Module S.Message
              1. Module S.Object
              1. Module S.Segment
              1. Module S.Slice
              1. Module S.StructStorage
            1. Module type MessageSig.SEGMENT
            1. Module type MessageSig.SLICE
        1. Module Capnp_unix
      1. Package cmdliner
        1. Module Cmdliner
          1. ...
          1. Module Cmdliner.Term
          1. ...
        1. Module Cmdliner_arg
        1. Module Cmdliner_base
        1. Module Cmdliner_cline
        1. Module Cmdliner_cmd
        1. Module Cmdliner_docgen
        1. Module Cmdliner_eval
        1. Module Cmdliner_info
        1. Module Cmdliner_manpage
        1. Module Cmdliner_msg
        1. Module Cmdliner_term
        1. Module Cmdliner_term_deprecated
        1. Module Cmdliner_trie
      1. Package fmt
        1. Module Fmt
        1. Module Fmt_cli
        1. Module Fmt_tty
      1. Package logs
        1. Module Logs
          1. Module type Logs.LOG
          1. ...
        1. Module Logs_cli
        1. Module Logs_fmt
        1. Module Logs_lwt
          1. Module type Logs_lwt.LOG
        1. Module Logs_threaded
      1. Package lwt
        1. Module Lwt
        1. Module Lwt_bytes
        1. Module Lwt_condition
        1. Module Lwt_config
        1. Module Lwt_engine
        1. Module Lwt_features
        1. Module Lwt_fmt
        1. Module Lwt_gc
        1. Module Lwt_io
            1. Module type Lwt_io.NumberIO
        1. Module Lwt_list
        1. Module Lwt_main
            1. Module type Lwt_main.Hooks
        1. Module Lwt_mutex
        1. Module Lwt_mvar
        1. Module Lwt_pool
        1. Module Lwt_pqueue
            1. Module type Lwt_pqueue.OrderedType
            1. Module type Lwt_pqueue.S
        1. Module Lwt_preemptive
        1. Module Lwt_process
        1. Module Lwt_result
        1. Module Lwt_seq
        1. Module Lwt_sequence
        1. Module Lwt_stream
        1. Module Lwt_switch
        1. Module Lwt_sys
        1. Module Lwt_throttle
            1. Module type Lwt_throttle.S
        1. Module Lwt_timeout
        1. Module Lwt_unix
      1. Package mtime
        1. Module Mtime
        1. Module Mtime_clock
      1. Package ocaml
        1. Module Bigarray
        1. Module Condition
        1. Module Dynlink
        1. Module Event
        1. Module Mutex
        1. Module Profiling
        1. Module Semaphore
        1. Module Stdlib
        1. Module Str
        1. Module Thread
        1. Module ThreadUnix
        1. Module Topdirs
        1. Module Unix
        1. Module UnixLabels
      1. Package
      1. Package result
        1. Module Result
      1. Package stdint
        1. Module Stdint
            1. Module type Stdint.Int
Logo for Diskuv

Your safety, first.