Batteries user guide : BatOptParse.Opt

# Module BatOptParse.Opt

    module Opt: sig .. end

This module contains the basic functions and types for defining new option types and accessing the values of options.

###### 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.

###### 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 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`.

###### Option value retrieval

    val get : 'a t -> 'a

Get the value of an option.
Raises `No_value` if no default values has been given and the option value has not been set from the command line.
Returns the value of the option. If the option has not been encountered while parsing the command line, the default value is returned.

    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.
Returns `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).
Returns `True` iff the option has a value.

###### 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 option has no default value.
Returns 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.
Returns the newly created option.