Module Kwapp.Option

module Option: sig .. end

Command Line Option Processing

This getopt is a compromise between the simplicity of Arg and the complexity of Cmdliner. This module is purely-applicative, as opposed to the side-effectual Arg. The generated usage message is fairly detailed and nicely formatted, with option descriptions and defaults, but not nearly as nice as Cmdliner's man pages.

Cmdliner is a higher-level abstraction. As a result, unlike Cmdliner, the functions provided by Kwapp can be used to implement subcommand-style applications with leading global options and distinct options per subcommand, and the types are easier to understand.

Traditional, short options (e.g. -v -x /foo) are supported (including optional "mashed" options e.g. -vx /foo), as are GNU-style long-options (e.g. --verbose --xpath=/foo) and old-style long options (e.g. -verbose -xpath /foo) -- though the latter obviously may conflict with "mashed" options and so are not recommended.

Terminology and types:

opt: an option definition Kwapp.Option.opt specifies arguments, types, and descriptions of some switch
switch: a list of equivalent switch names (such as ["-H"; "--help"]) paired with an opt
switchset: all the switches accepted by a call to Kwapp.getopt; for a simple app, this might be all the switches; for a subcommand-style app, you might have one global switchset (for switches that precede any subcommand) plus one more switchset for each subcommand each defining switches specific to that subcommand.
Parsed options (Parsedopt.ts): a successful call to Kwapp.getopt returns a Parsedopt.t (plus the remainder of argv); the Parsedopt.t is a Parsedopt map. The keys are switch names from the switchset which were present on the command line and the values are string options. The values represent the argument to the given switch.

The existence of a given switch name in the Parsedopt.t indicates that the switch was provided on the command line; the absence of the switch in the map indicates that it was not provided.

If a switch has multiple names e.g. it is defined by a switch such as sws ["-d";"--directory"] and any one of the names was given on the command line, the map will contain an entry for each of the names (all with the same value), so that you can query the map with any switch name you choose and don't need to know which name was actually used (in fact, there's no way to know this).

For a Boolean switch that was provided in the argv i.e. one that doesn't take an argument (and thus has opt.arg = None), the value in the map in this case will be None. For a given Parsedopt.t p, whether or not a switch s was provided is easily tested with has s p e.g. has "-v" p.

For a switch taking an argument that was provided in the argv, the value in the map in this case will be Some s where s is the string given as the argument. For a given Parsedopt.t p, whether or not such a switch s was provided is easily tested with has s p e.g. has "-d" p and the value can be obtained with e.g. value switchset "-d" p. If the switch was not given in argv but it has a default value, value will return the default.

This module is designed to be opened in restricted scopes e.g. Option.(...).

Option Definitions

A command-line option is described by a switch; a set of command-line options is an switchset.

type opt = {

`arg : string option;`	`(*`	short name of option's argument, if any	`*)`
`def : string list;`	`(*`	default value of option, if not given on the command line	`*)`
`desc : string;`	`(*`	one-line description of the option	`*)`
`req : bool;`	`(*`	true if the option is required; observed by `Kwapp.Option.check`	`*)`
`validate : Valid.t option;`	`(*`	validator	`*)`
`mex : int;`	`(*`	mutual exclusivity class; observed by `Kwapp.Option.check`	`*)`
`rep : bool;`	`(*`	true if the option is repeatable; observed by `Kwapp.Option.check`	`*)`
`hide : bool;`	`(*`	if true, don't include this option in any help strings	`*)`
`nyi : string option option;`	`(*`	if true, raise `Kwapp.NYI` immediately if option given on command line	`*)`

}

The type of option definitions.

val string_of_opt : opt -> string

type switch = string list * opt

val string_of_switch : string list * opt -> string

type switchset = switch list

val string_of_switchset : switchset -> string

val req : opt

Template for a required option; all fields are null except for req which is true. It's generally preferable to define an option via the combinators below (sw and friends).

val opt : opt

Template for an optional option; all fields are null except for req which is false. It's generally preferable to define an option via the combinators below (sw and friends).

val validate : string list * opt -> unit

validate switch: validate a switch.

Checks that the switch has at least one name and that a required switch doesn't have a (pointless) default value or (pointless) validator.

You typically don't want to call this; Kwapp.getopt, Kwapp.Option.check, and Help.help all call Kwapp.Option.validate for you.
Raises

