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:
Add the following to your project's
dependencies/CMakeLists.txt:DkSDKProject_DeclareAvailable(cmdliner CONSTRAINT "= 1.1.1+dune" FINDLIBS cmdliner) DkSDKProject_MakeAvailable(cmdliner)Add the
Findlib::cmdlinerlibrary to any desired targets insrc/*/CMakeLists.txt:target_link_libraries(YourPackage_YourLibraryName # ... existing libraries, if any ... Findlib::cmdliner)Click your IDE's
Buildbutton
Not using DkSDK?
FIRST, do one or all of the following:
Run:
opam install cmdliner.1.1.1+duneEdit your
dune-projectand add:(package (name YourExistingPackage) (depends ; ... existing dependenices ... (cmdliner (>= 1.1.1+dune))))Then run:
dune build *.opam # if this fails, run: dune buildEdit your
<package>.opamfile and add:depends: [ # ... existing dependencies ... "cmdliner" {>= "1.1.1+dune"} ]Then run:
opam install . --deps-only
FINALLY, add the cmdliner library to any desired (library)and/or (executable) targets in your **/dune files:
(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 ```` ]`
type``'a printer`` =Stdlib.Format.formatter->'a->unit
The type for converted argument printers.
valconv : ``?docv:string->``(``(``string->``('a, ``[ ```Msg of string ``` ])[result](../../ocaml/Stdlib/#type-result))`` * `'aprinter) `` \`->`` ``'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".
conv' is like conv but the Error case has an
unlabelled string.
valconv_parser :'aconv->``string->``('a, ``[ ```Msg of string ``` ])[result`](../../ocaml/Stdlib/#type-result)
conv_parser c is the parser of c.
valconv_docv :'aconv->string
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.).
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.
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.
typeinfo
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.
-
namesdefines the names under which an optional argument can be referred to. Strings of length1("c") define short option names ("-c"), longer strings ("count") define long option names ("--count").namesmust be empty for positional arguments. -
envdefines 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. -
docis the man page information of the argument. The documentation language can be used and the following variables are recognized:"$(docv)"the value ofdocv(see below)."$(opt)", one of the options ofnames, preference is given to a long one."$(env)", the environment var specified byenv(if any).
These functions can help with formatting argument values.
-
docvis for positional and non-flag optional arguments. It is a variable name used in the man page to stand for their value. -
docsis the title of the man page section in which the argument will be listed. For optional arguments this defaults toManpage.s_options. For positional arguments this defaults toManpage.s_arguments. However a positional argument is only listed if it has both adocanddocvspecified. -
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 indoc. 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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).
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.
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.formatTerm.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``->'aconv
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
lis 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.
list sep c splits the argument at each sep (defaults to ',')
character and converts each substrings with c.
array sep c splits the argument at each sep (defaults to ',')
character and converts each substring with c.
pair sep c0 c1 splits the argument at the first sep character
(defaults to ',') and respectively converts the substrings with c0
and c1.
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.
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 withdoc_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
altsis 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
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.
