867 lines
12 KiB
HTML
867 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Arg</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Arg</H1>
|
|
Section: OCaml library (3o)<BR>Updated: 2020-01-30<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Arg - Parsing of command line arguments.
|
|
<A NAME="lbAC"> </A>
|
|
<H2>Module</H2>
|
|
|
|
Module Arg
|
|
<A NAME="lbAD"> </A>
|
|
<H2>Documentation</H2>
|
|
|
|
<P>
|
|
Module
|
|
<B>Arg</B>
|
|
|
|
<BR> :
|
|
<B>sig end</B>
|
|
|
|
<P>
|
|
<P>
|
|
Parsing of command line arguments.
|
|
<P>
|
|
This module provides a general mechanism for extracting options and
|
|
arguments from the command line to the program.
|
|
<P>
|
|
Syntax of command lines:
|
|
A keyword is a character string starting with a
|
|
<B>-</B>
|
|
|
|
.
|
|
An option is a keyword alone or followed by an argument.
|
|
The types of keywords are:
|
|
<B>Unit</B>
|
|
|
|
,
|
|
<B>Bool</B>
|
|
|
|
,
|
|
<B>Set</B>
|
|
|
|
,
|
|
<B>Clear</B>
|
|
|
|
,
|
|
<B>String</B>
|
|
|
|
,
|
|
<B>Set_string</B>
|
|
|
|
,
|
|
<B>Int</B>
|
|
|
|
,
|
|
<B>Set_int</B>
|
|
|
|
,
|
|
<B>Float</B>
|
|
|
|
,
|
|
<B>Set_float</B>
|
|
|
|
,
|
|
<B>Tuple</B>
|
|
|
|
,
|
|
<B>Symbol</B>
|
|
|
|
, and
|
|
<B>Rest</B>
|
|
|
|
.
|
|
<B>Unit</B>
|
|
|
|
,
|
|
<B>Set</B>
|
|
|
|
and
|
|
<B>Clear</B>
|
|
|
|
keywords take no argument. A
|
|
<B>Rest</B>
|
|
|
|
keyword takes the remaining of the command line as arguments.
|
|
Every other keyword takes the following word on the command line
|
|
as argument. For compatibility with GNU getopt_long,
|
|
<B>keyword=arg</B>
|
|
|
|
is also allowed.
|
|
Arguments not preceded by a keyword are called anonymous arguments.
|
|
<P>
|
|
Examples (
|
|
<B>cmd</B>
|
|
|
|
is assumed to be the command name):
|
|
<P>
|
|
-
|
|
<B>cmd -flag </B>
|
|
|
|
(a unit option)
|
|
<P>
|
|
-
|
|
<B>cmd -int 1 </B>
|
|
|
|
(an int option with argument
|
|
<B>1</B>
|
|
|
|
)
|
|
<P>
|
|
-
|
|
<B>cmd -string foobar </B>
|
|
|
|
(a string option with argument
|
|
<B>foobar</B>
|
|
|
|
)
|
|
<P>
|
|
-
|
|
<B>cmd -float 12.34 </B>
|
|
|
|
(a float option with argument
|
|
<B>12.34</B>
|
|
|
|
)
|
|
<P>
|
|
-
|
|
<B>cmd a b c </B>
|
|
|
|
(three anonymous arguments:
|
|
<B>a</B>
|
|
|
|
,
|
|
<B>b</B>
|
|
|
|
, and
|
|
<B>c</B>
|
|
|
|
)
|
|
<P>
|
|
-
|
|
<B>cmd a b -- c d </B>
|
|
|
|
(two anonymous arguments and a rest option with
|
|
two arguments)
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>type spec </I>
|
|
|
|
=
|
|
<BR> | Unit
|
|
<B>of </B>
|
|
|
|
<B>(unit -> unit)</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Call the function with unit argument
|
|
<BR> *)
|
|
<BR> | Bool
|
|
<B>of </B>
|
|
|
|
<B>(bool -> unit)</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Call the function with a bool argument
|
|
<BR> *)
|
|
<BR> | Set
|
|
<B>of </B>
|
|
|
|
<B>bool ref</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Set the reference to true
|
|
<BR> *)
|
|
<BR> | Clear
|
|
<B>of </B>
|
|
|
|
<B>bool ref</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Set the reference to false
|
|
<BR> *)
|
|
<BR> | String
|
|
<B>of </B>
|
|
|
|
<B>(string -> unit)</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Call the function with a string argument
|
|
<BR> *)
|
|
<BR> | Set_string
|
|
<B>of </B>
|
|
|
|
<B>string ref</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Set the reference to the string argument
|
|
<BR> *)
|
|
<BR> | Int
|
|
<B>of </B>
|
|
|
|
<B>(int -> unit)</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Call the function with an int argument
|
|
<BR> *)
|
|
<BR> | Set_int
|
|
<B>of </B>
|
|
|
|
<B>int ref</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Set the reference to the int argument
|
|
<BR> *)
|
|
<BR> | Float
|
|
<B>of </B>
|
|
|
|
<B>(float -> unit)</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Call the function with a float argument
|
|
<BR> *)
|
|
<BR> | Set_float
|
|
<B>of </B>
|
|
|
|
<B>float ref</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Set the reference to the float argument
|
|
<BR> *)
|
|
<BR> | Tuple
|
|
<B>of </B>
|
|
|
|
<B>spec list</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Take several arguments according to the
|
|
spec list
|
|
<BR> *)
|
|
<BR> | Symbol
|
|
<B>of </B>
|
|
|
|
<B>string list * (string -> unit)</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Take one of the symbols as argument and
|
|
call the function with the symbol
|
|
<BR> *)
|
|
<BR> | Rest
|
|
<B>of </B>
|
|
|
|
<B>(string -> unit)</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* Stop interpreting keywords and call the
|
|
function with each remaining argument
|
|
<BR> *)
|
|
<BR> | Expand
|
|
<B>of </B>
|
|
|
|
<B>(string -> string array)</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (* If the remaining arguments to process
|
|
are of the form
|
|
<B>[-foo; arg] @ rest</B>
|
|
|
|
where "foo"
|
|
is registered as
|
|
<B>Expand f</B>
|
|
|
|
, then the
|
|
arguments
|
|
<B>f arg @ rest</B>
|
|
|
|
are
|
|
processed. Only allowed in
|
|
<B>parse_and_expand_argv_dynamic</B>
|
|
|
|
.
|
|
<BR> *)
|
|
<BR>
|
|
<P>
|
|
The concrete type describing the behavior associated
|
|
with a keyword.
|
|
<P>
|
|
<P>
|
|
<I>type key </I>
|
|
|
|
=
|
|
<B>string</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>type doc </I>
|
|
|
|
=
|
|
<B>string</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>type usage_msg </I>
|
|
|
|
=
|
|
<B>string</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>type anon_fun </I>
|
|
|
|
=
|
|
<B>string -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val parse </I>
|
|
|
|
:
|
|
<B>(key * spec * doc) list -> anon_fun -> usage_msg -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Arg.parse speclist anon_fun usage_msg</B>
|
|
|
|
parses the command line.
|
|
<B>speclist</B>
|
|
|
|
is a list of triples
|
|
<B>(key, spec, doc)</B>
|
|
|
|
.
|
|
<B>key</B>
|
|
|
|
is the option keyword, it must start with a
|
|
<B>'-'</B>
|
|
|
|
character.
|
|
<B>spec</B>
|
|
|
|
gives the option type and the function to call when this option
|
|
is found on the command line.
|
|
<B>doc</B>
|
|
|
|
is a one-line description of this option.
|
|
<B>anon_fun</B>
|
|
|
|
is called on anonymous arguments.
|
|
The functions in
|
|
<B>spec</B>
|
|
|
|
and
|
|
<B>anon_fun</B>
|
|
|
|
are called in the same order
|
|
as their arguments appear on the command line.
|
|
<P>
|
|
If an error occurs,
|
|
<B>Arg.parse</B>
|
|
|
|
exits the program, after printing
|
|
to standard error an error message as follows:
|
|
<P>
|
|
- The reason for the error: unknown option, invalid or missing argument, etc.
|
|
<P>
|
|
-
|
|
<B>usage_msg</B>
|
|
|
|
<P>
|
|
<P>
|
|
- The list of options, each followed by the corresponding
|
|
<B>doc</B>
|
|
|
|
string.
|
|
Beware: options that have an empty
|
|
<B>doc</B>
|
|
|
|
string will not be included in the
|
|
list.
|
|
<P>
|
|
For the user to be able to specify anonymous arguments starting with a
|
|
<B>-</B>
|
|
|
|
, include for example
|
|
<B>(-, String anon_fun, doc)</B>
|
|
|
|
in
|
|
<B>speclist</B>
|
|
|
|
.
|
|
<P>
|
|
By default,
|
|
<B>parse</B>
|
|
|
|
recognizes two unit options,
|
|
<B>-help</B>
|
|
|
|
and
|
|
<B>--help</B>
|
|
|
|
,
|
|
which will print to standard output
|
|
<B>usage_msg</B>
|
|
|
|
and the list of
|
|
options, and exit the program. You can override this behaviour
|
|
by specifying your own
|
|
<B>-help</B>
|
|
|
|
and
|
|
<B>--help</B>
|
|
|
|
options in
|
|
<B>speclist</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val parse_dynamic </I>
|
|
|
|
:
|
|
<B>(key * spec * doc) list ref -></B>
|
|
|
|
<B>anon_fun -> usage_msg -> unit</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Arg.parse</B>
|
|
|
|
, except that the
|
|
<B>speclist</B>
|
|
|
|
argument is a reference
|
|
and may be updated during the parsing. A typical use for this feature
|
|
is to parse command lines of the form:
|
|
<P>
|
|
- command subcommand
|
|
<B>options</B>
|
|
|
|
where the list of options depends on the value of the subcommand argument.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val parse_argv </I>
|
|
|
|
:
|
|
<B>?current:int ref -></B>
|
|
|
|
<B>string array -></B>
|
|
|
|
<B>(key * spec * doc) list -> anon_fun -> usage_msg -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Arg.parse_argv ~current args speclist anon_fun usage_msg</B>
|
|
|
|
parses
|
|
the array
|
|
<B>args</B>
|
|
|
|
as if it were the command line. It uses and updates
|
|
the value of
|
|
<B>~current</B>
|
|
|
|
(if given), or
|
|
<B>Arg.current</B>
|
|
|
|
. You must set
|
|
it before calling
|
|
<B>parse_argv</B>
|
|
|
|
. The initial value of
|
|
<B>current</B>
|
|
|
|
is the index of the program name (argument 0) in the array.
|
|
If an error occurs,
|
|
<B>Arg.parse_argv</B>
|
|
|
|
raises
|
|
<B>Arg.Bad</B>
|
|
|
|
with
|
|
the error message as argument. If option
|
|
<B>-help</B>
|
|
|
|
or
|
|
<B>--help</B>
|
|
|
|
is
|
|
given,
|
|
<B>Arg.parse_argv</B>
|
|
|
|
raises
|
|
<B>Arg.Help</B>
|
|
|
|
with the help message
|
|
as argument.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val parse_argv_dynamic </I>
|
|
|
|
:
|
|
<B>?current:int ref -></B>
|
|
|
|
<B>string array -></B>
|
|
|
|
<B>(key * spec * doc) list ref -></B>
|
|
|
|
<B>anon_fun -> string -> unit</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Arg.parse_argv</B>
|
|
|
|
, except that the
|
|
<B>speclist</B>
|
|
|
|
argument is a
|
|
reference and may be updated during the parsing.
|
|
See
|
|
<B>Arg.parse_dynamic</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val parse_and_expand_argv_dynamic </I>
|
|
|
|
:
|
|
<B>int ref -></B>
|
|
|
|
<B>string array ref -></B>
|
|
|
|
<B>(key * spec * doc) list ref -></B>
|
|
|
|
<B>anon_fun -> string -> unit</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Arg.parse_argv_dynamic</B>
|
|
|
|
, except that the
|
|
<B>argv</B>
|
|
|
|
argument is a
|
|
reference and may be updated during the parsing of
|
|
<B>Expand</B>
|
|
|
|
arguments.
|
|
See
|
|
<B>Arg.parse_argv_dynamic</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.05.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val parse_expand </I>
|
|
|
|
:
|
|
<B>(key * spec * doc) list -> anon_fun -> usage_msg -> unit</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Arg.parse</B>
|
|
|
|
, except that the
|
|
<B>Expand</B>
|
|
|
|
arguments are allowed and
|
|
the
|
|
<B>Arg.current</B>
|
|
|
|
reference is not updated.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.05.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>exception Help </I>
|
|
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<P>
|
|
<P>
|
|
Raised by
|
|
<B>Arg.parse_argv</B>
|
|
|
|
when the user asks for help.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>exception Bad </I>
|
|
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<P>
|
|
<P>
|
|
Functions in
|
|
<B>spec</B>
|
|
|
|
or
|
|
<B>anon_fun</B>
|
|
|
|
can raise
|
|
<B>Arg.Bad</B>
|
|
|
|
with an error
|
|
message to reject invalid arguments.
|
|
<B>Arg.Bad</B>
|
|
|
|
is also raised by
|
|
<B>Arg.parse_argv</B>
|
|
|
|
in case of an error.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val usage </I>
|
|
|
|
:
|
|
<B>(key * spec * doc) list -> usage_msg -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Arg.usage speclist usage_msg</B>
|
|
|
|
prints to standard error
|
|
an error message that includes the list of valid options. This is
|
|
the same message that
|
|
<B>Arg.parse</B>
|
|
|
|
prints in case of error.
|
|
<B>speclist</B>
|
|
|
|
and
|
|
<B>usage_msg</B>
|
|
|
|
are the same as for
|
|
<B>Arg.parse</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val usage_string </I>
|
|
|
|
:
|
|
<B>(key * spec * doc) list -> usage_msg -> string</B>
|
|
|
|
<P>
|
|
Returns the message that would have been printed by
|
|
<B>Arg.usage</B>
|
|
|
|
,
|
|
if provided with the same parameters.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val align </I>
|
|
|
|
:
|
|
<B>?limit:int -></B>
|
|
|
|
<B>(key * spec * doc) list -> (key * spec * doc) list</B>
|
|
|
|
<P>
|
|
Align the documentation strings by inserting spaces at the first alignment
|
|
separator (tab or, if tab is not found, space), according to the length of
|
|
the keyword. Use a alignment separator as the first character in a doc
|
|
string if you want to align the whole string. The doc strings corresponding
|
|
to
|
|
<B>Symbol</B>
|
|
|
|
arguments are aligned on the next line.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val current </I>
|
|
|
|
:
|
|
<B>int ref</B>
|
|
|
|
<P>
|
|
Position (in
|
|
<B>Sys.argv</B>
|
|
|
|
) of the argument being processed. You can
|
|
change this value, e.g. to force
|
|
<B>Arg.parse</B>
|
|
|
|
to skip some arguments.
|
|
<B>Arg.parse</B>
|
|
|
|
uses the initial value of
|
|
<B>Arg.current</B>
|
|
|
|
as the index of
|
|
argument 0 (the program name) and starts parsing arguments
|
|
at the next element.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val read_arg </I>
|
|
|
|
:
|
|
<B>string -> string array</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Arg.read_arg file</B>
|
|
|
|
reads newline-terminated command line arguments from
|
|
file
|
|
<B>file</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.05.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val read_arg0 </I>
|
|
|
|
:
|
|
<B>string -> string array</B>
|
|
|
|
<P>
|
|
Identical to
|
|
<B>Arg.read_arg</B>
|
|
|
|
but assumes null character terminated command
|
|
line arguments.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.05.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val write_arg </I>
|
|
|
|
:
|
|
<B>string -> string array -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Arg.write_arg file args</B>
|
|
|
|
writes the arguments
|
|
<B>args</B>
|
|
|
|
newline-terminated
|
|
into the file
|
|
<B>file</B>
|
|
|
|
. If the any of the arguments in
|
|
<B>args</B>
|
|
|
|
contains a
|
|
newline, use
|
|
<B>Arg.write_arg0</B>
|
|
|
|
instead.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.05.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val write_arg0 </I>
|
|
|
|
:
|
|
<B>string -> string array -> unit</B>
|
|
|
|
<P>
|
|
Identical to
|
|
<B>Arg.write_arg</B>
|
|
|
|
but uses the null character for terminator
|
|
instead of newline.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.05.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">Module</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">Documentation</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:35 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|