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 Alert unsynchronized_access. The Arg module relies on a mutable global
81 state, parsing functions should only be called from a single domain.
82 type spec =
88 | Unit of (unit -> unit)
89 (* Call the function with unit argument
90 *)
91 | Bool of (bool -> unit)
92 (* Call the function with a bool argument
93 *)
94 | Set of bool ref
95 (* Set the reference to true
96 *)
97 | Clear of bool ref
98 (* Set the reference to false
99 *)
100 | String of (string -> unit)
101 (* Call the function with a string argument
102 *)
103 | Set_string of string ref
104 (* Set the reference to the string argument
105 *)
106 | Int of (int -> unit)
107 (* Call the function with an int argument
108 *)
109 | Set_int of int ref
110 (* Set the reference to the int argument
111 *)
112 | Float of (float -> unit)
113 (* Call the function with a float argument
114 *)
115 | Set_float of float ref
116 (* Set the reference to the float argument
117 *)
118 | Tuple of spec list
119 (* Take several arguments according to the spec list
120 *)
121 | Symbol of string list * (string -> unit)
122 (* Take one of the symbols as argument and call the function with the
123 symbol
124 *)
125 | Rest of (string -> unit)
126 (* Stop interpreting keywords and call the function with each remain‐
127 ing argument
128 *)
129 | Rest_all of (string list -> unit)
130 (* Stop interpreting keywords and call the function with all remain‐
131 ing arguments
132 *)
133 | Expand of (string -> string array)
134 (* If the remaining arguments to process are of the form ["-foo";
135 "arg"] @ rest where "foo" is registered as Expand f , then the argu‐
136 ments f "arg" @ rest are processed. Only allowed in parse_and_ex‐
137 pand_argv_dynamic .
138 *)
139 The concrete type describing the behavior associated with a keyword.
142 type key = string
145 type doc = string
150 type usage_msg = string
155 type anon_fun = string -> unit
160 val parse : (key * spec * doc) list -> anon_fun -> usage_msg -> unit
166 Arg.parse speclist anon_fun usage_msg parses the command line.
169 speclist is a list of triples (key, spec, doc) . key is the option
170 keyword, it must start with a '-' character. spec gives the option
171 type and the function to call when this option is found on the command
172 line. doc is a one-line description of this option. anon_fun is
173 called on anonymous arguments. The functions in spec and anon_fun are
174 called in the same order as their arguments appear on the command line.
175 If an error occurs, Arg.parse exits the program, after printing to
177 standard error an error message as follows:
178 - The reason for the error: unknown option, invalid or missing argu‐
180 ment, etc.
181 - usage_msg
183 - The list of options, each followed by the corresponding doc string.
186 Beware: options that have an empty doc string will not be included in
187 the list.
188 For the user to be able to specify anonymous arguments starting with a
190 - , include for example ("-", String anon_fun, doc) in speclist .
191 By default, parse recognizes two unit options, -help and --help , which
193 will print to standard output usage_msg and the list of options, and
194 exit the program. You can override this behaviour by specifying your
195 own -help and --help options in speclist .
196 val parse_dynamic : (key * spec * doc) list ref -> anon_fun -> us‐
200 age_msg -> unit
201 Same as Arg.parse , except that the speclist argument is a reference
203 and may be updated during the parsing. A typical use for this feature
204 is to parse command lines of the form:
205 - command subcommand options where the list of options depends on
207 the value of the subcommand argument.
208 Since 4.01.0
212 val parse_argv : ?current:int ref -> string array -> (key * spec * doc)
216 list -> anon_fun -> usage_msg -> unit
217 Arg.parse_argv ~current args speclist anon_fun usage_msg parses the ar‐
220 ray args as if it were the command line. It uses and updates the value
221 of ~current (if given), or Arg.current . You must set it before call‐
222 ing parse_argv . The initial value of current is the index of the pro‐
223 gram name (argument 0) in the array. If an error occurs,
224 Arg.parse_argv raises Arg.Bad with the error message as argument. If
225 option -help or --help is given, Arg.parse_argv raises Arg.Help with
226 the help message as argument.
227 val parse_argv_dynamic : ?current:int ref -> string array -> (key *
231 spec * doc) list ref -> anon_fun -> string -> unit
232 Same as Arg.parse_argv , except that the speclist argument is a refer‐
234 ence and may be updated during the parsing. See Arg.parse_dynamic .
235 Since 4.01.0
238 val parse_and_expand_argv_dynamic : int ref -> string array ref -> (key
242 * spec * doc) list ref -> anon_fun -> string -> unit
243 Same as Arg.parse_argv_dynamic , except that the argv argument is a
245 reference and may be updated during the parsing of Expand arguments.
246 See Arg.parse_argv_dynamic .
247 Since 4.05.0
250 val parse_expand : (key * spec * doc) list -> anon_fun -> usage_msg ->
254 unit
255 Same as Arg.parse , except that the Expand arguments are allowed and
257 the Arg.current reference is not updated.
258 Since 4.05.0
261 exception Help of string
265 Raised by Arg.parse_argv when the user asks for help.
268 exception Bad of string
272 Functions in spec or anon_fun can raise Arg.Bad with an error message
275 to reject invalid arguments. Arg.Bad is also raised by Arg.parse_argv
276 in case of an error.
277 val usage : (key * spec * doc) list -> usage_msg -> unit
281 Arg.usage speclist usage_msg prints to standard error an error message
284 that includes the list of valid options. This is the same message that
285 Arg.parse prints in case of error. speclist and usage_msg are the same
286 as for Arg.parse .
287 val usage_string : (key * spec * doc) list -> usage_msg -> string
291 Returns the message that would have been printed by Arg.usage , if pro‐
293 vided with the same parameters.
294 val align : ?limit:int -> (key * spec * doc) list -> (key * spec * doc)
298 list
299 Align the documentation strings by inserting spaces at the first align‐
301 ment separator (tab or, if tab is not found, space), according to the
302 length of the keyword. Use a alignment separator as the first charac‐
303 ter in a doc string if you want to align the whole string. The doc
304 strings corresponding to Symbol arguments are aligned on the next line.
305 val current : int ref
309 Position (in Sys.argv ) of the argument being processed. You can
311 change this value, e.g. to force Arg.parse to skip some arguments.
312 Arg.parse uses the initial value of Arg.current as the index of argu‐
313 ment 0 (the program name) and starts parsing arguments at the next ele‐
314 ment.
315 val read_arg : string -> string array
319 Arg.read_arg file reads newline-terminated command line arguments from
322 file file .
323 Since 4.05.0
326 val read_arg0 : string -> string array
330 Identical to Arg.read_arg but assumes null character terminated command
332 line arguments.
333 Since 4.05.0
336 val write_arg : string -> string array -> unit
340 Arg.write_arg file args writes the arguments args newline-terminated
343 into the file file . If the any of the arguments in args contains a
344 newline, use Arg.write_arg0 instead.
345 Since 4.05.0
348 val write_arg0 : string -> string array -> unit
352 Identical to Arg.write_arg but uses the null character for terminator
354 instead of newline.
355 Since 4.05.0
358OCamldoc 2023-07-20 Arg(3)