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

Ulm's Oberon Library:
CompilerPragmas

NAME

SYNOPSIS

TYPE PragmaContext = POINTER TO PragmaContextRec;
TYPE PragmaContextRec = RECORD (PersistentDisciplines.ObjectRec) END;



(* error events of ProcessArgs: *)
CONST usageError = 0; (* syntax error in pragma definition *)
CONST unknownPragma = 1; (* unknown pragma variable *)
CONST invalidValue = 2; (* invalid pragma value *)
CONST errors = 3;
TYPE ErrorCode = SHORTINT; (* usageError..invalidValue *)
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
      RECORD
         (Events.EventRec)
         errorcode: ErrorCode;
      END;
VAR errormsg: ARRAY errors OF Events.Message;
VAR error: Events.EventType;



PROCEDURE DefineArgs(args: Args.Arguments);
PROCEDURE Create(VAR pcontext: PragmaContext; pragmas: Args.Arguments);



PROCEDURE ProcessArgs(pcontext: PragmaContext;
                      args: Args.Arguments) : BOOLEAN;
PROCEDURE ProcessPragmas(pcontext: PragmaContext;
                         loc: CompilerObjects.Location;
                         text: Streams.Stream);



PROCEDURE LookupPragma(pcontext: PragmaContext;
                       location: CompilerObjects.Location;
                       pname: ARRAY OF CHAR;
                       VAR value: Args.Value);
PROCEDURE LookupFlag(pcontext: PragmaContext;
                     location: CompilerObjects.Location;
                     pname: ARRAY OF CHAR) : BOOLEAN;

DESCRIPTION

DefineArgs is (like Compilers.DefineArgs) to be called shortly after Args.Create by those modules that create reference objects for program text sources (see CompilerSources) to extend the set of compilation options that apply for a particular source. DefineArgs creates a single argument named ``pragma'' (no single-letter abbreviation available) that accepts (using StrListArgs) any number of string arguments of initial pragma settings that are interpreted later at compilation time by ProcessArgs. In addition, the set of accepted values for boolean arguments (see BoolArgs and BoolDisciplines) for args is extended by ``+'' and ``on'' indicating TRUE, and by ``-'' and ``off'' indicating FALSE.

Create is to be called at the initial stage of a compilation process to create a pragma context that,

• supporting the set of pragmas defined by pragmas, and
• beginning with the initial state afterwards defined by ProcessArgs,

allows to set and query source location dependent compilation options. Pragma sets are usually defined by compiler-dependent extensions of this module. See, for example, OberonPragmas that defines the set of pragmas for the Oberon compiler and offers in OberonPragmas.Create an operation which indirectly calls Create with its own pragma set.

ProcessArgs is to be called shortly after Create before ProcessPragmas is called for the first time to accept any initial pragma values given earlier at the creation time of the associated source reference object. Assignments in initial pragma options consists of a variable name, ``='' as delimiter, and a value whose interpretation is delegated to the associated type extension of Args. ProcessArgs returns FALSE and generates error events in case of errors.

ProcessPragmas works like a scanner in the sense of Args that scans text stretches (text at location loc) with pragma settings within sources which, in dependence of the language and the compiler in use, are usually located within comments or specific instructions. Pragma settings are expected to conform to following syntax:

PragmaAssignments =   { PragmaAssignment } .
PragmaAssignment =    "$" (FlagAssignment | FreeAssignment) .
FlagAssignment =      FlagName ("+" | "-" | "=") .
FlagName =            (* just one letter *) .
FreeAssignment =      PragmaVarname = PragmaValue .
PragmaVarname =       (* word with at least two characters *) .
PragmaValue =         NaturalNumber | QuotedValue .
NaturalNumber =       (* sequence of digits 0..9 *)
QuotedValue =         (* any text, enclosed in "..." *)

• the traditional style in conformance to oc and some Zürich compilers with BOOLEAN-valued single-letter options that allow nesting (``='' as flag value undoes the previous flag setting), and
• an open style that supports (on base of Args) arbitrary pragma types where value parsing is delegated to type extensions of Args like BoolArgs, IntArgs, and StringArgs. The open style is required to use pragma variable names with a minimal length of 2 to distinguish it syntactically from the traditional style.

The interpretation of white space within pragma assignments is shared with that of text, see StreamDisciplines.

LookupPragma and LookupFlag permit to lookup pragma values of pname at location within pcontext. LookupPragma returns (like Args.GetValue) NIL in case of undefined values. LookupFlag returns FALSE for undefined flag values.

DIAGNOSTICS

usageError

``='' is missing or the pragma variable name is empty.

unknownPragma

An unknown pragma variable name was encountered.

invalidValue

The pragma value does not conform to the input syntax of the corresponding type extension of Args.

General syntax errors in pragma assignments are silently ignored by ProcessPragmas because not every text stretch presented to ProcessPragmas is necessarily intended as pragma setting. However, once a pragma setting is correctly recognized as such, compiler errors using CompilerErrors are generated for unknown pragma variables, unbalanced pragma settings (in case of the traditional style), and invalid pragma values (in case of the open style).

Error events generated by Args are forwarded to the corresponding pragma context.

SEE ALSO

Args

general abstraction for options and option types.

CompilerErrors

standardized event generation for compilation errors.

CompilerSources

reference objects for program text sources that store the initial set of compilation options including pragmas.

OberonPragmas

defines the pragma set for the Oberon compiler and offers OberonPragmas.Create that indirectly invokes Create.

StrListArgs

list of strings for arguments; used for ``pragma'' compilation option to setup initial pragma values.

BUGS

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