/ 
parrot-0.8.0
/ docs/dev/longopt.pod

NAME

docs/dev/longopt.pod - Long option parsing

SUMMARY

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 is currently one possible flag: OPTION_required_FLAG, which states that this option has a required argument. Optional arguments are not supported, and they should be.

The array should 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, 0,                    { 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>