1Arg(3)                           OCaml library                          Arg(3)
2
3
4

NAME

6       Arg - Parsing of command line arguments.
7

Module

9       Module   Arg
10

Documentation

12       Module Arg
13        : sig end
14
15
16       Parsing of command line arguments.
17
18       This module provides a general mechanism for extracting options and ar‐
19       guments from the command line to the program.
20
21       Syntax of command lines: A keyword is a character string starting  with
22       a  -  .   An option is a keyword alone or followed by an argument.  The
23       types of keywords are: Unit , Bool , Set , Clear , String ,  Set_string
24       , Int , Set_int , Float , Set_float , Tuple , Symbol , and Rest .  Unit
25       , Set and Clear keywords take no argument. A Rest keyword takes the re‐
26       maining  of  the  command line as arguments.  Every other keyword takes
27       the following word on the command line as argument.  For  compatibility
28       with  GNU getopt_long, keyword=arg is also allowed.  Arguments not pre‐
29       ceded by a keyword are called anonymous arguments.
30
31       Examples ( cmd is assumed to be the command name):
32
33       - cmd -flag (a unit option)
34
35       - cmd -int 1 (an int option with argument 1 )
36
37       - cmd -string foobar (a string option with argument "foobar" )
38
39       - cmd -float 12.34 (a float option with argument 12.34 )
40
41       - cmd a b c (three anonymous arguments: "a" , "b" , and "c" )
42
43       - cmd a b -- c d (two anonymous arguments and a rest  option  with  two
44       arguments)
45
46
47
48
49
50
51       type spec =
52        | Unit of (unit -> unit)
53         (* Call the function with unit argument
54        *)
55        | Bool of (bool -> unit)
56         (* Call the function with a bool argument
57        *)
58        | Set of bool ref
59         (* Set the reference to true
60        *)
61        | Clear of bool ref
62         (* Set the reference to false
63        *)
64        | String of (string -> unit)
65         (* Call the function with a string argument
66        *)
67        | Set_string of string ref
68         (* Set the reference to the string argument
69        *)
70        | Int of (int -> unit)
71         (* Call the function with an int argument
72        *)
73        | Set_int of int ref
74         (* Set the reference to the int argument
75        *)
76        | Float of (float -> unit)
77         (* Call the function with a float argument
78        *)
79        | Set_float of float ref
80         (* Set the reference to the float argument
81        *)
82        | Tuple of spec list
83         (* Take several arguments according to the spec list
84        *)
85        | Symbol of string list * (string -> unit)
86         (* Take one of the symbols as argument and call the function with the
87       symbol
88        *)
89        | Rest of (string -> unit)
90         (* Stop interpreting keywords and call the function with each remain‐
91       ing argument
92        *)
93        | Expand of (string -> string array)
94         (*  If  the  remaining  arguments to process are of the form ["-foo";
95       "arg"] @ rest where "foo" is registered as Expand f ,  then  the  argu‐
96       ments  f  "arg"  @  rest  are  processed. Only allowed in parse_and_ex‐
97       pand_argv_dynamic .
98        *)
99
100
101       The concrete type describing the behavior associated with a keyword.
102
103
104       type key = string
105
106
107
108
109       type doc = string
110
111
112
113
114       type usage_msg = string
115
116
117
118
119       type anon_fun = string -> unit
120
121
122
123
124
125       val parse : (key * spec * doc) list -> anon_fun -> usage_msg -> unit
126
127
128       Arg.parse  speclist  anon_fun  usage_msg  parses  the   command   line.
129       speclist  is  a  list  of triples (key, spec, doc) .  key is the option
130       keyword, it must start with a '-' character.   spec  gives  the  option
131       type  and the function to call when this option is found on the command
132       line.  doc is a one-line  description  of  this  option.   anon_fun  is
133       called  on anonymous arguments.  The functions in spec and anon_fun are
134       called in the same order as their arguments appear on the command line.
135
136       If an error occurs, Arg.parse exits  the  program,  after  printing  to
137       standard error an error message as follows:
138
139       -   The  reason for the error: unknown option, invalid or missing argu‐
140       ment, etc.
141
142       - usage_msg
143
144
145       -  The list of options, each followed by the corresponding doc  string.
146       Beware:  options  that have an empty doc string will not be included in
147       the list.
148
149       For the user to be able to specify anonymous arguments starting with  a
150       - , include for example ("-", String anon_fun, doc) in speclist .
151
152       By default, parse recognizes two unit options, -help and --help , which
153       will print to standard output usage_msg and the list  of  options,  and
154       exit  the  program.  You can override this behaviour by specifying your
155       own -help and --help options in speclist .
156
157
158
159       val parse_dynamic : (key * spec * doc) list  ref  ->  anon_fun  ->  us‐
160       age_msg -> unit
161
162       Same  as  Arg.parse  , except that the speclist argument is a reference
163       and may be updated during the parsing. A typical use for  this  feature
164       is to parse command lines of the form:
165
166       -     command  subcommand  options where the list of options depends on
167       the value of the subcommand argument.
168
169
170
171       Since 4.01.0
172
173
174
175       val parse_argv : ?current:int ref -> string array -> (key * spec * doc)
176       list -> anon_fun -> usage_msg -> unit
177
178
179       Arg.parse_argv ~current args speclist anon_fun usage_msg parses the ar‐
180       ray args as if it were the command line.  It uses and updates the value
181       of  ~current (if given), or Arg.current .  You must set it before call‐
182       ing parse_argv .  The initial value of current is the index of the pro‐
183       gram   name   (argument   0)   in  the  array.   If  an  error  occurs,
184       Arg.parse_argv raises Arg.Bad with the error message as  argument.   If
185       option  -help  or  --help is given, Arg.parse_argv raises Arg.Help with
186       the help message as argument.
187
188
189
190       val parse_argv_dynamic : ?current:int ref -> string  array  ->  (key  *
191       spec * doc) list ref -> anon_fun -> string -> unit
192
193       Same  as Arg.parse_argv , except that the speclist argument is a refer‐
194       ence and may be updated during the parsing.  See Arg.parse_dynamic .
195
196
197       Since 4.01.0
198
199
200
201       val parse_and_expand_argv_dynamic : int ref -> string array ref -> (key
202       * spec * doc) list ref -> anon_fun -> string -> unit
203
204       Same  as  Arg.parse_argv_dynamic  ,  except that the argv argument is a
205       reference and may be updated during the parsing  of  Expand  arguments.
206       See Arg.parse_argv_dynamic .
207
208
209       Since 4.05.0
210
211
212
213       val  parse_expand : (key * spec * doc) list -> anon_fun -> usage_msg ->
214       unit
215
216       Same as Arg.parse , except that the Expand arguments  are  allowed  and
217       the Arg.current reference is not updated.
218
219
220       Since 4.05.0
221
222
223
224       exception Help of string
225
226
227       Raised by Arg.parse_argv when the user asks for help.
228
229
230
231       exception Bad of string
232
233
234       Functions  in  spec or anon_fun can raise Arg.Bad with an error message
235       to reject invalid arguments.  Arg.Bad is also raised by  Arg.parse_argv
236       in case of an error.
237
238
239
240       val usage : (key * spec * doc) list -> usage_msg -> unit
241
242
243       Arg.usage  speclist usage_msg prints to standard error an error message
244       that includes the list of valid options.  This is the same message that
245       Arg.parse prints in case of error.  speclist and usage_msg are the same
246       as for Arg.parse .
247
248
249
250       val usage_string : (key * spec * doc) list -> usage_msg -> string
251
252       Returns the message that would have been printed by Arg.usage , if pro‐
253       vided with the same parameters.
254
255
256
257       val align : ?limit:int -> (key * spec * doc) list -> (key * spec * doc)
258       list
259
260       Align the documentation strings by inserting spaces at the first align‐
261       ment  separator  (tab or, if tab is not found, space), according to the
262       length of the keyword.  Use a alignment separator as the first  charac‐
263       ter  in  a  doc  string if you want to align the whole string.  The doc
264       strings corresponding to Symbol arguments are aligned on the next line.
265
266
267
268       val current : int ref
269
270       Position (in Sys.argv ) of  the  argument  being  processed.   You  can
271       change  this  value,  e.g.  to  force Arg.parse to skip some arguments.
272       Arg.parse uses the initial value of Arg.current as the index  of  argu‐
273       ment 0 (the program name) and starts parsing arguments at the next ele‐
274       ment.
275
276
277
278       val read_arg : string -> string array
279
280
281       Arg.read_arg file reads newline-terminated command line arguments  from
282       file file .
283
284
285       Since 4.05.0
286
287
288
289       val read_arg0 : string -> string array
290
291       Identical to Arg.read_arg but assumes null character terminated command
292       line arguments.
293
294
295       Since 4.05.0
296
297
298
299       val write_arg : string -> string array -> unit
300
301
302       Arg.write_arg file args writes the  arguments  args  newline-terminated
303       into  the  file  file  . If the any of the arguments in args contains a
304       newline, use Arg.write_arg0 instead.
305
306
307       Since 4.05.0
308
309
310
311       val write_arg0 : string -> string array -> unit
312
313       Identical to Arg.write_arg but uses the null character  for  terminator
314       instead of newline.
315
316
317       Since 4.05.0
318
319
320
321
322
323OCamldoc                          2021-01-26                            Arg(3)