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