module OptParse

: sig

Modules for GNU getopt(3)-style command line parsing.

module Opt : sig

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.

Returns the value of the option. If the option has not been encountered while parsing the command line, the default value is returned.

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

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

end

module StdOpt : sig

This module contains various standard options.

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

increment Increment to add to the option value each time the option is encountered.

dest Reference to the option value. Useful for making options like '--quiet' and '--verbose' sharing a single value.

Returns the newly created option.

val incr_option : ?dest:int Pervasives.ref -> unit -> int Opt.t

Exactly identical to count_option ~dest:dest ~increment:1 ().

val decr_option : ?dest:int Pervasives.ref -> unit -> int Opt.t

Exactly identical to count_option ~dest:dest ~increment:(-1) ().

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.

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.

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

module Formatter : sig

This module contains the types and functions for implementing custom usage message formatters.

type t = {

# indent	: unit -> unit	;	(*	Increase the indentation level.	*)
# dedent	: unit -> unit	;	(*	Decrease the indentation level.	*)
# format_usage	: string -> string	;	(*	Format usage string into style of this formatter.	*)
# format_heading	: string -> string	;	(*	Format heading into style of this formatter.	*)
# format_description	: string -> string	;	(*	Format description into style of this formatter.	*)
# format_option	: char list * string list -> string list -> string option -> string	;	(*	Format option into style of this formatter (see explanation below).	*)

}

This is the type of a formatter. The format_option has signature format_option (snames,lnames) metavars help, where snames is a list of the short option names, lnames is a list of the long option names, metavars is a list of the metavars the option takes as arguments, and help is the help string supplied by the user.

Standard formatters

val indented_formatter : ?level:int Pervasives.ref -> ?indent:int Pervasives.ref -> ?indent_increment:int -> ?max_help_position:int -> ?width:int -> ?short_first:bool -> unit -> t

Create an "indented" formatter with the given options.

width Total with of the usage messages printed.

max_help_position Maximum starting column for the help messages relating to each option.

short_first List all the short option names first?

indent_increment Number of columns to indent by when more indentation is required.

indent Reference to the current indentation amount. Its value reflects changes in indentation level.

level Reference to the current indentation level. Its value reflects changes in indentation level.

val titled_formatter : ?level:int Pervasives.ref -> ?indent:int Pervasives.ref -> ?indent_increment:int -> ?max_help_position:int -> ?width:int -> ?short_first:bool -> unit -> t

Creates a titled formatter which is quite similar to the indented formatter. See OptParse.Formatter.indented_formatter for a description of the options.

Low-level formatting

val wrap : ?initial_indent:int -> ?subsequent_indent:int -> string -> int -> string list

wrap text width reflows the given text paragraph into lines of width at most width (lines may exceed this if the are single words that exceed this limit).

initial_indent Indentation of the first line.

subsequent_indent Indentation of the following lines.

Returns a list of lines making up the reformatted paragraph.

val fill : ?initial_indent:int -> ?subsequent_indent:int -> string -> int -> string

See OptParse.Formatter.wrap.

Returns a string containing the reformatted paragraph.

end

module OptParser : sig

This module contains the option parser itself.

It provides functions to create, populate and use option parsers to parse command line arguments.

Exceptions

exception Option_conflict of string

Option_conflict name is raised by OptParse.OptParser.add when two different options are added with identical names. Usually this doesn't need to be caught since this error is usually easily fixed permanently by removing/renaming the conflicting option names.

Types

type t

The type of an option parser.

type group

The type of an option group.

Option parser creation

val make : ?usage:string -> ?description:string -> ?version:string -> ?suppress_usage:bool -> ?suppress_help:bool -> ?prog:string -> ?formatter:Formatter.t -> unit -> t

Creates a new option parser with the given options.

usage Usage message. The default is a reasonable usage message for most programs. Any occurrence of the substring "%prog" in usage is replaced with the name of the program (see prog).

prog Program name. The default is the base name of the executable.

suppress_usage Suppress the usage message if set.

suppress_help Suppress the 'help' option which is otherwise added by default.

version Version string. If set, a '--version' option is automatically added. When encountered on the command line it causes version to be printed to the standard output and the program to exit.

description : description of the main purpose of the program.

Returns the new option parser.

val add : t -> ?group:group -> ?help:string -> ?hide:bool -> ?short_name:char -> ?short_names:char list -> ?long_name:string -> ?long_names:string list -> 'a Opt.t -> unit

Add an option to the option parser.

Raises Option_conflict if the short name(s) or long name(s) have alread been used for some other option.

help Short help message describing the option (for the usage message).

hide If true, hide the option from the usage message. This can be used to implement "secret" options which are not shown, but work just the same as regular options in all other respects.

short_name is the name for the short form of the option (e.g. 'x' means that the option is invoked with -x on the command line).

short_names is a list of names for the short form of the option (see short_name).

long_name is the name for the long form of the option (e.g. "xyzzy" means that the option is invoked with --xyzzy on the command line).

long_names is a list of names for the long form of the option (see long_name).

val add_group : t -> ?parent:group -> ?description:string -> string -> group

Add a group to the option parser.

parent is the parent group (if any).

description is a description of the group.

Returns the new group.

Output and error handling

val error : t -> ?chn:Pervasives.out_channel -> ?status:int -> string -> 'a

Display an error message and exit the program. The error message is printed to the channel chn (default is Pervasives.stderr) and the program exits with exit status status (default is 1).

val usage : t -> ?chn:Pervasives.out_channel -> unit -> unit

Display the usage message to the channel chn (default is Pervasives.stdout) and return.

Option parsing

val parse : t -> ?first:int -> ?last:int -> string array -> string list

Parse arguments as if the arguments args.(first), args.(first+1), ..., args.(last) had been given on the command line. By default first is 0 and last is the index of the last element of the array.

val parse_argv : t -> string list

Parse all the arguments in Sys.argv.

end