src/utils/cdk/arg2.mli

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