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

Ulm's Oberon Library:
Args

NAME

SYNOPSIS

CONST nameLen = 256;
TYPE Name = ARRAY nameLen OF CHAR; (* the name of an argument *)
TYPE Value = POINTER TO ValueRec; (* the value of an argument *)
TYPE ValueRec = RECORD (PersistentDisciplines.ObjectRec) END;
TYPE Arguments = POINTER TO ArgumentsRec; (* collection of arguments *)
TYPE ArgumentsRec = RECORD (PersistentDisciplines.ObjectRec) END;



TYPE ReadProc = PROCEDURE (s: Streams.Stream; VAR value: Value) : BOOLEAN;
TYPE PrintProc = PROCEDURE (s: Streams.Stream; value: Value);
TYPE HelpProc = PROCEDURE (s: Streams.Stream);
TYPE TypeInterface = POINTER TO TypeInterfaceRec;
TYPE TypeInterfaceRec =
   RECORD
      (Objects.ObjectRec)
      read: ReadProc;
      print: PrintProc;
      help: HelpProc; (* may be NIL *)
   END;
TYPE Type = POINTER TO TypeRec; 
TYPE TypeRec =
   RECORD 
      (Disciplines.ObjectRec)
      name: Name;
      moduleName: Name;
   END;



TYPE ScanProc = PROCEDURE (args: Arguments);
TYPE ScannerList = POINTER TO ScannerListRec;
TYPE ScannerListRec = RECORD (Disciplines.ObjectRec) END;



TYPE Argument = POINTER TO ArgumentRec;
TYPE ArgumentRec =
   RECORD
      (Disciplines.ObjectRec)
      name: Name;
      short: CHAR;
      type: Type;
      description: Name;
   END;



TYPE ChangeNotification = POINTER TO ChangeNotificationRec;
TYPE ChangeNotificationRec =
   RECORD
      (Events.EventRec)
      args: Arguments;
      arg: Argument;
   END;



CONST lowPriority    = 0;
CONST middlePriority = 1;
CONST highPriority   = 2;
TYPE Priority = INTEGER;



VAR systemScanners: ScannerList; (* predefined scanners *)



CONST cannotReadArgs     = 0;    (* failed to read list of arguments *)
CONST unknownTypeName    = 1;    (* unknown type name encountered *)
CONST twiceDefined       = 2;    (* an argument name has been defined twice *)
CONST cannotWriteArgs    = 3;    (* failed to write list of arguments *)
CONST unknownArgName     = 4;    (* an unknown argument name was given *)
CONST namedErrors = {unknownTypeName, twiceDefined, unknownArgName};
CONST errorcodes         = 5;    (* number of error codes *)
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      errorcode: SHORTINT;
      name: Name; (* defined if errorcode IN namedErrors *)
   END;
VAR errormsg: ARRAY errorcodes OF Events.Message;
VAR error: Events.EventType; 



(* client side *)
PROCEDURE Create(VAR args: Arguments);
PROCEDURE CreateCopyOf(VAR args: Arguments; orig: Arguments);
PROCEDURE Define(args: Arguments; name: ARRAY OF CHAR;
                 short: CHAR; type: Type; description: ARRAY OF CHAR);
PROCEDURE Exists(args: Arguments; name: ARRAY OF CHAR) : BOOLEAN;
PROCEDURE Scan(args: Arguments; scanners: ScannerList);
PROCEDURE GetValue(args: Arguments; name: ARRAY OF CHAR; VAR value: Value);
PROCEDURE SetValue(args: Arguments; name: ARRAY OF CHAR; value: Value);
PROCEDURE GetNotification(args: Arguments; name: ARRAY OF CHAR;
                          VAR eventType: Events.EventType);
PROCEDURE Print(args: Arguments; name: ARRAY OF CHAR; s: Streams.Stream);
PROCEDURE PrintValue(s: Streams.Stream; value: Value);
PROCEDURE ReadValue(s: Streams.Stream; type: Type; VAR value: Value) : BOOLEAN;
PROCEDURE IterateArgs(args: Arguments; VAR it: Iterators.Iterator);
PROCEDURE Seek(args: Arguments; name: ARRAY OF CHAR; VAR arg: Argument);
PROCEDURE String2Type(string: ARRAY OF CHAR) : Type;
PROCEDURE TypeHelp(args: Arguments; type: Type; s: Streams.Stream);
PROCEDURE IterateTypes(VAR it: Iterators.Iterator);
PROCEDURE AssignPrintProc(s: Streams.Stream; type: Type; print: PrintProc);



