Module Cmdliner.Arg

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

Argument converters

An argument converter transforms a string argument of the command line to an OCaml value. Predefined converters are provided for many types of the standard library.

type``'a parser`` = ``string->``[ ```Ok of  ````'a``` |Error ``` of string ```` ]`

The type for argument parsers.

Deprecated. Use parser signatures of conv or conv'.

  • deprecated Use Arg.conv or Arg.conv' instead.
type``'a printer`` =Stdlib.Format.formatter -> 'a -> unit

The type for converted argument printers.

type``'a conv`` ='a parser*'a printer

The type for argument converters.

Warning. Do not use directly, use conv or conv'. This type will become abstract in the next major version of cmdliner.

valconv : ``?docv:string->``(``(``string-> ``('a, ``[ ``` Msg of string ``` ]) [result](../../ocaml/Stdlib/#type-result))``  * `'a printer) `` \`->`` ``'a`` ``conv`

conv ~docv (parse, print) is an argument converter parsing values with parse and printing them with print. docv is a documentation meta-variable used in the documentation to stand for the argument value, defaults to "VALUE".

valconv' : ``?docv:string->``(``(``string-> ``('a, string)`` result)`` * 'a printer)`` -> 'a conv

conv' is like conv but the Error case has an unlabelled string.

valconv_parser :'a conv ->``string-> ``('a, ``[ ``` Msg of string ``` ]) [result`](../../ocaml/Stdlib/#type-result)

conv_parser c is the parser of c.

valconv_printer :'a conv -> 'a printer

conv_printer c is the printer of c.

valconv_docv :'a conv -> string

conv_docv c is c's documentation meta-variable.

Warning. Currently always returns "VALUE" in the future will return the value given to conv or conv'.

valparser_of_kind_of_string : ``kind:string->``(``string-> 'aoption``)``->``string-> ``('a, ``[ ``` Msg of string ``` ]) [result`](../../ocaml/Stdlib/#type-result)

parser_of_kind_of_string ~kind kind_of_string is an argument parser using the kind_of_string function for parsing and kind to report errors (e.g. could be "an integer" for an int parser.).

val some' : ``?none:'a -> 'a conv -> 'aoption``conv

some' ?none c is like the converter c except it returns Some value. It is used for command line arguments that default to None when absent. If provided, none is used with conv's printer to document the value taken on absence; to document a more complex behaviour use the absent argument of info.

valsome : ``?none:string-> 'a conv -> 'aoption``conv

some ?none c is like some' but none is described as a string that will be rendered in bold.

Arguments and their information

Argument information defines the man page information of an argument and, for optional arguments, its names. An environment variable can also be specified to read the argument value from if the argument is absent from the command line and the variable is defined.

type ``'a t

The type for arguments holding data of type 'a.

type info

The type for information about command line arguments.

valinfo : ``?deprecated:string->``?absent:string->``?docs:string->``?docv:string->``?doc:string-> ``?env:Cmd.Env.info ->``string list``-> info

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

  • names defines the names under which an optional argument can be referred to. Strings of length 1 ("c") define short option names ("-c"), longer strings ("count") define long option names ("--count"). names must be empty for positional arguments.

  • 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.

  • deprecated, if specified the argument is deprecated and the string is a message output on standard error when the argument is used.

  • absent, if specified a documentation string that indicates what happens when the argument is absent. The document language can be used like in doc. This overrides the automatic default value rendering that is performed by the combinators.

val (&) : ``('a -> 'b)`` -> 'a -> 'b

f & v is f v, a right associative composition operator for specifying argument terms.

Optional arguments

The information of an optional argument must have at least one name or Invalid_argument is raised.

valflag :info ->``boolt

flag i is a bool argument defined by an optional flag that may appear at most once on the command line under one of the names specified by i. The argument holds true if the flag is present on the command line and false otherwise.

valflag_all :info ->``bool list``t

flag_all is like flag except the flag may appear more than once. The argument holds a list that contains one true value per occurrence of the flag. It holds the empty list if the flag is absent from the command line.

valvflag :'a -> ``('a*info)`` list`` -> 'a t

vflag v [v0,i0;…] is an 'a argument defined by an optional flag that may appear at most once on the command line under one of the names specified in the ik values. The argument holds v if the flag is absent from the command line and the value vk if the name under which it appears is in ik.

Note. Environment variable lookup is unsupported for for these arguments.

valvflag_all :'alist``-> ``('a*info)`` list`` -> 'alist``t

vflag_all v l is like vflag except the flag may appear more than once. The argument holds the list v if the flag is absent from the command line. Otherwise it holds a list that contains one corresponding value per occurrence of the flag, in the order found on the command line.

Note. Environment variable lookup is unsupported for for these arguments.

val opt : ``?vopt:'a -> 'a conv -> 'a -> info -> 'a t

opt vopt c v i is an 'a argument defined by the value of an optional argument that may appear at most once on the command line under one of the names specified by i. The argument holds v if the option is absent from the command line. Otherwise it has the value of the option as converted by c.

If vopt is provided the value of the optional argument is itself optional, taking the value vopt if unspecified on the command line.

val opt_all : ``?vopt:'a -> 'a conv -> 'alist``-> info -> 'alist``t

opt_all vopt c v i is like opt except the optional argument may appear more than once. The argument holds a list that contains one value per occurrence of the flag in the order found on the command line. It holds the list v if the flag is absent from the command line.

Positional arguments

The information of a positional argument must have no name or Invalid_argument is raised. Positional arguments indexing is zero-based.

Warning. The following combinators allow to specify and extract a given positional argument with more than one term. This should not be done as it will likely confuse end users and documentation generation. These over-specifications may be prevented by raising Invalid_argument in the future. But for now it is the client's duty to make sure this doesn't happen.

valpos : ``?rev:bool->``int-> 'a conv -> 'a -> info -> 'a t

pos rev n c v i is an 'a argument defined by the nth positional argument of the command line as converted by c. If the positional argument is absent from the command line the argument is v.

If rev is true (defaults to false), the computed position is max-n where max is the position of the last positional argument present on the command line.

valpos_all :'a conv -> 'alist``-> info -> 'alist``t

pos_all c v i is an 'a list argument that holds all the positional arguments of the command line as converted by c or v if there are none.

valpos_left : ``?rev:bool->``int-> 'a conv -> 'alist``-> info -> 'alist``t

pos_left rev n c v i is an 'a list argument that holds all the positional arguments as converted by c found on the left of the nth positional argument or v if there are none.

If rev is true (defaults to false), the computed position is max-n where max is the position of the last positional argument present on the command line.

valpos_right : ``?rev:bool->``int-> 'a conv -> 'alist``-> info -> 'alist``t

pos_right is like pos_left except it holds all the positional arguments found on the right of the specified positional argument.

Arguments as terms

valvalue :'a t -> 'a Term.t

value a is a term that evaluates to a's value.

valrequired :'aoption``t -> 'a Term.t

required a is a term that fails if a's value is None and evaluates to the value of Some otherwise. Use this for required positional arguments (it can also be used for defining required optional arguments, but from a user interface perspective this shouldn't be done, it is a contradiction in terms).

valnon_empty :'alist``t -> 'alist``Term.t

non_empty a is term that fails if a's list is empty and evaluates to a's list otherwise. Use this for non empty lists of positional arguments.

vallast :'alist``t -> 'a Term.t

last a is a term that fails if a's list is empty and evaluates to the value of the last element of the list otherwise. Use this for lists of flags or options where the last occurrence takes precedence over the others.

Predefined arguments

valman_format :Manpage.format Term.t

man_format is a term that defines a --man-format option and evaluates to a value that can be used with Manpage.print.

Predefined converters

valbool : ``boolconv

bool converts values with bool_of_string.

valchar : ``charconv

char converts values by ensuring the argument has a single char.

valint : ``intconv

int converts values with int_of_string.

valnativeint : ``nativeintconv

nativeint converts values with Nativeint.of_string.

valint32 : ``int32conv

int32 converts values with Int32.of_string.

valint64 : ``int64conv

int64 converts values with Int64.of_string.

valfloat : ``floatconv

float converts values with float_of_string.

valstring : ``stringconv

string converts values with the identity function.

valenum : ``(string *'a)`` list`` -> 'a conv

enum l p converts values such that unambiguous prefixes of string names in l map to the corresponding value of type 'a.

Warning. The type 'a must be comparable with Stdlib.compare.

  • raises Invalid_argument

    if l is empty.

valfile : ``stringconv

file converts a value with the identity function and checks with Sys.file_exists that a file with that name exists.

valdir : ``stringconv

dir converts a value with the identity function and checks with Sys.file_exists and Sys.is_directory that a directory with that name exists.

valnon_dir_file : ``stringconv

non_dir_file converts a value with the identity function and checks with Sys.file_exists and Sys.is_directory that a non directory file with that name exists.

vallist : ``?sep:char-> 'a conv -> 'alist``conv

list sep c splits the argument at each sep (defaults to ',') character and converts each substrings with c.

valarray : ``?sep:char-> 'a conv -> 'aarray``conv

array sep c splits the argument at each sep (defaults to ',') character and converts each substring with c.

valpair : ``?sep:char-> 'a conv -> 'b conv -> ``('a*'b)`` conv

pair sep c0 c1 splits the argument at the first sep character (defaults to ',') and respectively converts the substrings with c0 and c1.

valt2 : ``?sep:char-> 'a conv -> 'b conv -> ``('a*'b)`` conv

t2 is pair.

valt3 : ``?sep:char-> 'a conv -> 'b conv -> 'c conv -> ``('a*'b*'c)`` conv

t3 sep c0 c1 c2 splits the argument at the first two sep characters (defaults to ',') and respectively converts the substrings with c0, c1 and c2.

valt4 : ``?sep:char-> 'a conv -> 'b conv -> 'c conv -> 'd conv -> ``('a*'b*'c*'d)`` conv

t4 sep c0 c1 c2 c3 splits the argument at the first three sep characters (defaults to ',') respectively converts the substrings with c0, c1, c2 and c3.

Documentation formatting helpers

valdoc_quote : ``string-> string

doc_quote s quotes the string s.

valdoc_alts : ``?quoted:bool->``string list``-> string

doc_alts alts documents the alternative tokens alts according the number of alternatives. If quoted is:

  • None, the tokens are enclosed in manpage markup directives to render them in bold (manpage convention).
  • Some true, the tokens are quoted with doc_quote.
  • Some false, the tokens are written as is

The resulting string can be used in sentences of the form "$(docv) must be %s".

  • raises Invalid_argument

    if alts is the empty list.

valdoc_alts_enum : ``?quoted:bool->``(string *'a)`` list`` -> string

doc_alts_enum quoted alts is doc_alts quoted (List.map fst alts).

Deprecated

type``'a converter`` ='a conv

See Arg.conv'.

  • deprecated Use Arg.conv' function instead.
valpconv : ``?docv:string-> ``('a parser*'a printer)`` -> 'a conv

pconv is like conv or conv', but uses a deprecated parser signature.

  • deprecated Use Arg.conv or Arg.conv' function instead.
typeenv`` =Cmd.Env.info

See Cmd.Env.info

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

See Cmd.Env.info.

  • deprecated Use Cmd.Env.info 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.Arg
          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