Permalink
Switch branches/tags
Find file
Fetching contributors…
Cannot retrieve contributors at this time
67 lines (46 sloc) 2.37 KB

NAME

docs/dev/longopt.pod - Long option parsing

DESCRIPTION

The files longopt.c and longopt.h implement rudimentary long option parsing. They have little to do with Parrot itself, other than that the parrot binary and imcc both needed long options. So this gives it to them.

USAGE

To use longopt, you first need to #include "parrot/longopt.h" (it comes with parrot/parrot.h, too). Then you need to set up the options table, which is an array of struct longopt_opt_decls.

Each element of this array has four components: the short option, the option id (generally the same as the short option), some flags, and finally a list of up to nine long options (all for this one behavior), terminated with a NULL pointer.

There are currently two possible flags: OPTION_required_FLAG, which states that this option has a required argument, and OPTION_optional_FLAG, which indicates that this option has an optional argument.

The array must be terminated with an element that has 0 for the option id. So, for example:

struct longopt_opt_decl options[] = {
    { 'f', 'f', 0,                    { "--foo", NULL } },
    { 'b', 'b', OPTION_required_FLAG, { "--bar", NULL } },
    {   0, 128, 0,                    { "--baz", "--bazbar", NULL } },
    {   0,   0, OPTION_optional_FLAG, { NULL } }
};

This is a structure that specifies three options.

Some various ways you could give these options on the command line follow:

program --baz --bar=arg --foo somefile
program --bar arg -f somefile
program -f -b arg --bazbar somefile
program -barg -f somefile
program -fbarg somefile

So it basically behaves how most GNU programs do. It accepts - as a real argument, and -- as a non argument, but that specifies that only non-flags will follow. Again, just like GNU.

No options can follow a non-option, however. This is because programs that this is written for, like parrot, usually want to pass options given after the file to the file they're executing.

BUGS

It won't complain if you don't give it an argument to an option expecting one. It will just set the opt_arg pointer to NULL.

It won't complain if you give an argument to an option not expecting one. It will just ignore it (this only applies to the --foo=bar style).

AUTHOR

Luke Palmer  C<fibonaci@babylonia.flatirons.org>