Subsections

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:

5.1 Types, Constants and variables :

5.1.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.

5.1.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.

5.1.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.

5.2 Procedures and functions


5.2.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


5.2.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.


root
2000-12-20