1Arg(3) OCaml library Arg(3)
2
3
4
6 Arg - Parsing of command line arguments.
7
9 Module Arg
10
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 2021-07-22 Arg(3)