uarg.mli (4694B)
1 (***********************************************************************) 2 (* *) 3 (* Objective Caml *) 4 (* *) 5 (* Xavier Leroy, projet Cristal, INRIA Rocquencourt *) 6 (* *) 7 (* Copyright 1996 Institut National de Recherche en Informatique et *) 8 (* Automatique. Distributed only by permission. *) 9 (* *) 10 (***********************************************************************) 11 (* Slightly modified version by BCP for Unison in 1999 and 2008 *) 12 13 (* Module [Uarg]: parsing of command line arguments *) 14 15 (* This module provides a general mechanism for extracting options and 16 arguments from the command line to the program. 17 *) 18 19 (* Syntax of command lines: 20 A keyword is a character string starting with a [-]. 21 An option is a keyword alone or followed by an argument. 22 The types of keywords are: [Unit], [Set], [Clear], [String], 23 [Int], [Float], and [Rest]. [Unit], [Set] and [Clear] keywords take 24 no argument. [String], [Int], and [Float] keywords take the following 25 word on the command line as an argument. A [Rest] keyword takes the 26 remaining of the command line as (string) arguments. 27 Arguments not preceded by a keyword are called anonymous arguments. 28 *) 29 30 (* Examples ([cmd] is assumed to be the command name): 31 - [cmd -flag ](a unit option) 32 - [cmd -int 1 ](an int option with argument [1]) 33 - [cmd -string foobar ](a string option with argument ["foobar"]) 34 - [cmd -float 12.34 ](a float option with argument [12.34]) 35 - [cmd a b c ](three anonymous arguments: ["a"], ["b"], and ["c"]) 36 - [cmd a b -- c d ](two anonymous arguments and a rest option with 37 - [ ] two arguments) 38 *) 39 40 type spec = 41 | Unit of (unit -> unit) (* Call the function with unit argument *) 42 | Set of bool ref (* Set the reference to true *) 43 | Clear of bool ref (* Set the reference to false *) 44 | Bool of (bool -> unit) (* Pass true to the function *) 45 | String of (string -> unit) (* Call the function with a string argument *) 46 | Int of (int -> unit) (* Call the function with an int argument *) 47 | Float of (float -> unit) (* Call the function with a float argument *) 48 | Rest of (string -> unit) (* Stop interpreting keywords and call the 49 function with each remaining argument *) 50 (* The concrete type describing the behavior associated 51 with a keyword. *) 52 53 val parse : (string * spec * string) list -> (string -> unit) -> string -> unit 54 (* 55 [Uarg.parse speclist anonfun usage_msg] parses the command line. 56 [speclist] is a list of triples [(key, spec, doc)]. 57 [key] is the option keyword, it must start with a ['-'] character. 58 [spec] gives the option type and the function to call when this option 59 is found on the command line. 60 [doc] is a one-line description of this option. 61 [anonfun] is called on anonymous arguments. 62 The functions in [spec] and [anonfun] are called in the same order 63 as their arguments appear on the command line. 64 65 If an error occurs, [Uarg.parse] exits the program, after printing 66 an error message as follows: 67 - The reason for the error: unknown option, invalid or missing argument, etc. 68 - [usage_msg] 69 - The list of options, each followed by the corresponding [doc] string. 70 71 For the user to be able to specify anonymous arguments starting with a 72 [-], include for example [("-", String anonfun, doc)] in [speclist]. 73 74 By default, [parse] recognizes a unit option [-help], which will 75 display [usage_msg] and the list of options, and exit the program. 76 You can override this behaviour by specifying your own [-help] 77 option in [speclist]. 78 *) 79 80 exception Bad of string 81 (* 82 Functions in [spec] or [anonfun] can raise [Uarg.Bad] with an error 83 message to reject invalid arguments. 84 *) 85 86 val usage: (string * spec * string) list -> string -> unit 87 (* 88 [Uarg.usage speclist usage_msg] prints an error message including 89 the list of valid options. This is the same message that 90 [Uarg.parse] prints in case of error. 91 [speclist] and [usage_msg] are the same as for [Uarg.parse]. 92 *) 93 94 val current: int ref;; 95 (* 96 Position (in [Sys.argv]) of the argument being processed. You can 97 change this value, e.g. to force [Uarg.parse] to skip some arguments. 98 *)