Previous  Up  Next

Module Kwapp.Argv

module Argv: sig .. end
Command-line Argument Definitions

The command-line arguments are the non-option arguments of the program (i.e. not switches and their possible values). They come after all arguments that look like switches. The standard optional "--" option terminates the options; anything that comes after it is considered an argument and is the purview of this Kwapp.Argv module.

Command-line arguments are positional and are typically accessed by calling Kwapp.getopt to split the command line into options (and their values) and the command-line args, returned as a string list. You can extract the args by pattern matching or by name by calling Kwapp.argument.

The combinators work similarly to those for Options, but since args are positional, the Argv combinators are applied in a single chain, while the Option combinators are applied to a single option at a atime, and multiple options are gathered in a list.

All combinators apply to the previous arg, but all those for a given arg may come in any order (arg must come first).

Examples:

  1. one file arg: Argv.(empty +> arg "FILE")
  2. one optional file arg: Argv.(empty +> arg "FILE" +> optional)
  3. two file args: Argv.(empty +> arg "FILE1" +> arg "FILE2")
  4. two file args, the final one optional: Argv.(empty +> arg "FILE1" +> arg "FILE2" +> optional)
  5. two file args, the final one required but repeatable (at least one final arg required): Argv.(empty +> arg "FILE1" +> arg "FILE2" +> rep)
  6. two file args, the final one optional but repeatable: Argv.(empty +> arg "FILE1" +> arg "FILE2" +> optional +> rep)
Illegal examples:

  1. attempt to apply a combinator to the empty argv (add an arg with arg name first): Argv.(empty +> optional)
  2. two file args, the first repeatable (only the final arg can be repeatable): Argv.(empty +> arg "FILE1" +> rep +> arg "FILE2")


Types


type arg = {
   name : string; (*
name
*)
   opt : bool; (*
optional
*)
   def : string option; (*
default value of arg, if not given on the command line
*)
   desc : string option; (*
description
*)
   validate : Valid.t option; (*
validator
*)
   hide : bool; (*
hidden in help strings?
*)
}
The type of individual command-line arguments.
val string_of_arg : arg -> string
type argv = {
   argv : arg list;
   rep : arg option;
}
The type of the complete command-line argument vector.
val string_of_argv : argv -> string
val empty : argv
The empty argv, which accepts no args.
val any : argv
The argv that accepts zero or more arbitrary string args.
val validate : argv -> unit
validate argv: validate an argv.

Checks that the argv doesn't define a required arg after an optional arg.

You typically don't want to call this; Kwapp.getopt, Kwapp.Argv.check, and Help.help all call Kwapp.Argv.validate for you.
Raises ReqAfter for a required option after an optional one


Combinators


val (+>) : 'a -> ('a -> 'b) -> 'b
(+>): infix operator to combine combinators (arg,optional,valid,rep); really just right-associative function composition.
val arg : string -> argv -> argv
arg name: define a command line argument with the name name.
Raises Failure on attempt to add an arg after a repeatable arg
val optional : argv -> argv
optional: make the argument optional.
Raises Failure if applied to no arg
val desc : string -> argv -> argv
desc description: give the argument a description.
Raises Failure if applied to no arg
val def : string -> argv -> argv
def d: : add a default value for an optional command-line arg.

Kwapp.argument will return this default if the option isn't given on the command line.
Raises Failure if applied to no arg or if applied to a required arg

d : the default
val valid : Valid.t -> argv -> argv
valid v: add a validator to the argument.
Raises Failure if applied to no arg
val rep : argv -> argv
rep: make the final argument repeatable.

Only the final argument can be repeatable!
Raises Failure if applied to no arg or if applied to an argv whose last arg is already repeatable

val hide : argv -> argv
hide: make this argument hidden.

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


Validation of arguments


val check : argv -> Kwapp.parsedopts * string list -> unit
check iargv (m,argv): check parsed command line to assure that all required command-line arguments were provided, that there are no mutually-exclusive option conflicts, and that all option arguments validate.
Raises
iargv : the Kwapp.Argv.argv, typically from the app Kwapp.interface
(m,argv) : argv : actual argv, typically from Kwapp.getopt
m : parsed options, typically from Kwapp.getopt
val sanshidden : argv -> argv
sanshidden argv: remove the hidden args from argv.
Returns a copy of the input with all hidden args removed
argv : the argv