Module Utils.SubargSource

Subarg

This module provides an extension of the standard Arg library with support for sub-commands. It allows defining multiple commands, each with their own set of options and arguments, and parsing command-line arguments to select and execute the appropriate command.

Note. This module is designed to work with the Arg module from the standard library. It extends its functionality to support complex command line interfaces with multiple sub-commands.

@see Arg (standard library) for the base argument parsing functionality.

Sourcetype spec = Stdlib.Arg.key * Stdlib.Arg.spec * Stdlib.Arg.doc
Sourcetype command = {
  1. name : string;
    (*

    The name of the command.

    *)
  2. help : Stdlib.Arg.usage_msg;
    (*

    A short help string describing what the command does.

    *)
  3. specs : spec list;
    (*

    The list of options and arguments accepted by this command.

    *)
  4. enter : unit -> unit;
    (*

    A function called when this command is selected.

    *)
  5. anon : (string -> unit) option;
    (*

    A function to handle anonymous (positional) arguments.

    *)
  6. commit : unit -> unit;
    (*

    A function called after successful parsing of the command.

    *)
  7. abort : unit -> unit;
    (*

    A function called when parsing fails.

    *)
}
Sourceval command : string -> Stdlib.Arg.usage_msg -> ?enter:(unit -> unit) -> ?anon:Stdlib.Arg.anon_fun -> ?commit:(unit -> unit) -> ?abort:(unit -> unit) -> spec list -> command

command name help ?enter ?anon ?commit ?abort specs creates a new command with the given name and help string. The command accepts the options defined in specs.

  • parameter name

    The name of the command.

  • parameter help

    A short help string describing what the command does.

  • parameter enter

    A function called when this command is selected (default: ignore).

  • parameter anon

    A function to handle anonymous arguments (default: None).

  • parameter commit

    A function called after successful parsing (default: ignore).

  • parameter abort

    A function called when parsing fails (default: ignore).

  • parameter specs

    The list of options and arguments accepted by this command.

  • raises Invalid_argument

    if the default command is not in the command list.

Sourceval usage_string : spec list -> command list -> Stdlib.Arg.usage_msg -> string

usage_string specs commands errmsg returns a complete usage string for the command set. It includes the global options and the sub-command list.

  • parameter specs

    The global options (applies to all commands).

  • parameter commands

    The list of available commands.

  • parameter errmsg

    The error message to display if parsing fails.

Sourceval usage : spec list -> command list -> Stdlib.Arg.usage_msg -> unit

usage speclist commands errmsg prints a complete usage message to standard error and exits with code 2.

  • parameter speclist

    The global options.

  • parameter commands

    The list of available commands.

  • parameter errmsg

    The error message to display if parsing fails.

Sourceval parse_argv : ?current:int Stdlib.ref -> string array -> spec list -> command list -> ?default:string -> ?warn_default:(unit -> unit) -> ?no_subcommand:(unit -> unit) -> Stdlib.Arg.anon_fun -> Stdlib.Arg.usage_msg -> unit

parse_argv ?current argv specs commands ?default ?warn_default ?no_subcommand anon msg parses command-line arguments and executes the specified command.

The function selects the appropriate command based on the first argument (which must be one of the command names), then parses the remaining arguments according to that command's specifications.

  • parameter ?current

    A reference to the current argument index (default: Arg.current).

  • parameter argv

    The command-line arguments array.

  • parameter specs

    The global options (applies to all commands).

  • parameter commands

    The list of available commands.

  • parameter ?default

    The default command name if no command is specified.

  • parameter ?warn_default

    A function called when the default command is used.

  • parameter ?no_subcommand

    A function called when no sub-command is specified.

  • parameter anon

    A function to handle anonymous arguments.

  • parameter msg

    The usage message to display on error.

  • raises Bad

    if parsing fails.

  • raises Help

    if the -help or --help option is encountered.

Sourceval parse : spec list -> command list -> ?default:string -> ?warn_default:(unit -> unit) -> ?no_subcommand:(unit -> unit) -> Stdlib.Arg.anon_fun -> Stdlib.Arg.usage_msg -> unit

parse specs commands ?default ?warn_default ?no_subcommand anon usage parses command-line arguments and executes the specified command, exiting cleanly on error.

This is a wrapper around parse_argv that handles exit codes and exceptions.

  • parameter specs

    The global options.

  • parameter commands

    The list of available commands.

  • parameter ?default

    The default command name if no command is specified.

  • parameter ?warn_default

    A function called when the default command is used.

  • parameter ?no_subcommand

    A function called when no sub-command is specified.

  • parameter anon

    A function to handle anonymous arguments.

  • parameter usage

    The usage message to display on error.

  • raises Exit

    2 if parsing fails.

  • raises Exit

    0 if -help or --help is encountered.