(* scanner providers *)
PROCEDURE CreateScannerList(VAR list: ScannerList);
PROCEDURE RegisterScanner(scanners: ScannerList; scan: ScanProc;
                           priority: Priority);
PROCEDURE ScanValue(args: Arguments; name: ARRAY OF CHAR;
                    stream: Streams.Stream) : BOOLEAN;



(* type providers *)
PROCEDURE DefineType(type: Type; if: TypeInterface; valtype: Services.Type);

DESCRIPTION

Arguments are name/value pairs with some additional components which are organized in argument collections. Argument values are typed and the types are associated with a set of interface procedures which allow to read and print them. A scanner knows how to retrieve arguments from a specific area (e.g. from the command line). Scan allows to fire a set of scanners for a given argument collection.

Defining a Set of Arguments

The following example shows the creation of an argument list with three arguments:

VAR args: Args.Arguments; (* argument list *)



(* ... *)



Args.Create(args);
Args.Define(args, "copies",  "#", IntArgs.type,    "number of copies");
Args.Define(args, "file",    "f", StringArgs.type, "file to be printed");
Args.Define(args, "printer", "p", StringArgs.type, "name of the printer");

It is possible to give argument default values, or to modify them at a later time by SetValue. In the example above, the number of copies should probably default to 1:

VAR value: Args.Value;



(* ... *)
IntArgs.Create(value, 1); Args.SetValue(args, "copies", value);

CreateCopyOf allows to create a new argument list as clone of the already existing list orig.

Scan allows to call all scanners of a scanner list for a given argument list. All indirectly invoked scanners try to locate settings for the arguments in their area and to assign them. Usually, systemScanners should be given as scanners to Scan. UnixCommandLine, for example, (which is member of systemScanners) would assign letter to file and hp to printer for following command line:

cmdname -p hp -file letter

After calling Scan, it is useful to retrieve values by GetValue. Note that GetValue returns NIL for undefined values. In the example above, the file which is to be printed may be retrieved by:

VAR file: StringArgs.Value; filename: ARRAY 80 OF CHAR;



(* ... *)



Args.GetValue(args, "file", file);
IF file = NIL THEN
   (* a file name was not given anywhere *)
ELSE
   COPY(file.string, filename);
END;

Offering help

PROCEDURE PrintHelpText(s: Streams.Stream; args: Args.Arguments);
   VAR it: Iterators.Iterator; arg: Args.Argument;
BEGIN
   Args.IterateArgs(args, it);
   WHILE Iterators.Yield(it, arg) DO
      Print.S4(s, "%1s %-20s %-8s  %s\n",
         arg.short, arg.name, arg.type.name, arg.description);
   END;
END PrintHelpText;

Print and PrintValue allow to print arbitrary values to the given stream. Following example shows how the values of all defined arguments may be printed:

PROCEDURE PrintValues(s: Streams.Stream; args: Args.Arguments);
   VAR it: Iterators.Iterator; arg: Args.Argument;
BEGIN
   Args.IterateArgs(args, it);
   WHILE Iterators.Yield(it, arg) DO
      Print.S2(s, "%-20s: %-8s = ", arg.name, arg.type.name);
      Args.Print(args, arg.name, s);
      Print.S(s, "\n");
   END;
END PrintValues;

Informations about the supported argument types may be retrieved by TypeHelp, and IterateTypes allows to iterate through all supported types. String2Type allows to convert a (probably user-supplied) type name into a type. NIL is returned if the type name is not known.

Creating a Scanner

Scanners may check the existence of argument names by Exist. It depends usually on the scanner whether missing argument names are considered as an error (of the invoker / user) or not. UnixCommandLine, for example, generates error events for each option named on the command line which is not part of the argument list. Other scanners, however, are less restrictive.

