Feature Set Of Initial Version

Overview

The M2PP preprocessor works by reading a template file which it expands into an output file.

The initial version implements the following reduced feature set:

• template comments
• simple placeholder expansion
• predefined placeholders for version and filenames
• two built-in directives IMPCAST and TCAST for dialect independent casting

These features will now be described in further detail below.

Template Comments

Template comments are non-nestable block comments, denoted by a left-most opening delimiter /* and a right-most closing delimiter */. Any characters may appear in between the delimiters. Template comments are not copied into the output file.

templateComment :=
  '/*' printableCharacter* '*/'
  ;

Simple Placeholder Expansion

Placeholders are denoted by leading and trailing ## delimiters. An identifier must appear in between the delimiters. A placeholder whose identifier has been defined is replaced in the output with its definition.

placeholder :=
  '##' StdIdent '##'
  ;

Definitions for placeholders may be passed as command line arguments to M2PP.

m2pp infile=Stack.gen.def outfile=RealStack.def stackSize=100 entryType=REAL

Placeholders infile and outfile are always defined by M2PP with the names of the template file and the output file respectively. Any other placeholder definitions are optional.

Definition of the Output Version

Placeholders ver, Ver and VER have special meanings. If any one of them is defined, the all-lowercase representation of the definition string is assigned to placeholder ver, its capitalised representation is assigned to placeholder Ver and its all-uppercase representation is assigned to placeholder VER.

Sample Expansion

The following example illustrates a template expansion.

Given a template file String.gen.def ...

(*!m2##ver##*)(* Copyright (C) 2017 Modula-2 Software Foundation *)

DEFINITION MODULE String; (* ##VER## version *)

...

invoking M2PP with the following arguments ...

m2pp infile=String.gen.def outfile=String.iso.def ver=iso

will generate the following output file String.iso.def ...

(*!m2iso*)(* Copyright (C) 2017 Modula-2 Software Foundation *)

DEFINITION MODULE String; (* ISO version *)

...

Built-in Directive IMPCAST

Directive IMPCAST writes an ISO specific import of CAST to the output if ver matches iso. Otherwise it will be ignored and produces no output.

impcastDirective :=
  '(*?' IMPCAST '*)'
  ;

Example

the following template source fragment

(*?IMPCAST*)

will generate the following output if ver matches iso

FROM SYSTEM IMPORT CAST;

Built-in Directive TCAST

Directive TCAST writes a PIM or ISO specific cast to the output, depending on the value of ver.

tcastDirective :=
  '(*?' TCAST '(' typeIdent ',' valueIdent ')' '*)'
  ;

Example

the following template source fragment

CONST NilString = (*?TCAST(StringT, NIL)*);

will generate the following output,

if ver matches pim

CONST NilString = StringT(NIL);

if ver matches iso

CONST NilString = CAST(StringT, NIL);