Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
UnixArguments

NAME

UnixArguments - scan command line arguments

SYNOPSIS

TYPE Argument = POINTER TO ArgumentRec;
TYPE ArgumentRec = RECORD (Streams.StreamRec) END;



VAR usagecode: INTEGER;



PROCEDURE Init(infostring: ARRAY OF CHAR);
PROCEDURE Usage;
PROCEDURE GetFlag(VAR flag: CHAR) : BOOLEAN;
PROCEDURE GetOpt(VAR flag: CHAR; VAR plus: BOOLEAN) : BOOLEAN;
PROCEDURE Fetch(VAR arg: Streams.Stream);
PROCEDURE FetchString(VAR string: ARRAY OF CHAR);
PROCEDURE GetArg(VAR string: ARRAY OF CHAR) : BOOLEAN;
PROCEDURE OpenArg(VAR arg: Streams.Stream) : BOOLEAN;
PROCEDURE UngetArg;
PROCEDURE UngetOpt;
PROCEDURE AllArgs;
PROCEDURE GetCommandName(VAR name: ARRAY OF CHAR);
PROCEDURE GetPathName(VAR path: ARRAY OF CHAR);

DESCRIPTION

The UnixArguments module supports reading and interpreting command line arguments, according to the following standard:

Flags: are single characters preceded by a -.
Options,: however, can be preceded either by - or +.
Flags or options with the same prefix: may be concatenated to one command argument, without repeating the prefix.
A: value follows a flag/option as the rest of the command argument or as the next command argument. Nothing can follow a value in the same command argument.
-
as a command argument: is interpreted as a non-flag/non-option argument. It should designate standard input or standard output in place of a file.
--
as a command argument: terminates flag/option processing but is itself not interpreted as an argument. Successing command arguments, even when beginning with - or + are considered not to contain flags nor options.

The procedures are used as follows:

Init specifies infostring for Usage and (re)starts the reading cycle, i.e. makes the first command argument the next one to be read.

Usage prints 'Usage: command infostring' onto Streams.stderr and terminates program execution ('command' stands here for the actual processes' name). Usage passes usagecode as parameter to SysProcess.Exit.

AllArgs calls Usage if any command arguments are not yet read.

GetFlag and GetOpt read one flag resp. option from the argument list or return FALSE if all of them have been read. GetOpt sets plus to TRUE if the actual option is of the kind +x, otherwise FALSE.

GetArg reads one arbitrary argument and OpenArg opens one argument for reading. Both return FALSE if all arguments have been read already. The stream opened by OpenArg is closed automatically.

FetchString reads an argument and Fetch opens an argument for reading. If the selected argument (part) is missing Usage is called implicitly. The stream opened by Fetch is closed automatically.

UngetOpt and UngetArg push back one flag/option resp. argument per call to the list of not yet read command arguments. Note that UngetOpt is not able to skip command arguments that have been read using GetArg or one of the Fetch procedures.

GetPathName returns the first argument which is by convention the name of the executable. GetCommandName returns the basename of the first argument (i.e. without leading directory path).

Streams returned by Fetch and OpenArg are of type UnixArguments.Argument.

EXAMPLE

PROCEDURE WorkupArguments;
   VAR
      arg: Streams.Stream;
      flag: CHAR;
BEGIN
   xflag := FALSE;
   number := 1;
   string := defaultstring;
   UnixArguments.Init("[-x] [-s string] [-nnn] [file]...");
   WHILE UnixArguments.GetFlag(flag) DO
      CASE flag OF
      | "x":      xflag := TRUE;
      | "s":      UnixArguments.FetchString(string);
      | "0".."9": UnixArguments.UngetOpt;
                  UnixArguments.Fetch(arg); Read.IntS(arg, number);
      ELSE
         UnixArguments.Usage
      END;
   END;
   WHILE UnixArguments.GetArg(filename) DO
      IF filename = "-" THEN
         (* process Streams.stdin *)
      ELSE
         (* process filename *)
      END;
   END;
END WorkupArguments;

AUTHOR

Martin Hasch, University of Ulm
revised by Andreas Borchert

Edited by: borchert, last change: 2005/08/23, revision: 1.10, converted to HTML: 2005/08/23