[Chapter 7] 7.2.35 Getopt::Long - Extended Processing of Command-Line Options
Author: Larry Wall, Tom Christiansen & Randal L. Schwartz
Date: 1999-07-02T02:02:36Z

#

| Chapter 7 The Standard Perl Library |

### 7.2.35 Getopt::Long - Extended Processing of Command-Line Options

    use Getopt::Long;
    $result = GetOptions(option-descriptions);

The Getopt::Long module implements an extended function called `GetOptions()`. This function retrieves and processes the command-line options with which your Perl program was invoked, based on the description of valid options that you provide.

`GetOptions()` adheres to the POSIX syntax for command-line options, with GNU extensions. In general, this means that options have long names instead of single letters, and are introduced with a double hyphen `--`. (A single hyphen can also be used, but implies restrictions on functionality. See later in the chapter.) There is no bundling of command-line options, as was the case with the more traditional single-letter approach. For example, the UNIX ps(1) command can be given the command-line argument:

    -vax

which means the combination of `-v`, `-a` and `-x`. With the Getopt::Long syntax, `-vax` would be a single option.

Command-line options can be used to set values. These values can be specified in one of two ways:

    --size 24
    --size=24

`GetOptions()` is called with a list of option descriptions, each of which consists of two elements: the option specifier and the option linkage. The option specifier defines the name of the option and, optionally, the value it can take. The option linkage is usually a reference to a variable that will be set when the option is used. For example, the following call to `GetOptions()`:

    &GetOptions("size=i" => \$offset);

will accept a command-line option "`size`" that must have an integer value. With a command line of `--size 24` this will cause the variable `$offset` to be assigned the value 24.

Alternatively, the first argument to GetOptions may be a reference to a hash describing the linkage for the options. The following call is equivalent to the example above:

    %optctl = (size => \$offset);
    &GetOptions(\%optctl, "size=i");

Linkage may be specified using either of the above methods, or both. The linkage specified in the argument list takes precedence over the linkage specified in the hash.

The command-line options are implicitly taken from array `@ARGV`. Upon completion of `GetOptions()`, `@ARGV` will contain only the command-line arguments that were not options. (But see below for a way to process non-option arguments.) Each option specifier handed to `GetOptions()` designates the name of an option, possibly followed by an argument specifier. Values for argument specifiers are:

`<none>`

  Option does not take an argument. If the user invokes the option, the option variable will be set to 1.

`!`

  Option does not take an argument and may be negated, that is, prefixed by "`no`". For example, `foo!` will allow `--foo` (with value 1 being assigned to the option variable) and `-nofoo` (with value 0).

`=s`

  Option takes a mandatory string argument. This string will be assigned to the option variable. Even if the string argument starts with `-` or `--`, it will be assigned to the option variable rather than taken as a separate option.

`:s`

  Option takes an optional string argument. This string will be assigned to the option variable. If the string is omitted from the command invocation, `""` (an empty string) will be assigned to the option variable. If the string argument starts with `-` or `--`, it will be taken as another option rather than assigned to the option variable.

`=i`

  Option takes a mandatory integer argument. This value will be assigned to the option variable. Note that the value may start with `-` to indicate a negative value.

`:i`

  Option takes an optional integer argument. This integer value will be assigned to the option variable. If the optional argument is omitted, the value 0 will be assigned to the option variable. The value may start with `-` to indicate a negative value.

`=f`

  Option takes a mandatory floating-point argument. This value will be assigned to the option variable. Note that the value may start with `-` to indicate a negative value.

`:f`

  Option takes an optional floating-point argument. This value will be assigned to the option variable. If the optional argument is omitted, the value 0 will be assigned to the option variable. The value may start with `-` to indicate a negative value.

A lone hyphen `-` is considered an option; the corresponding option name is the empty string.

A lone double hyphen `--` terminates the processing of options and arguments. Any options following the double hyphen will remain in `@ARGV` when `GetOptions()` returns.

If an argument specifier concludes with `@` (as in `=s@`), then the option is treated as an array. That is, multiple invocations of the same option, each with a particular value, will result in the list of values being assigned to the option variable, which is an array. See the following section for an example.

#### 7.2.35.1 Linkage specification

The linkage specifier is optional. If no linkage is explicitly specified but a hash reference is passed, `GetOptions()` will place the value in the hash. For example:

    %optctl = ();
    &GetOptions (\%optctl, "size=i");

will perform the equivalent of the assignment:

    $optctl{"size"} = 24;

For array options, a reference to an anonymous array is generated. For example:

    %optctl = ();
    &GetOptions (\%optctl, "sizes=i@");

with command-line arguments:

    -sizes 24 -sizes 48

will perform the equivalent of the assignment:

    $optctl{"sizes"} = [24, 48];

If no linkage is explicitly specified and no hash reference is passed, `GetOptions()` will put the value in a global variable named after the option, prefixed by `opt_`. To yield a usable Perl variable, characters that are not part of the syntax for variables are translated to underscores. For example, `--fpp-struct-return` will set the variable `$opt_fpp_struct_return`. (Note that this variable resides in the namespace of the calling program, not necessarily main.) For example:

    &GetOptions ("size=i", "sizes=i@");

with command line:

    -size 10 -sizes 24 -sizes 48

will perform the equivalent of the assignments:

    $opt_size = 10;
    @opt_sizes = (24, 48);

A lone hyphen (`-`) is considered an option; the corresponding identifier is `$opt_` .

The linkage specifier can be a reference to a scalar, a reference to an array, or a reference to a subroutine:

- If a scalar reference is supplied, the new value is stored in the referenced variable. If the option occurs more than once, the previous value is overwritten.

