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
19       arguments 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
26       remaining  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 Pervasives.ref
59         (* Set the reference to true
60        *)
61        | Clear of bool Pervasives.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 Pervasives.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 Pervasives.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 Pervasives.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"; arg
95       ] @ rest where "foo" is registered as Expand f , then the  arguments  f
96       arg @ rest are processed. Only allowed in parse_and_expand_argv_dynamic
97       .
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 Pervasives.ref ->  anon_fun
160       -> usage_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 Pervasives.ref -> string array -> (key  *
176       spec * doc) list -> anon_fun -> usage_msg -> unit
177
178
179       Arg.parse_argv  ~current  args  speclist  anon_fun usage_msg parses the
180       array args as if it were the command line.  It  uses  and  updates  the
181       value  of ~current (if given), or Arg.current .  You must set it before
182       calling parse_argv .  The initial value of current is the index of  the
183       program   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 Pervasives.ref -> string array ->
191       (key * spec * doc) list Pervasives.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 Pervasives.ref -> string  array
202       Pervasives.ref -> (key * spec * doc) list Pervasives.ref -> anon_fun ->
203       string -> unit
204
205       Same as Arg.parse_argv_dynamic , except that the  argv  argument  is  a
206       reference  and  may  be updated during the parsing of Expand arguments.
207       See Arg.parse_argv_dynamic .
208
209
210       Since 4.05.0
211
212
213
214       val parse_expand : (key * spec * doc) list -> anon_fun -> usage_msg  ->
215       unit
216
217       Same  as  Arg.parse  , except that the Expand arguments are allowed and
218       the Arg.current reference is not updated.
219
220
221       Since 4.05.0
222
223
224
225       exception Help of string
226
227
228       Raised by Arg.parse_argv when the user asks for help.
229
230
231
232       exception Bad of string
233
234
235       Functions in spec or anon_fun can raise Arg.Bad with an  error  message
236       to  reject invalid arguments.  Arg.Bad is also raised by Arg.parse_argv
237       in case of an error.
238
239
240
241       val usage : (key * spec * doc) list -> usage_msg -> unit
242
243
244       Arg.usage speclist usage_msg prints to standard error an error  message
245       that includes the list of valid options.  This is the same message that
246       Arg.parse prints in case of error.  speclist and usage_msg are the same
247       as for Arg.parse .
248
249
250
251       val usage_string : (key * spec * doc) list -> usage_msg -> string
252
253       Returns the message that would have been printed by Arg.usage , if pro‐
254       vided with the same parameters.
255
256
257
258       val align : ?limit:int -> (key * spec * doc) list -> (key * spec * doc)
259       list
260
261       Align the documentation strings by inserting spaces at the first align‐
262       ment separator (tab or, if tab is not found, space), according  to  the
263       length  of the keyword.  Use a alignment separator as the first charac‐
264       ter in a doc string if you want to align the  whole  string.   The  doc
265       strings corresponding to Symbol arguments are aligned on the next line.
266
267
268
269       val current : int Pervasives.ref
270
271       Position  (in  Sys.argv  )  of  the  argument being processed.  You can
272       change this value, e.g. to force  Arg.parse  to  skip  some  arguments.
273       Arg.parse  uses  the initial value of Arg.current as the index of argu‐
274       ment 0 (the program name) and starts parsing arguments at the next ele‐
275       ment.
276
277
278
279       val read_arg : string -> string array
280
281
282       Arg.read_arg  file reads newline-terminated command line arguments from
283       file file .
284
285
286       Since 4.05.0
287
288
289
290       val read_arg0 : string -> string array
291
292       Identical to Arg.read_arg but assumes null character terminated command
293       line arguments.
294
295
296       Since 4.05.0
297
298
299
300       val write_arg : string -> string array -> unit
301
302
303       Arg.write_arg  file  args  writes the arguments args newline-terminated
304       into the file file . If the any of the arguments  in  args  contains  a
305       newline, use Arg.write_arg0 instead.
306
307
308       Since 4.05.0
309
310
311
312       val write_arg0 : string -> string array -> unit
313
314       Identical  to  Arg.write_arg but uses the null character for terminator
315       instead of newline.
316
317
318       Since 4.05.0
319
320
321
322
323
324OCamldoc                          2019-02-02                            Arg(3)