Nameless raises Nameless for a switch that has no name
BadSwitch raises BadSwitch for a switch that is required but has pointless default, or that takes no arg but has a validator

Combinators for Building `switchset`s.

switchsets are lists of switchs, where each string in the string list is an equivalent switch name (e.g. "-v";"--verbose") for the option described by opt.

They can be built manually, e.g.:

[
  ["-v"], { opt with arg = None; def = None; desc = "set VERBOSITY to 1"; };
  ["-x";"--xpath"], { opt with arg = Some "XPATH"; def = None; desc = "Xpath of XML elements to be extracted"; };
    ]

but it may be less verbose to use these combinators:

[
  sw "-v" +> desc "set VERBOSITY to 1";
  sws ["-x";"--xpath"] +> arg "XPATH" +> desc "Xpath of XML elements to be extracted";
]

You generate a basic switch with sw and then flesh out the details with additional combinator applications.

Combinators on `switch`s.

val (+>) : 'a -> ('a -> 'b) -> 'b

(+>): infix operator to combine combinators (sw,sws,alias,optional,required,arg,def,desc,valid); really just right-associative function composition.

val sw : string -> string list * opt

sw s: generate a minimal switch for an optional switch named s that takes no arguments and has no description.

val sws : string list -> string list * opt

sws ss: shorthand for defining an option with one or more aliases.

sws ["-a";"-b"] is the same as sw "-a" +> alias "-b"

val alias : string -> string list * 'a -> string list * 'a

alias s opt: add an alias (i.e. another name) to a switch.

val optional : 'a * opt -> 'a * opt

optional opt: make the option optional.

val required : 'a * opt -> 'a * opt

required opt: make the option required.

val rep : 'a * opt -> 'a * opt

rep opt: make the option repeatable.

val arg : string -> 'a * opt -> 'a * opt

arg a opt: add a short name for the option's argument (used in the help message).

This is how you indicate that an option takes an argument!

a : the argument name

val def : string list -> 'a * opt -> 'a * opt

def d opt: add a default value for the option. Kwapp.value will return this default if the option isn't given on the command line.

d : the default

val mex : int -> 'a * opt -> 'a * opt

mex n opt: add a mutual-exclusivity class (1,∞) for the option.

Options in different classes cannot be given together in a command invocation.
Raises Failure if invoked with 0 as class number

val desc : string -> 'a * opt -> 'a * opt

desc d opt: add a one-line desacription of the option's semantics.

The default value (if any) will automatically be appended to the help message.

d : the description

val valid : Valid.t -> 'a * opt -> 'a * opt

valid v opt: add a validator for the option's argument.

A description of the argument's type will automatically be appended to the help message.

v : the validator

val hide : 'a * opt -> 'a * opt

hide opt: make this option hidden.

A hidden option will not be described in any help strings.

val nyi : ?because:string -> 'a * opt -> 'a * opt

nyi reason opt: this option is not yet implemented.

A Kwapp.NYI exception will be raised by Kwapp.Option.check if the option is given on the command line.

because : message given in the Kwapp.NYI exception

Combinators on `switchset`s.

val withhelp : ?sws:string list ->
       (string list * opt) list ->
       (string list * opt) list

withhelp ?sws switchset: add standard help options to a switchset.

For example, this defines a set of options with a "-v" verbose option and the standard help options:

[sw "-v"] +> withhelp

sws : list of help switches (default: ["-H";"--help"])

Validation of options

val check : (Kwapp.Parsedopt.key list * opt) list ->
       Kwapp.parsedopts * string list -> Kwapp.parsedopts * string list

check iopts (m,argv): check parsed command line to assure that all required options were provided, that there are no mutually-exclusive option conflicts, and that all option arguments validate.
Raises

Missing if any required options were missing
Invalid if option argument or command-line arg has an invalid type
ReqAfter for a required option after an optional one
Mutual if mutually exclusive arguments were provided
NYI if any option in m has something iopts.nyi

iopts : the Kwapp.Option.switchset, typically from the app Kwapp.interface

(m,argv) : argv : actual argv, typically from Kwapp.getopt
m : parsed options, typically from Kwapp.getopt

val sanshidden : ('a * opt) list -> ('a * opt) list

sanshidden switchset: remove the hidden switches from switchset.
Returns a copy of the input with all hidden switches removed

switchset : the switchset