- If an array reference is supplied, the new value is appended (pushed) to the referenced array.

- If a code reference is supplied, the referenced subroutine is called with two arguments: the option name and the option value. The option name is always the true name, not an abbreviation or alias.

#### 7.2.35.2 Aliases and abbreviations

The option specifier may actually include a "`|`"-separated list of option names:

    foo|bar|blech=s

In this example, `foo` is the true name of the option. If no linkage is specified, options `-foo`, `-bar` and `-blech` all will set `$opt_foo`.

Options may be invoked as unique abbreviations, depending on configuration variable `$Getopt::Long::autoabbrev`.

#### 7.2.35.3 Non-option callback routine

A special option specifier `<>` can be used to designate a subroutine to handle non-option arguments. For example:

    &GetOptions(..."<>", \&mysub...);

In this case `GetOptions()` will immediately call `&mysub` for every non-option it encounters in the options list. This subroutine gets the name of the non-option passed. This feature requires `$Getopt::Long::order` to have the value of the predefined and exported variable, `$PERMUTE`. See also the examples.

#### 7.2.35.4 Option starters

On the command line, options can start with `-` (traditional), `--` (POSIX), and `+` (GNU, now being phased out). The latter is not allowed if the environment variable `POSIXLY_CORRECT` has been defined.

Options that start with `--` may have an argument appended, following an equals sign (`=`). For example: `--foo=bar`.

#### 7.2.35.5 Return value

A return status of `0` (false) indicates that the function detected one or more errors.

#### 7.2.35.6 Configuration variables

The following variables can be set to change the default behavior of `GetOptions()`:

`$Getopt::Long::autoabbrev`

  If true, then allow option names to be invoked with unique abbreviations. Default is `1` unless environment variable `POSIXLY_CORRECT` has been set.

`$Getopt::Long::getopt_compat`

  If true, then allow "`+`" to start options. Default is 1 unless environment variable `POSIXLY_CORRECT` has been set.

`$Getopt::Long::order`

  If set to `$PERMUTE`, then non-options are allowed to be mixed with options on the command line. If set to `$REQUIRE_ORDER`, then mixing is not allowed. Default is `$REQUIRE_ORDER` if environment variable `POSIXLY_CORRECT` has been set, `$PERMUTE` otherwise. Both `$PERMUTE` and `$REQUIRE_ORDER` are defined in the library module and automatically exported. `$PERMUTE` means that:

      -foo arg1 -bar arg2 arg3

  is equivalent to:

      -foo -bar arg1 arg2 arg3

  If a non-option callback routine is specified, `@ARGV` will always be empty upon successful return of `GetOptions()` since all options have been processed, except when `--` is used. So, for example:

      -foo arg1 -bar arg2 -- arg3

  will call the callback routine for `arg1` and `arg2`, and then terminate, leaving `arg3` in `@ARGV`. If `$Getopt::Long::order` is `$REQUIRE_ORDER`, option processing terminates when the first non-option is encountered.

      -foo arg1 -bar arg2 arg3

  is equivalent to:

      -foo -- arg1 -bar arg2 arg3

`$Getopt::Long::ignorecase`

  If true, then ignore case when matching options. Default is `1`.

`$Getopt::Long::VERSION`

  The version number of this Getopt::Long implementation is in the format `major.minor`. This can be used to have Exporter check the version. Example:

      use Getopt::Long 2.00;

  `$Getopt::Long::major_version` and `$Getopt::Long::minor_version` may be inspected for the individual components.

`$Getopt::Long::error`

  Internal error flag. May be incremented from a callback routine to cause options parsing to fail.

`$Getopt::Long::debug`

  Enable copious debugging output. Default is `0`.

#### 7.2.35.7 Examples

If the option specifier is `one:i` (which takes an optional integer argument), then the following situations are handled:

    -one -two            # $opt_one = "", -two is next option
    -one -2              # $opt_one = -2

Also, assume specifiers `foo=s` and `bar:s`:

    -bar -xxx            # $opt_bar = "", -xxx is next option
    -foo -bar            # $opt_foo = '-bar'
    -foo --              # $opt_foo = '--'

In GNU or POSIX format, option names and values can be combined:

    +foo=blech           # $opt_foo = 'blech'
    --bar=               # $opt_bar = ""
    --bar=--             # $opt_bar = '--'

Example using variable references:

    $ret = &GetOptions ('foo=s', \$foo, 'bar=i', 'ar=s', \@ar);

With command-line options `-foo blech -bar 24 -ar xx -ar yy` this will result in:

    $opt_foo = 'blech'
    $opt_bar = 24
    @ar = ('xx', 'yy')

Example of using the `<>` option specifier:

    @ARGV = qw(-foo 1 bar -foo 2 blech);
    &GetOptions("foo=i", \$myfoo, "<>", \&mysub);

Results:

    &mysub("bar") will be called (with $myfoo being 1)
    &mysub("blech") will be called (with $myfoo being 2)

Compare this with:

    @ARGV = qw(-foo 1 bar -foo 2 blech);
    &GetOptions("foo=i", \$myfoo);

This will leave the non-options in `@ARGV:`

    $myfoo becomes 2
    @ARGV  becomes qw(bar blech)

If you're using the `use strict` pragma, which requires you to employ only lexical variables or else globals that are fully declared, you will have to use the double-colon package delimiter or else the `use vars` pragma. For example:

    use strict;
    use vars qw($opt_rows $opt_cols);
    use Getopt::Long;

7.2.34 GDBM_File - Tied Access to GDBM Library |  | 7.2.36 Getopt::Std - Process Single-Character Options with Option Clustering