NAME¶
Arg - Parsing of command line arguments.
Module¶
Module Arg
Documentation¶
Module
Arg
:
sig end
Parsing of command line arguments.
This module provides a general mechanism for extracting options and arguments
from the command line to the program.
Syntax of command lines: A keyword is a character string starting with a
- . An option is a keyword alone or followed by an argument. The types
of keywords are:
Unit ,
Bool ,
Set ,
Clear ,
String ,
Set_string ,
Int ,
Set_int ,
Float
,
Set_float ,
Tuple ,
Symbol , and
Rest .
Unit ,
Set and
Clear keywords take no argument. A
Rest keyword takes the remaining of the command line as arguments.
Every other keyword takes the following word on the command line as argument.
Arguments not preceded by a keyword are called anonymous arguments.
Examples (
cmd is assumed to be the command name):
-
cmd -flag (a unit option)
-
cmd -int 1 (an int option with argument
1 )
-
cmd -string foobar (a string option with argument
foobar )
-
cmd -float 12.34 (a float option with argument
12.34 )
-
cmd a b c (three anonymous arguments:
a ,
b , and
c )
-
cmd a b -- c d (two anonymous arguments and a rest option with two
arguments)
type spec =
| Unit
of (unit -> unit) (* Call the function with
unit argument *)
| Bool
of (bool -> unit) (* Call the function with a
bool argument *)
| Set
of bool Pervasives.ref (* Set the reference to
true *)
| Clear
of bool Pervasives.ref (* Set the reference to
false *)
| String
of (string -> unit) (* Call the function
with a string argument *)
| Set_string
of string Pervasives.ref (* Set the
reference to the string argument *)
| Int
of (int -> unit) (* Call the function with an
int argument *)
| Set_int
of int Pervasives.ref (* Set the reference to
the int argument *)
| Float
of (float -> unit) (* Call the function with
a float argument *)
| Set_float
of float Pervasives.ref (* Set the reference
to the float argument *)
| Tuple
of spec list (* Take several arguments according
to the spec list *)
| Symbol
of string list * (string -> unit) (* Take
one of the symbols as argument and call the function with the symbol *)
| Rest
of (string -> unit) (* Stop interpreting
keywords and call the function with each remaining argument *)
The concrete type describing the behavior associated with a keyword.
type key =
string
type doc =
string
type usage_msg =
string
type anon_fun =
string -> unit
val parse :
(key * spec * doc) list -> anon_fun -> usage_msg
-> unit
Arg.parse speclist anon_fun usage_msg parses the command line.
speclist is a list of triples
(key, spec, doc) .
key is
the option keyword, it must start with a
'-' character.
spec
gives the option type and the function to call when this option is found on
the command line.
doc is a one-line description of this option.
anon_fun is called on anonymous arguments. The functions in
spec
and
anon_fun are called in the same order as their arguments appear on
the command line.
If an error occurs,
Arg.parse exits the program, after printing to
standard error an error message as follows:
- The reason for the error: unknown option, invalid or missing argument, etc.
-
usage_msg
- The list of options, each followed by the corresponding
doc string.
For the user to be able to specify anonymous arguments starting with a
-
, include for example
("-", String anon_fun, doc) in
speclist .
By default,
parse recognizes two unit options,
-help and
--help , which will print to standard output
usage_msg and the
list of options, and exit the program. You can override this behaviour by
specifying your own
-help and
--help options in
speclist
.
val parse_argv :
?current:int Pervasives.ref -> string array
-> (key * spec * doc) list -> anon_fun -> usage_msg ->
unit
Arg.parse_argv ~current args speclist anon_fun usage_msg parses the array
args as if it were the command line. It uses and updates the value of
~current (if given), or
Arg.current . You must set it before
calling
parse_argv . The initial value of
current is the index
of the program name (argument 0) in the array. If an error occurs,
Arg.parse_argv raises
Arg.Bad with the error message as
argument. If option
-help or
--help is given,
Arg.parse_argv raises
Arg.Help with the help message as
argument.
exception Help of string
Raised by
Arg.parse_argv when the user asks for help.
exception Bad of string
Functions in
spec or
anon_fun can raise
Arg.Bad with an
error message to reject invalid arguments.
Arg.Bad is also raised by
Arg.parse_argv in case of an error.
val usage :
(key * spec * doc) list -> usage_msg -> unit
Arg.usage speclist usage_msg prints to standard error an error message
that includes the list of valid options. This is the same message that
Arg.parse prints in case of error.
speclist and
usage_msg
are the same as for
Arg.parse .
val usage_string :
(key * spec * doc) list -> usage_msg ->
string
Returns the message that would have been printed by
Arg.usage , if
provided with the same parameters.
val align :
(key * spec * doc) list -> (key * spec * doc) list
Align the documentation strings by inserting spaces at the first space,
according to the length of the keyword. Use a space as the first character in
a doc string if you want to align the whole string. The doc strings
corresponding to
Symbol arguments are aligned on the next line.
val current :
int Pervasives.ref
Position (in
Sys.argv ) of the argument being processed. You can change
this value, e.g. to force
Arg.parse to skip some arguments.
Arg.parse uses the initial value of
Arg.current as the index of
argument 0 (the program name) and starts parsing arguments at the next
element.