Previous section To contents Next section

14.6 Getopt

Getopt is a group of function which can be used to find command line options. Command line options come in two flavors: long and short. The short ones consists of a dash followed by a character (-t), the long ones consist of two dashes followed by a string of text (--test). The short options can also be combined, which means that you can write -tda instead of -t -d -a. Options can also require arguments, in which case they cannot be combined. To write an option with an argument you write -t argument or -targument or --test=argument.

FUNCTION
Getopt.find_option - find command line options

SYNTAX

mixed find_option(array(string) argv,

string shortform,
void|string longform,
void|string envvar,
void|mixed def,
void|int throw_errors);

DESCRIPTION
This is a generic function to parse command line options of the type '-f', '--foo' or '--foo=bar'. The first argument should be the array of strings that is sent as second argument to your main() function, the second is a string with the short form of your option. The short form must be only one character long. The 'longform' is an alternative and maybe more readable way to give the same option. If you give "foo" as longform your program will accept '--foo' as argument. The envvar argument specifies what environment variable can be used to specify the same option. The envvar option exists to make it easier to customize program usage. The 'def' has two functions: It specifies that the option takes an argument and it tells find_option what to return if the option is not present. If 'def' is given and the option does not have an argument find_option will print an error message and exit the program.

Also, as an extra bonus: shortform, longform and envvar can all be arrays, in which case either of the options in the array will be accpted.

NOTE
find_option modifies argv.
This function reads options even if they are written after the first non-option on the line.

EXAMPLE 
/* This program tests two different options. One is called -f or
 * --foo and the other is called -b or --bar and can also be given
 * by using the BAR_OPTION environment variable.
 */

int main(int argc, array(string) argv)
{
    if(find_option(argv,"f","foo"))
        werror("The FOO option was given.\n");

    werror("The BAR option got the "+
        find_option(argv,"b","bar","BAR_OPTION","default")+
        " argument.\n");
}

SEE ALSO
Getopt.get_args

FUNCTION
Getopt.find_all_options - find command line options

SYNTAX
array find_all_options(array(string) argv, array option, int|void posix_me_harder, int|void throw_errors);

DESCRIPTION
This function does the job of several calls to find_option. The main advantage of this is that it allows it to handle the POSIX_ME_HARDER environment variable better. When the either the argument posix_me_harder or the environment variable POSIX_ME_HARDER is true, no arguments will be parsed after the first non-option on the command line.

Each element in the array options should be an array on the following form:

({
string name,
int type,
string|array(string) aliases,
void|string|array(string) env_var,
void|mixed default
})
Only the first three elements has to be included.
name
Name is a tag used to identify the option in the output.
type
Type is one of Getopt.HAS_ARG, Getopt.NO_ARG and Getopt.MAY_HAVE_ARG and it affects how the error handling and parsing works. You should use HAS_ARG for options that require a path, a number or similar. NO_ARG should be used for options that do not need an argument, such as --version. MAY_HAVE_ARG should be used for options that may or may not need an argument.
aliases
This is a string or an array of string of options that will be looked for. Short and long options can be mixed, and short options can be combined into one string. Note that you must include the dashes in aliases so find_all_options can distinguish between long and short options. Example: ({"-tT","--test"}) This would make find_all_options look for -t, -T and --test.
env_var
This is a string or an array of strings containing names of environment variables that can be used instead of the command line option.
default
This is the default value the option will have in the output from this function. Options without defaults will be omitted from the output if they are not found in argv.
The good news is that the output from this function is a lot simpler. Find_all_options returns an array where each element is an array on this form:
({
string name,
mixed value
})
The name is the identifier from the input and value is the value given to it from the argument, environment variable or default. If no default is given, value will be 1.

NOTE
find_all_options modifies argv.

EXAMPLE
First let's take a look at input and output: 
> Getopt.find_all_options(({"test","-dd"}),
>>  ({ ({ "debug", Getopt.NO_ARG, ({"-d","--debug"}), "DEBUG", 1}) }));
Result: ({
  ({ "debug",  1 }),
  ({ "debug",  1 })
})

This is what it would look like in real code: 

import Getopt;

int debug=0;

int main(int argc, array(string) argv
{
    foreach(find_all_options(argv, ({
        ({ "debug", MAY_HAVE_ARG, ({"-d","--debug"}), "DEBUG", 1}),
        ({ "version", NO_ARG, ({"-v","--version" }) })  })),
        mixed option)
    {
        switch(option[0])
        {
            case "debug": debug+=option[1]; break;
            case "version":
                write("Test program version 1.0\n");
                exit(1);
        }
    }

    argv=Getopt.get_args(argv);
}

SEE ALSO
Getopt.get_args

FUNCTION
Getopt.get_args - get the non-option arguments

SYNTAX
array(string) get_args(array(string) argv,void|int throw_errors);

DESCRIPTION
This function returns the remaining command line arguments after you have run find_options to find all the options in the argument list. If there are any options left not handled by find_options an error message will be written and the program will exit. Otherwise a new 'argv' array without the parsed options is returned.

EXAMPLE 
int main(int argc, array(string) argv)
{
    if(find_option(argv,"f","foo"))
        werror("The FOO option was given.\n");

    argv=get_args(argv);
    werror("The arguments are: "+(argv*" ")+".\n");
}

SEE ALSO
Getopt.find_option
Previous section To contents Next section