Commit | Line | Data |
---|---|---|
feec80c3 C |
1 | (* |
2 | * optParse - Functions for parsing command line arguments. | |
3 | * Copyright (C) 2004 Bardur Arantsson | |
4 | * | |
5 | * Heavily influenced by the optparse.py module from the Python | |
6 | * standard library, but with lots of adaptation to the 'Ocaml Way' | |
7 | * | |
8 | * | |
9 | * This library is free software; you can redistribute it and/or | |
10 | * modify it under the terms of the GNU Lesser General Public | |
11 | * License as published by the Free Software Foundation; either | |
12 | * version 2.1 of the License, or (at your option) any later version, | |
13 | * with the special exception on linking described in file LICENSE. | |
14 | * | |
15 | * This library is distributed in the hope that it will be useful, | |
16 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
18 | * Lesser General Public License for more details. | |
19 | * | |
20 | * You should have received a copy of the GNU Lesser General Public | |
21 | * License along with this library; if not, write to the Free Software | |
22 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
23 | *) | |
24 | ||
25 | (** Modules for GNU [getopt(3)]-style command line parsing. *) | |
26 | ||
27 | ||
28 | (** This module contains the basic functions and types for defining | |
29 | new option types and accessing the values of options. *) | |
30 | module Opt : | |
31 | sig | |
32 | ||
33 | (** {6 Exceptions} *) | |
34 | ||
35 | exception No_value | |
36 | (** [No_value] gets raised by {!OptParse.Opt.get} when an option | |
37 | value is not available. *) | |
38 | ||
39 | exception Option_error of string * string | |
40 | (** This exception signals that an option value is invalid. The | |
41 | first string contains the option string ('-x' or '--long-name') | |
42 | and the second string contains an error message. | |
43 | ||
44 | This exception is only used when implementing custom option types | |
45 | and can never "escape" the scope of a {!OptParse.OptParser.parse}. | |
46 | The user should therefore not attempt to catch it. *) | |
47 | ||
48 | exception Option_help | |
49 | (** When an option wants to display a usage message, this exception | |
50 | may be raised. It can never "escape" the scope of a | |
51 | {!OptParse.OptParser.parse} call and the user should therefore not | |
52 | attempt to catch it. *) | |
53 | ||
54 | ||
55 | (** {6 Types} *) | |
56 | ||
57 | type 'a t = { | |
58 | option_set : string -> string list -> unit; | |
59 | option_set_value : 'a -> unit; | |
60 | option_get : unit -> 'a option; | |
61 | option_metavars : string list; | |
62 | option_defhelp : string option | |
63 | } | |
64 | (** Option type. | |
65 | ||
66 | [option_set] is a closure which converts and records the value of | |
67 | an option so that it can be retrieved with a later call to the | |
68 | [option_get] closure. It is called with the option name which was | |
69 | given on the command line and a list of strings, each representing | |
70 | one of the argument values given on the command line. It may raise | |
71 | [Option_error] if the value is invalid (for whatever reason). | |
72 | ||
73 | [option_set_value] is a closure which sets the value of an option | |
74 | to a particular value. | |
75 | ||
76 | [option_get] is a closure which retrieves the recorded value | |
77 | of the option. If the option value has not been set from the | |
78 | command line, the default value is used. If there is no default | |
79 | value, then [None] should be returned. | |
80 | ||
81 | [option_metavars] is a list of "meta-variables" (arguments) | |
82 | which this option accepts. This is mainly for display purposes, | |
83 | but the length of this list determines how many arguments the | |
84 | option parser accepts for this option (currently only lists of | |
85 | length 0 or 1 are supported). | |
86 | ||
87 | [option_defhelp] is the default help string (if any). It is | |
88 | used for displaying help messages whenever the user does {b | |
89 | not} specify a help string manually when adding this | |
90 | option. Using a non-None value here only makes sense for | |
91 | completely generic options like {!OptParse.StdOpt.help_option}. | |
92 | ||
93 | *) | |
94 | ||
95 | ||
96 | (** {6 Option value retrieval} *) | |
97 | ||
98 | val get : 'a t -> 'a | |
99 | (** Get the value of an option. | |
100 | ||
101 | @return the value of the option. If the option has not been | |
102 | encountered while parsing the command line, the default value is | |
103 | returned. | |
104 | ||
105 | @raise No_value if no default values has been given | |
106 | and the option value has not been set from the command line. | |
107 | ||
108 | *) | |
109 | ||
110 | val set : 'a t -> 'a -> unit | |
111 | (** Set the value of an option. *) | |
112 | ||
113 | val opt : 'a t -> 'a option | |
114 | (** Get the value of an option as an optional value. | |
115 | ||
116 | @return [Some x] if the option has value [x] (either by default or | |
117 | from the command line). If the option doesn't have a value [None] | |
118 | is returned. *) | |
119 | ||
120 | val is_set : 'a t -> bool | |
121 | (** Find out if the option has a value (either by default or | |
122 | from the command line). | |
123 | ||
124 | @return [True] iff the option has a value. | |
125 | *) | |
126 | ||
127 | ||
128 | ||
129 | (** {6 Option creation} *) | |
130 | ||
131 | val value_option : | |
132 | string -> 'a option -> (string -> 'a) -> (exn -> string -> string) -> | |
133 | 'a t | |
134 | (** Make an option which takes a single argument. | |
135 | ||
136 | [value_option metavar default coerce errfmt] returns an option | |
137 | which takes a single argument from the command line and calls | |
138 | [coerce] to coerce it to the proper type. If [coerce] raises an | |
139 | exception, [exn], then [errfmt exn argval] is called to generate | |
140 | an error message for display. [metavar] is the name of the | |
141 | metavariable of the option. | |
142 | ||
143 | [default] is the default value of the option. If [None], the the | |
144 | option has no default value. | |
145 | ||
146 | @return the newly created option. | |
147 | ||
148 | *) | |
149 | ||
150 | val callback_option : | |
151 | string -> (string -> 'a) -> (exn -> string -> string) -> ('a -> unit) -> | |
152 | unit t | |
153 | (** Make a callback option which takes a single argument. | |
154 | ||
155 | [callback_option metavar coerce errfmt f] returns an option which | |
156 | takes a single argument from the command line and calls [coerce] | |
157 | to coerce it to the proper type. If [coerce] raises an exception | |
158 | [errfmt exn argval] is called to format an error message for | |
159 | display. If [coerce] succeeds, the callback function [f] is called | |
160 | with the coerced value. Finally, [metavar] is the name of the | |
161 | metavariable of the option. | |
162 | ||
163 | @return the newly created option. | |
164 | *) | |
165 | ||
166 | ||
167 | end | |
168 | ||
169 | ||
170 | (** This module contains various standard options. *) | |
171 | module StdOpt : | |
172 | sig | |
173 | ||
174 | (** {6 Flag options} *) | |
175 | ||
176 | val store_const : ?default: 'a -> 'a -> 'a Opt.t | |
177 | (** [store_const ?default const] returns a flag option which | |
178 | stores the constant value [const] when the option is | |
179 | encountered on the command line. *) | |
180 | ||
181 | val store_true : unit -> bool Opt.t | |
182 | (** [store_true ()] returns an option which is set to true when | |
183 | it is encountered on the command line. The default value is | |
184 | false. *) | |
185 | ||
186 | val store_false : unit -> bool Opt.t | |
187 | (** [store_false ()] returns an option which is set to false when | |
188 | it is encountered on the command line. The default value is | |
189 | true. *) | |
190 | ||
191 | val count_option : ?dest: int ref -> ?increment: int -> unit -> int Opt.t | |
192 | (** Create a counting option which increments its value each time the | |
193 | option is encountered on the command line. | |
194 | ||
195 | @param increment Increment to add to the option value each | |
196 | time the option is encountered. | |
197 | ||
198 | @param dest Reference to the option value. Useful for making | |
199 | options like '--quiet' and '--verbose' sharing a single value. | |
200 | ||
201 | @return the newly created option. | |
202 | *) | |
203 | ||
204 | val incr_option : ?dest: int ref -> unit -> int Opt.t | |
205 | (** Exactly identical to [count_option ~dest:dest ~increment:1 ()]. *) | |
206 | ||
207 | val decr_option : ?dest: int ref -> unit -> int Opt.t | |
208 | (** Exactly identical to [count_option ~dest:dest ~increment:(-1) ()]. *) | |
209 | ||
210 | ||
211 | (** {6 Value options} *) | |
212 | ||
213 | val int_option : ?default: int -> ?metavar: string -> unit -> int Opt.t | |
214 | (** [int_option ?default ?metavar ()] returns an option which takes | |
215 | a single integer argument. If [~default] is given it is the | |
216 | default value returned when the option has not been encountered | |
217 | on the command line. *) | |
218 | ||
219 | val float_option : | |
220 | ?default: float -> ?metavar: string -> unit -> float Opt.t | |
221 | (** See {!OptParse.StdOpt.int_option}. *) | |
222 | ||
223 | val str_option : | |
224 | ?default: string -> ?metavar: string -> unit -> string Opt.t | |
225 | (** See {!OptParse.StdOpt.int_option}. *) | |
226 | ||
227 | ||
228 | (** {6 Callback options} *) | |
229 | ||
230 | val int_callback : ?metavar: string -> (int -> unit) -> unit Opt.t | |
231 | (** [int_callback ?metavar f] returns an option which takes a single | |
232 | integer argument and calls [f] with that argument when encountered | |
233 | on the command line. *) | |
234 | ||
235 | val float_callback : ?metavar: string -> (float -> unit) -> unit Opt.t | |
236 | (** See {!OptParse.StdOpt.int_callback}. *) | |
237 | ||
238 | val str_callback : ?metavar: string -> (string -> unit) -> unit Opt.t | |
239 | (** See {!OptParse.StdOpt.int_callback}. *) | |
240 | ||
241 | ||
242 | (** {6 Special options} *) | |
243 | ||
244 | val help_option : unit -> 'a Opt.t | |
245 | (** [help_option ()] returns the standard help option which | |
246 | displays a usage message and exits the program when encountered | |
247 | on the command line. *) | |
248 | ||
249 | val version_option : (unit -> string) -> 'a Opt.t | |
250 | (** [version_option f] returns the standard version option which | |
251 | displays the string returned by [f ()] (and nothing else) on | |
252 | standard output and exits. *) | |
253 | ||
254 | end | |
255 | ||
256 | ||
257 | (** This module contains the types and functions for implementing | |
258 | custom usage message formatters. *) | |
259 | module Formatter : | |
260 | sig | |
261 | type t = { | |
262 | indent : unit -> unit; (** Increase the indentation level. *) | |
263 | dedent : unit -> unit; (** Decrease the indentation level. *) | |
264 | format_usage : string -> string; (** Format usage string into style of this formatter. *) | |
265 | format_heading : string -> string; (** Format heading into style of this formatter. *) | |
266 | format_description : string -> string; (** Format description into style of this formatter. *) | |
267 | format_option : | |
268 | char list * string list -> string list -> string option -> string (** Format option into style of this formatter (see explanation below). *) | |
269 | } | |
270 | ||
271 | (** This is the type of a formatter. The [format_option] has | |
272 | signature [format_option (snames,lnames) metavars help], where | |
273 | [snames] is a list of the short option names, [lnames] is a | |
274 | list of the long option names, [metavars] is a list of the | |
275 | metavars the option takes as arguments, and [help] is the help | |
276 | string supplied by the user. *) | |
277 | ||
278 | ||
279 | (** {6 Standard formatters} *) | |
280 | ||
281 | ||
282 | val indented_formatter : | |
283 | ?level: int ref -> ?indent: int ref -> ?indent_increment: int -> | |
284 | ?max_help_position: int -> ?width: int -> ?short_first: bool -> | |
285 | unit -> t | |
286 | (** Create an "indented" formatter with the given options. | |
287 | ||
288 | @param width Total with of the usage messages printed. | |
289 | ||
290 | @param max_help_position Maximum starting column for the help | |
291 | messages relating to each option. | |
292 | ||
293 | @param short_first List all the short option names first? | |
294 | ||
295 | @param indent_increment Number of columns to indent by when | |
296 | more indentation is required. | |
297 | ||
298 | @param indent Reference to the current indentation amount. Its | |
299 | value reflects changes in indentation level. | |
300 | ||
301 | @param level Reference to the current indentation level. Its | |
302 | value reflects changes in indentation level. *) | |
303 | ||
304 | val titled_formatter : ?level: int ref -> ?indent: int ref -> | |
305 | ?indent_increment: int -> ?max_help_position: int -> | |
306 | ?width: int -> ?short_first: bool -> unit -> t | |
307 | (** Creates a titled formatter which is quite similar to the | |
308 | indented formatter. See | |
309 | {!OptParse.Formatter.indented_formatter} for a description of | |
310 | the options. *) | |
311 | ||
312 | ||
313 | (** {6 Low-level formatting} *) | |
314 | ||
315 | ||
316 | val wrap : ?initial_indent: int -> ?subsequent_indent: int -> | |
317 | string -> int -> string list | |
318 | (** [wrap text width] reflows the given text paragraph into lines | |
319 | of width at most [width] (lines may exceed this if the are | |
320 | single words that exceed this limit). | |
321 | ||
322 | @param initial_indent Indentation of the first line. | |
323 | ||
324 | @param subsequent_indent Indentation of the following lines. | |
325 | ||
326 | @return a list of lines making up the reformatted paragraph. *) | |
327 | ||
328 | val fill : ?initial_indent: int -> ?subsequent_indent: int -> | |
329 | string -> int -> string | |
330 | (** See {!OptParse.Formatter.wrap}. | |
331 | ||
332 | @return a string containing the reformatted paragraph. *) | |
333 | ||
334 | end | |
335 | ||
336 | ||
337 | ||
338 | (** This module contains the option parser itself. | |
339 | ||
340 | It provides functions to create, populate and use option parsers to | |
341 | parse command line arguments. *) | |
342 | module OptParser : | |
343 | sig | |
344 | ||
345 | (** {6 Exceptions} *) | |
346 | ||
347 | ||
348 | exception Option_conflict of string | |
349 | (** [Option_conflict name] is raised by {!OptParse.OptParser.add} | |
350 | when two different options are added with identical | |
351 | names. Usually this doesn't need to be caught since this error | |
352 | is usually easily fixed permanently by removing/renaming the | |
353 | conflicting option names. *) | |
354 | ||
355 | ||
356 | (** {6 Types} *) | |
357 | ||
358 | ||
359 | type t | |
360 | (** The type of an option parser. *) | |
361 | ||
362 | type group | |
363 | (** The type of an option group. *) | |
364 | ||
365 | ||
366 | (** {6 Option parser creation} *) | |
367 | ||
368 | val make : ?usage: string -> ?description: string -> ?version: string -> | |
369 | ?suppress_usage: bool -> ?suppress_help: bool -> ?prog: string -> | |
370 | ?formatter: Formatter.t -> unit -> t | |
371 | (** Creates a new option parser with the given options. | |
372 | ||
373 | @param usage Usage message. The default is a reasonable usage | |
374 | message for most programs. Any occurrence of the substring | |
375 | ["%prog"] in [usage] is replaced with the name of the program | |
376 | (see [prog]). | |
377 | ||
378 | @param prog Program name. The default is the base name of the | |
379 | executable. | |
380 | ||
381 | @param suppress_usage Suppress the usage message if set. | |
382 | ||
383 | @param suppress_help Suppress the 'help' option which is | |
384 | otherwise added by default. | |
385 | ||
386 | @param version Version string. If set, a '--version' option is | |
387 | automatically added. When encountered on the command line it | |
388 | causes [version] to be printed to the standard output and the | |
389 | program to exit. | |
390 | ||
391 | @param description: description of the main purpose of the | |
392 | program. | |
393 | ||
394 | @return the new option parser. | |
395 | ||
396 | *) | |
397 | ||
398 | ||
399 | val add : t -> ?group: group -> ?help: string -> ?hide: bool -> | |
400 | ?short_name: char -> ?short_names: char list -> ?long_name: string -> | |
401 | ?long_names: string list -> 'a Opt.t -> unit | |
402 | (** Add an option to the option parser. | |
403 | ||
404 | @raise Option_conflict if the short name(s) or long name(s) | |
405 | have alread been used for some other option. | |
406 | ||
407 | @param help Short help message describing the option (for the usage message). | |
408 | ||
409 | @param hide If true, hide the option from the usage | |
410 | message. This can be used to implement "secret" options which | |
411 | are not shown, but work just the same as regular options in all | |
412 | other respects. | |
413 | ||
414 | @param short_name is the name for the short form of the option | |
415 | (e.g. ['x'] means that the option is invoked with [-x] on the | |
416 | command line). | |
417 | ||
418 | @param short_names is a list of names for the short form of the | |
419 | option (see [short_name]). | |
420 | ||
421 | @param long_name is the name for the long form of the option | |
422 | (e.g. ["xyzzy"] means that the option is invoked with [--xyzzy] | |
423 | on the command line). | |
424 | ||
425 | @param long_names is a list of names for the long form of the | |
426 | option (see [long_name]). | |
427 | *) | |
428 | ||
429 | ||
430 | val add_group : t -> ?parent: group -> ?description: string -> | |
431 | string -> group | |
432 | (** Add a group to the option parser. | |
433 | ||
434 | @param parent is the parent group (if any). | |
435 | ||
436 | @param description is a description of the group. | |
437 | ||
438 | @return the new group. | |
439 | ||
440 | *) | |
441 | ||
442 | (** {6 Output and error handling} *) | |
443 | ||
444 | val error : t -> ?chn: out_channel -> ?status: int -> string -> unit | |
445 | (** Display an error message and exit the program. The error | |
446 | message is printed to the channel [chn] (default is | |
447 | [Pervasives.stderr]) and the program exits with exit status | |
448 | [status] (default is 1). *) | |
449 | ||
450 | val usage : t -> ?chn: out_channel -> unit -> unit | |
451 | (** Display the usage message to the channel [chn] (default is | |
452 | [Pervasives.stdout]) and return. *) | |
453 | ||
454 | ||
455 | (** {6 Option parsing} *) | |
456 | ||
457 | val parse : t -> ?first: int -> ?last: int -> string array -> string list | |
458 | (** Parse arguments as if the arguments [args.(first)], | |
459 | [args.(first+1)], ..., [args.(last)] had been given on the | |
460 | command line. By default [first] is 0 and [last] is the index | |
461 | of the last element of the array. *) | |
462 | ||
463 | val parse_argv : t -> string list | |
464 | (** Parse all the arguments in [Sys.argv]. *) | |
465 | ||
466 | end |