Subsections

- 1 Types, Constants and variables :
  - 1 Constants
  - 2 Types
  - 3 Variables
- 2 Procedures and functions
  - 1 GetLongOpts
  - 2 Getopt

# 5 The GETOPTS unit.

This document describes the GETOPTS unit for Free Pascal. It was written for LINUX by Michaël Van Canneyt. It now also works for all supported platforms.

The getopts unit provides a mechanism to handle command-line options in a structured way, much like the GNU getopts mechanism. It allows you to define the valid options for you program, and the unit will then parse the command-line options for you, and inform you of any errors.

The chapter is divided in 2 sections:

- The first section lists types, constants and variables from the interface part of the unit.
- The second section describes the functions defined in the unit.

# 1 Types, Constants and variables :

## 1 Constants

`No_Argument=0` : Specifies that a long option does not take an argument.
`Required_Argument=1` : Specifies that a long option needs an argument.
`Optional_Argument=2` : Specifies that a long option optionally takes an argument.
`EndOfOptions=#255` : Returned by getopt, getlongopts to indicate that there are no more options.

## 2 Types

    TOption = record
      Name    : String;
      Has_arg : Integer;
      Flag    : PChar;
      Value   : Char;
      end;
    POption = ^TOption;

The `option` type is used to communicate the long options to `GetLongOpts`. The `Name` field is the name of the option. `Has_arg` specifies if the option wants an argument, `Flag` is a pointer to a `char`, which is set to `Value`, if it is non-`nil`. `POption` is a pointer to a `Option` record. It is used as an argument to the `GetLongOpts` function.

## 3 Variables

`OptArg:String` Is set to the argument of an option, if the option needs one.
`Optind:Longint` Is the index of the current `paramstr()`. When all options have been processed, `optind` is the index of the first non-option parameter. This is a read-only variable. Note that it can become equal to `paramcount+1`
`OptErr:Boolean` Indicates whether `getopt()` prints error messages.
`OptOpt:Char` In case of an error, contains the character causing the error.

# 2 Procedures and functions

##
1 GetLongOpts

Declaration
  `Function GetLongOpts (Shortopts : String, LongOpts : POption; var Longint : Longint ) : Char;`

  ``

Description

  Returns the next option found on the command-line, taking into account long options as well. If no more options are found, returns `EndOfOptions`. If the option requires an argument, it is returned in the `OptArg` variable. `ShortOptions` is a string containing all possible one-letter options. (see Getopt for its description and use) `LongOpts` is a pointer to the first element of an array of `Option` records, the last of which needs a name of zero length. The function tries to match the names even partially (i.e. `-app` will match e.g. the `append` option), but will report an error in case of ambiguity. If the option needs an argument, set `Has_arg` to `Required_argument`, if the option optionally has an argument, set `Has_arg` to `Optional_argument`. If the option needs no argument, set `Has_arg` to zero. Required arguments can be specified in two ways :

  1. Pasted to the option : `-option=value`
  2. As a separate argument : `-option value`
  Optional arguments can only be specified through the first method.

Errors
  see Getopt, `getopt` (3)
See also
  Getopt

##
2 Getopt

Declaration
  `Function Getopt (Shortopts : String) : Char;`

  ``

Description

  Returns the next option found on the command-line. If no more options are found, returns `EndOfOptions`. If the option requires an argument, it is returned in the `OptArg` variable. `ShortOptions` is a string containing all possible one-letter options. If a letter is followed by a colon (:), then that option needs an argument. If a letter is followed by 2 colons, the option has an optional argument. If the first character of `shortoptions` is a `'+'` then options following a non-option are regarded as non-options (standard Unix behavior). If it is a `'-'`, then all non-options are treated as arguments of a option with character `#0`. This is useful for applications that require their options in the exact order as they appear on the command-line. If the first character of `shortoptions` is none of the above, options and non-options are permuted, so all non-options are behind all options. This allows options and non-options to be in random order on the command line.

Errors

  Errors are reported through giving back a `'?'` character. `OptOpt` then gives the character which caused the error. If `OptErr` is `True` then getopt prints an error-message to `stdout`.

See also
  GetLongOpts, `getopt` (3)

Example

      program testopt;

      { Program to depmonstrate the getopts function. }

      {
        Valid calls to this program are
        optex --verbose --add me --delete you
        optex --append --create child
        optex -ab -c me -d you
        and so on
      }
      uses getopts;

      var c : char;
          optionindex : Longint;
          theopts : array[1..7] of TOption;

      begin
        with theopts[1] do
         begin
          name:='add';
          has_arg:=1;
          flag:=nil;
          value:=#0;
        end;
        with theopts[2] do
         begin
          name:='append';
          has_arg:=0;
          flag:=nil;
          value:=#0;
        end;
        with theopts[3] do
         begin
          name:='delete';
          has_arg:=1;
          flag:=nil;
          value:=#0;
        end;
        with theopts[4] do
         begin
          name:='verbose';
          has_arg:=0;
          flag:=nil;
          value:=#0;
        end;
        with theopts[5] do
         begin
          name:='create';
          has_arg:=1;
          flag:=nil;
          value:='c'
        end;
        with theopts[6] do
         begin
          name:='file';
          has_arg:=1;
          flag:=nil;
          value:=#0;
        end;
        with theopts[7] do
         begin
          name:='';
          has_arg:=0;
          flag:=nil;
        end;
        c:=#0;
        repeat
          c:=getlongopts('abc:d:012',@theopts[1],optionindex);
          case c of
            '1','2','3','4','5','6','7','8','9' :
              begin
              writeln ('Got optind : ',c)
              end;
            #0 : begin
                 write ('Long option : ',theopts[optionindex].name);
                 if theopts[optionindex].has_arg>0 then
                   writeln (' With value  : ',optarg)
                 else
                   writeln
                 end;
            'a' : writeln ('Option a.');
            'b' : writeln ('Option b.');
            'c' : writeln ('Option c : ', optarg);
            'd' : writeln ('Option d : ', optarg);
            '?',':' : writeln ('Error with opt : ',optopt);
         end; { case }
       until c=endofoptions;
       if optind<=paramcount then
          begin
          write ('Non options : ');
          while optind<=paramcount do
            begin
            write (paramstr(optind),' ');
            inc(optind)
            end;
          writeln
          end
      end.