Module Cmdliner.Cmd

Command information
Commands
Evaluation
- Low level evaluation

Instructions: Use this module in your project

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

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

Copy

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

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)

Click your IDE's Build button

Not using DkSDK?

FIRST, do one or all of the following:

Run:
Copy
```
opam install cmdliner.1.1.1+dune
```

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

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

Command information

Command information defines the name and documentation of a command.

module Exit:sig...end

Exit codes and their information.

module Env:sig...end

Environment variable and their information.

type info

The type for information about commands.

valinfo : ``?deprecated:string-> ``?man_xrefs:Manpage.xreflist``-> ``?man:Manpage.blocklist``-> ``?envs:Env.infolist``-> ``?exits:Exit.infolist``->``?sdocs:string->``?docs:string->``?doc:string->``?version:string->``string-> info

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

name is the name of the command.
version is the version string of the command line tool, this is only relevant for the main command and ignored otherwise.
deprecated, if specified the command is deprecated and the string is a message output on standard error when the command is used.
doc is a one line description of the command used for the NAME section of the command's man page and in command group listings.
docs, for commands that are part of a group, the title of the section of the parent's command 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_common_options).
exits is a list of exit statuses that the command evaluation may produce, defaults to Exit.defaults.
envs is a list of environment variables that influence the command's evaluation.
man is the text of the man page for the command.
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) command's name.
$(mname) the main command name.

Commands

type ``'a t

The type for commands whose evaluation result in a value of type 'a.

valv :info -> 'a Term.t -> 'a t

v i t is a command with information i and command line syntax parsed by t.

val group : ``?default:'a Term.t -> info -> 'a tlist``-> 'a t

group i ?default cmds is a command with information i that groups sub commands cmds. default is the command line syntax to parse if no sub command is specified on the command line. If default is None (default), the tool errors when no sub command is specified.

valname :'a t -> string

name c is the name of c.

Evaluation

These functions are meant to be composed with Stdlib.exit. The following exit codes may be returned by all these functions:

Exit.cli_error if a parse error occurs.
Exit.internal_error if the ~catch argument is true (default) and an uncaught exception is raised.
The value of ~term_err (defaults to Exit.cli_error) if a term error occurs.

These exit codes are described in Exit.defaults which is the default value of the ?exits argument of function info.

val eval : ``?help:Stdlib.Format.formatter -> ``?err:Stdlib.Format.formatter ->``?catch:bool->``?env:``(``string->``string option``)``->``?argv:``string array``-> ``?term_err:Exit.code ->``unitt -> Exit.code

eval cmd is Exit.ok if cmd evaluates to (). See eval_value for other arguments.

val eval' : ``?help:Stdlib.Format.formatter -> ``?err:Stdlib.Format.formatter ->``?catch:bool->``?env:``(``string->``string option``)``->``?argv:``string array``-> ``?term_err:Exit.code -> Exit.code t -> Exit.code

eval' cmd is c if cmd evaluates to the exit code c. See eval_value for other arguments.

val eval_result : ``?help:Stdlib.Format.formatter -> ``?err:Stdlib.Format.formatter ->``?catch:bool->``?env:``(``string->``string option``)``->``?argv:``string array``-> ``?term_err:Exit.code ->``(unit, string)``result t -> Exit.code

eval_result cmd is:

Exit.ok if cmd evaluates to Ok ().
Exit.some_error if cmd evaluates to Error msg. In this case msg is printed on err.

See eval_value for other arguments.

val eval_result' : ``?help:Stdlib.Format.formatter -> ``?err:Stdlib.Format.formatter ->``?catch:bool->``?env:``(``string->``string option``)``->``?argv:``string array``-> ``?term_err:Exit.code -> ``(Exit.code, string)`` result t -> Exit.code

eval_result' cmd is:

c if cmd evaluates to Ok c.
Exit.some_error if cmd evaluates to Error msg. In this case msg is printed on err.

See eval_value for other arguments.

Low level evaluation

This interface gives more information on command evaluation results and lets you choose how to map evaluation results to exit codes.

type``'a eval_ok`` = ``[


| ``` Ok  ``of 'a
(*
The term of the command evaluated to this value.
*)
   


| ``` Version ``
(*
The version of the main cmd was requested.
*)
   


| ``` Help ``
(*
Help was requested.
*)
   
 ]

The type for successful evaluation results.

typeeval_error`` = ``[


| ``` Parse ``
(*
A parse error occured.
*)
   


| ``` Term ``
(*
A term evaluation error occured.
*)
   


| ``` Exn ``
(*
An uncaught exception occured.
*)
   
 ]

The type for erroring evaluation results.

val eval_value : ``?help:Stdlib.Format.formatter -> ``?err:Stdlib.Format.formatter ->``?catch:bool->``?env:``(``string->``string option``)``->``?argv:``string array``-> 'a t -> ``('a eval_ok, eval_error)`` result

eval ~help ~err ~catch ~env ~argv cmd is the evaluation result of cmd with:

argv the command line arguments to parse (defaults to Sys.argv)
env the function used for environment variable lookup (defaults to Sys.getenv.
catch if 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.

valeval_peek_opts : ``?version_opt:bool->``?env:``(``string->``string option``)``->``?argv:``string array``-> 'a Term.t -> 'a option`` * ``('a eval_ok, eval_error)`` 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_value 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.

More from the DkSDK Book

1. DkSDK
1. 1. Package capnp
  1. 1. Module Capnp
    1. Module Capnp_unix
  1. Package cmdliner
  1. 1. Module Cmdliner
    1. 1. ...
      1. Module Cmdliner.Cmd
      1. Module Cmd.Env
        Module Cmd.Exit
      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. 1. Module Fmt
    1. Module Fmt_cli
    1. Module Fmt_tty
  1. Package logs
  1. 1. Module Logs
    1. Module Logs_cli
    1. Module Logs_fmt
    1. Module Logs_lwt
    1. Module Logs_threaded
  1. Package lwt
  1. 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 Lwt_list
    1. Module Lwt_main
    1. Module Lwt_mutex
    1. Module Lwt_mvar
    1. Module Lwt_pool
    1. Module Lwt_pqueue
    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 Lwt_timeout
    1. Module Lwt_unix
  1. Package mtime
  1. 1. Module Mtime
    1. Module Mtime_clock
  1. Package ocaml
  1. 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. 1. Module Result
  1. Package stdint
  1. 1. Module Stdint