If an argument has been found, it may be read in by ScanValue which, in turn, calls the type-specific read procedure of the argument. Note that these read procedures are expected to interpret field separators and line terminators (see StreamDisciplines) as delimiters. Alternatively, Seek may be called to access the argument directly.

Following example shows a simple implementation of a scanner which takes arguments out of a rc file whose lines have two fields which are separated by a colon. The first field is the name of the parameter and the second the associated value:

PROCEDURE ScanFile(args: Args.Arguments);
   VAR
      s: Streams.Stream;
      fieldseps: Sets.CharSet;
      name: Args.Name;
BEGIN
   (* open the rc file and let s point to it *)
   RelatedEvents.Forward(s, args);
   Sets.InitSet(fieldseps); Sets.InclChar(fieldseps, ":");
   StreamDisciplines.SetFieldSepSet(s, fieldseps);
   WHILE Read.FieldS(s, name) DO
      IF ~Args.Exists(args, name) OR ~Args.ScanValue(args, name, s) THEN
         (* raise an appropriate error event and relate it to args *)
      END;
      Read.LnS(s);
   END;
   Streams.Release(s);
END ScanFile;

Offering an Argument Type

read: PROCEDURE(s: Streams.Stream; VAR value: Value) : BOOLEAN;

read a value from the given stream. Exactly one input field in the sense of StreamDisciplines and Read.FieldS is to be consumed from s. That means that line terminators may not be skipped over and field separators work as delimiters but are to be consumed. This field must be read in completely even if the input does not syntactically conform to the type. But read has to terminate immediately on end of file or in case of errors returned from Streams. TRUE is to be returned if a value has been read successfully.
Note that read is free to update value instead of creating it if value is non-NIL. This could be of interest if value represents a list or set where subsequent read operations add new elements.

print: PROCEDURE(s: Streams.Stream; value: Value);

print the given value (which is guaranteed to be non-NIL and an extension of valtype) in ``readable'' form on the given stream. If multiple lines are needed, Write.IndentS is to be called on the beginning of each new line. Note that the last line must not be terminated.

help: PROCEDURE(s: Streams.Stream);

print some useful help information about the type to s. Note that multiple lines should be avoided here. If they are nevertheless necessary, the conventions of print should be used. This interface procedure is optional and may be set to NIL.

Additionally, type providers should export a simple constructor to allow default values to be set.

ReadValue allows to create a value of the given type and to scan it from s. This may be useful for type constructors whose read interface procedures want to read values of their subtypes.

Internal Links on base of IndirectDisciplines

DIAGNOSTICS

unknownArgName

An unknown argument name was given to ScanValue, GetValue, SetValue, GetNotification, or PrintValue.

twiceDefined

An argument name was given to Define which has been already given earlier for the same argument list.

cannotReadArgs

Args was not able to read an argument list (via PersistentObjects.Read).

cannotWriteArgs

Is returned on write failures during PersistentObjects.Write for argument lists.

unknownTypeName

An unknown argument value type name was encountered during PersistentObjects.Read for an argument list.

Some errors are caught by assertions:

• Define checks the validity of its parameters: name must be non-empty, type must be non-NIL and initialized (by the providing module).
• Scan and ScanValue expect args to be non-NIL.
• DefineType requires that that name is unique and that if, if.read and if.print are non-NIL. Additionally, valtype is checked to be an extension of Args.Value.
• PrintValue requires the value parameter to be an extension of a type which has been given to DefineType.
• A non-NIL scan interface procedure must be given to RegisterScanner.
• SetValue checks that the given value is either NIL or an extension of the type-specific extension of Args.Value.
• A similar test is performed for the values returned by the read interface procedures.

SEE ALSO

BoolArgs

arguments of type BOOLEAN

IntArgs

arguments of type INTEGER

PersistentObjects

input and output of persistent objects

StreamDisciplines

parameterized definition of an input field

StringArgs

arguments of type ARRAY OF CHAR

StrListArgs

arguments of type ARRAY OF ARRAY OF CHAR

UnixCommandLine

scanner for the UNIX command line

AUTHORS

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