14.1 argp

Like any other program, Poke scripts often need to handle options passed in the command line. The argp pickle provides a convenient and easy way to handle these arguments.

The main entry point of the pickle is the function argp_parse, with the following prototype:

fun argp_parse = (string program,
                  string version = "",
                  string summary = "",
                  Argp_Option[] opts = Argp_Option[](),
                  string[] argv = string[](),
                  int allow_unknown = 0) string[]

Where program is the name of the program providing the command-line options. version is either a string identifying the version of the program, or the empty string. summary is a short summary of what the program does. opts is an array of Argp_Option structs, each of which describe a command line option and, in particular, a handler for that option. argv is an array of string containing the command line elements to process. Finally, allow_unknown specifies whether unknown options constitute an error or not. This last option is useful in order to support sub-parsers.

Once invoked, argp_parse analyzes the command line provided in argv, recognizes options, performs checks making sure that all specified options are well formed, and that every option requiring an argument gets one, invokes the handlers registered for each option, and finally returns an array of non-option arguments in argv, for further processing by the user.

Each Argp_Option struct describes an option. They have this form:

type Argp_Option =
  struct
  {
    string name;
    string long_name;
    string summary;
    string arg_name;
    int arg_required;
    Argp_Option_Handler handler;
  };

Where name is a string of size one character specifying the short name for the option. long_name is a non-empty string of any size specifying the long name for the option. summary is a short paragraph with a summary of that the option does. arg_name, if specified, is a string to be used to describe the argument of the option in the --help output. If arg_name is not specified then "ARG" is used. arg_required is a boolean specifying whether the option accepts and expects an argument. Defaults to 0. Finally, handler is a function that will be invoked to process the option. The function has the following prototype:

type Argp_Option_Handler = (string)void

The argp_parse function provides default handlers for several standard options:

--help

The default handler for this option prints out an usage message in the standard GNU way, and exits. In particular, this output is compatible with the help2man utility.

--version

The default handler for this option prints out the name and the version of the program, and exits.

If the user provides handlers for the options above, these take precedence wrt the default handlers.

Several short options can be accumulated this way:

foo -qyz

The special option --, if found in the command line, stops the processing of options. Everything found about it is considered non-option arguments.