1Arg(3) OCaml library Arg(3)
2
6 Arg - Parsing of command line arguments.
7
9 Module Arg
10
12 Module Arg
13 : sig end
14 Parsing of command line arguments.
17 This module provides a general mechanism for extracting options and ar‐
19 guments from the command line to the program. For example:
20 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 let anon_fun filename =
28 input_files := filename::!input_files
29 let speclist =
31 [("-verbose", Arg.Set verbose, "Output debug information");
32 ("-o", Arg.Set_string output_file, "Set output file name")]
33 let () =
35 Arg.parse speclist anon_fun usage_msg;
36 (* Main functionality here *)
37 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 Unit , Set and Clear keywords take no argument.
47 A Rest or Rest_all keyword takes the remainder of the command line as
49 arguments. (More explanations below.)
50 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 Examples ( cmd is assumed to be the command name):
57 - cmd -flag (a unit option)
59 - cmd -int 1 (an int option with argument 1 )
61 - cmd -string foobar (a string option with argument "foobar" )
63 - cmd -float 12.34 (a float option with argument 12.34 )
65 - cmd a b c (three anonymous arguments: "a" , "b" , and "c" )
67 - cmd a b -- c d (two anonymous arguments and a rest option with two
69 arguments)
70 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 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 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 The concrete type describing the behavior associated with a keyword.
138 type key = string
141 type doc = string
146 type usage_msg = string
151 type anon_fun = string -> unit
156 val parse : (key * spec * doc) list -> anon_fun -> usage_msg -> unit
162 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 If an error occurs, Arg.parse exits the program, after printing to
173 standard error an error message as follows:
174 - The reason for the error: unknown option, invalid or missing argu‐
176 ment, etc.
177 - usage_msg
179 - 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 For the user to be able to specify anonymous arguments starting with a
186 - , include for example ("-", String anon_fun, doc) in speclist .
187 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 val parse_dynamic : (key * spec * doc) list ref -> anon_fun -> us‐
196 age_msg -> unit
197 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 - command subcommand options where the list of options depends on
203 the value of the subcommand argument.
204 Since 4.01.0
208 val parse_argv : ?current:int ref -> string array -> (key * spec * doc)
212 list -> anon_fun -> usage_msg -> unit
213 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 val parse_argv_dynamic : ?current:int ref -> string array -> (key *
227 spec * doc) list ref -> anon_fun -> string -> unit
228 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 Since 4.01.0
234 val parse_and_expand_argv_dynamic : int ref -> string array ref -> (key
238 * spec * doc) list ref -> anon_fun -> string -> unit
239 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 Since 4.05.0
246 val parse_expand : (key * spec * doc) list -> anon_fun -> usage_msg ->
250 unit
251 Same as Arg.parse , except that the Expand arguments are allowed and
253 the Arg.current reference is not updated.
254 Since 4.05.0
257 exception Help of string
261 Raised by Arg.parse_argv when the user asks for help.
264 exception Bad of string
268 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 val usage : (key * spec * doc) list -> usage_msg -> unit
277 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 val usage_string : (key * spec * doc) list -> usage_msg -> string
287 Returns the message that would have been printed by Arg.usage , if pro‐
289 vided with the same parameters.
290 val align : ?limit:int -> (key * spec * doc) list -> (key * spec * doc)
294 list
295 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 val current : int ref
305 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 val read_arg : string -> string array
315 Arg.read_arg file reads newline-terminated command line arguments from
318 file file .
319 Since 4.05.0
322 val read_arg0 : string -> string array
326 Identical to Arg.read_arg but assumes null character terminated command
328 line arguments.
329 Since 4.05.0
332 val write_arg : string -> string array -> unit
336 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 Since 4.05.0
344 val write_arg0 : string -> string array -> unit
348 Identical to Arg.write_arg but uses the null character for terminator
350 instead of newline.
351 Since 4.05.0
354OCamldoc 2023-01-23 Arg(3)