(*
* optParse - Functions for parsing command line arguments.
* Copyright (C) 2004 Bardur Arantsson
*
* Heavily influenced by the optparse.py module from the Python
* standard library, but with lots of adaptation to the 'Ocaml Way'
*
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version,
* with the special exception on linking described in file LICENSE.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*)
(** Modules for GNU [getopt(3)]-style command line parsing. *)
(** This module contains the basic functions and types for defining
new option types and accessing the values of options. *)
module Opt :
sig
(** {6 Exceptions} *)
exception No_value
(** [No_value] gets raised by {!OptParse.Opt.get} when an option
value is not available. *)
exception Option_error of string * string
(** This exception signals that an option value is invalid. The
first string contains the option string ('-x' or '--long-name')
and the second string contains an error message.
This exception is only used when implementing custom option types
and can never "escape" the scope of a {!OptParse.OptParser.parse}.
The user should therefore not attempt to catch it. *)
exception Option_help
(** When an option wants to display a usage message, this exception
may be raised. It can never "escape" the scope of a
{!OptParse.OptParser.parse} call and the user should therefore not
attempt to catch it. *)
(** {6 Types} *)
type 'a t = {
option_set : string -> string list -> unit;
option_set_value : 'a -> unit;
option_get : unit -> 'a option;
option_metavars : string list;
option_defhelp : string option
}
(** Option type.
[option_set] is a closure which converts and records the value of
an option so that it can be retrieved with a later call to the
[option_get] closure. It is called with the option name which was
given on the command line and a list of strings, each representing
one of the argument values given on the command line. It may raise
[Option_error] if the value is invalid (for whatever reason).
[option_set_value] is a closure which sets the value of an option
to a particular value.
[option_get] is a closure which retrieves the recorded value
of the option. If the option value has not been set from the
command line, the default value is used. If there is no default
value, then [None] should be returned.
[option_metavars] is a list of "meta-variables" (arguments)
which this option accepts. This is mainly for display purposes,
but the length of this list determines how many arguments the
option parser accepts for this option (currently only lists of
length 0 or 1 are supported).
[option_defhelp] is the default help string (if any). It is
used for displaying help messages whenever the user does {b
not} specify a help string manually when adding this
option. Using a non-None value here only makes sense for
completely generic options like {!OptParse.StdOpt.help_option}.
*)
(** {6 Option value retrieval} *)
val get : 'a t -> 'a
(** Get the value of an option.
@return the value of the option. If the option has not been
encountered while parsing the command line, the default value is
returned.
@raise No_value if no default values has been given
and the option value has not been set from the command line.
*)
val set : 'a t -> 'a -> unit
(** Set the value of an option. *)
val opt : 'a t -> 'a option
(** Get the value of an option as an optional value.
@return [Some x] if the option has value [x] (either by default or
from the command line). If the option doesn't have a value [None]
is returned. *)
val is_set : 'a t -> bool
(** Find out if the option has a value (either by default or
from the command line).
@return [True] iff the option has a value.
*)
(** {6 Option creation} *)
val value_option :
string -> 'a option -> (string -> 'a) -> (exn -> string -> string) ->
'a t
(** Make an option which takes a single argument.
[value_option metavar default coerce errfmt] returns an option
which takes a single argument from the command line and calls
[coerce] to coerce it to the proper type. If [coerce] raises an
exception, [exn], then [errfmt exn argval] is called to generate
an error message for display. [metavar] is the name of the
metavariable of the option.
[default] is the default value of the option. If [None], the the
option has no default value.
@return the newly created option.
*)
val callback_option :
string -> (string -> 'a) -> (exn -> string -> string) -> ('a -> unit) ->
unit t
(** Make a callback option which takes a single argument.
[callback_option metavar coerce errfmt f] returns an option which
takes a single argument from the command line and calls [coerce]
to coerce it to the proper type. If [coerce] raises an exception
[errfmt exn argval] is called to format an error message for
display. If [coerce] succeeds, the callback function [f] is called
with the coerced value. Finally, [metavar] is the name of the
metavariable of the option.
@return the newly created option.
*)
end
(** This module contains various standard options. *)
module StdOpt :
sig
(** {6 Flag options} *)
val store_const : ?default: 'a -> 'a -> 'a Opt.t
(** [store_const ?default const] returns a flag option which
stores the constant value [const] when the option is
encountered on the command line. *)
val store_true : unit -> bool Opt.t
(** [store_true ()] returns an option which is set to true when
it is encountered on the command line. The default value is
false. *)
val store_false : unit -> bool Opt.t
(** [store_false ()] returns an option which is set to false when
it is encountered on the command line. The default value is
true. *)
val count_option : ?dest: int ref -> ?increment: int -> unit -> int Opt.t
(** Create a counting option which increments its value each time the
option is encountered on the command line.
@param increment Increment to add to the option value each
time the option is encountered.
@param dest Reference to the option value. Useful for making
options like '--quiet' and '--verbose' sharing a single value.
@return the newly created option.
*)
val incr_option : ?dest: int ref -> unit -> int Opt.t
(** Exactly identical to [count_option ~dest:dest ~increment:1 ()]. *)
val decr_option : ?dest: int ref -> unit -> int Opt.t
(** Exactly identical to [count_option ~dest:dest ~increment:(-1) ()]. *)
(** {6 Value options} *)
val int_option : ?default: int -> ?metavar: string -> unit -> int Opt.t
(** [int_option ?default ?metavar ()] returns an option which takes
a single integer argument. If [~default] is given it is the
default value returned when the option has not been encountered
on the command line. *)
val float_option :
?default: float -> ?metavar: string -> unit -> float Opt.t
(** See {!OptParse.StdOpt.int_option}. *)
val str_option :
?default: string -> ?metavar: string -> unit -> string Opt.t
(** See {!OptParse.StdOpt.int_option}. *)
(** {6 Callback options} *)
val int_callback : ?metavar: string -> (int -> unit) -> unit Opt.t
(** [int_callback ?metavar f] returns an option which takes a single
integer argument and calls [f] with that argument when encountered
on the command line. *)
val float_callback : ?metavar: string -> (float -> unit) -> unit Opt.t
(** See {!OptParse.StdOpt.int_callback}. *)
val str_callback : ?metavar: string -> (string -> unit) -> unit Opt.t
(** See {!OptParse.StdOpt.int_callback}. *)
(** {6 Special options} *)
val help_option : unit -> 'a Opt.t
(** [help_option ()] returns the standard help option which
displays a usage message and exits the program when encountered
on the command line. *)
val version_option : (unit -> string) -> 'a Opt.t
(** [version_option f] returns the standard version option which
displays the string returned by [f ()] (and nothing else) on
standard output and exits. *)
end
(** This module contains the types and functions for implementing
custom usage message formatters. *)
module Formatter :
sig
type t = {
indent : unit -> unit; (** Increase the indentation level. *)
dedent : unit -> unit; (** Decrease the indentation level 
