m2c-grammar.gll

/* M2BSK -- EBNF Grammar for Modula-2 R10 Bootstrap Kernel (subset).
 *
 * Copyright (c) 2016, 2023 The Modula-2 Software Foundation
 *
 * Author & Maintainer: Benjamin Kowarsch <org.m2sf>
 *
 * @synopsis
 *
 * Modula-2 BSK is a subset of Modula-2 R10 for bootstrapping a compiler.
 *
 * This document describes the grammar of Modula-2 BSK in EBNF.
 *
 * @repository
 *
 * https://github.com/m2sf/m2bsk
 *
 * @file
 *
 * m2bsk-grammar.gll
 *
 * Grammar of Modula-2 BSK source files.
 *
 */

grammar m2bsk;

/* * *   R e s e r v e d   W o r d s   * * */

reserved
  ALIAS, AND, ARGLIST, ARRAY, BEGIN, CASE, CONST, COPY, DIV, DO, ELSE, ELSIF,
  END, EXIT, FOR, IF, IMPLEMENTATION, IMPORT, IN, INTERFACE, LOOP, MOD, MODULE,
  NEW, NOP, NOT, OCTETSEQ, OF, OPAQUE, OR, POINTER, PROCEDURE, READ, RECORD,
  RELEASE, REPEAT, RETAIN, RETURN, SET, THEN, TO, TYPE, UNQUALIFIED, UNTIL,
  VAR, WHILE, WRITE;

/* ADDRESS, CAPACITY, CAST and NIL are Schroedinger's Tokens */


/* * *   N o n - T e r m i n a l   S y m b o l s   * * */

/* Compilation Unit */

compilationUnit :=
  interfaceModule | implementationModule | programModule
  ;


/*** Interface Module Syntax ***/

/* Interface Module */

interfaceModule :=
  INTERFACE MODULE moduleIdent ';'
  import* declaration* END moduleIdent '.'
  ;

/* Module Identifier */

alias moduleIdent = StdIdent ;


/* Import */

import :=
  IMPORT libIdent reExport? ( ',' libIdent reExport? )* ';'
  ;

/* Library Identifier */

alias libIdent = StdIdent ;

alias reExport = '+' ;


/* Public Definition or Declaration */

declaration :=
  CONST ( constDefinition ';' )+ |
  TYPE ( typeDefinition ';' )+ |
  VAR ( varDefinition ';' )+ |
  procDeclaration ';' |
  toDoList ';'
  ;


/* Constant Definition */

constDefinition :=
  constBinding?  simpleConstDefinition
  ;
  
/* Constant Binding */

constBinding :=
  '[' constBindableIdent ']'
  ;

/* Constant Bindable Identifier */

.constBindableIdent := Ident=("COLLATION" | "TLIMIT") ;


/* Simple Constant Definition */

simpleConstDefinition :=
  ident ( ':' typeIdent )? '=' constExpression
  ;


/* Identifier */

alias ident = StdIdent ;


/* Type Identifier */

alias typeIdent = qualident ;


/* Qualified Identifier */

qualident :=
  StdIdent ( '.' StdIdent )*
  ;


/* Constant Expression */

alias constExpression = expression ;


/* Type Definition */

typeDefinition :=
  ident '=' publicType
  ;

/* Public Type Constructor */

publicType :=
  aliasType | derivedType | subrangeType | enumType | setType |
  arrayType | recordType | pointerType | opaqueType | procedureType
  ;


/* Alias Type Constructor */

aliasType :=
  ALIAS OF typeIdent
  ;

/* Derived Type */

alias derivedType = typeIdent ;


/* Subrange Type Constructor */

subrangeType :=
  constRange OF countableType
  ;

/* Constant Range */

alias constRange = valueRange ;

/* Value Range */

valueRange :=
  '[' lowerBound '..' upperBound ']'
  ;

/* Lower Bound  */

alias lowerBound = constExpression ;

/* Upper Bound */

alias upperBound = constExpression ;

/* Countable Type */

alias countableType = typeIdent ;


/* Enumeration Type Constructor */

enumType :=
  '(' ( '+' enumTypeToExtend ',' )? identList ')'
  ;

/* Enumeration Type To Extend */

alias enumTypeToExtend = enumTypeIdent ;

/* Enumeration Type Identifier */

alias enumTypeIdent = typeIdent ;


/* Identifier List */

identList :=
  StdIdent ( ',' StdIdent )*
  ;


/* Set Type Constructor */

setType :=
  SET OF enumTypeIdent
  ;


/* Array Type Constructor */

arrayType :=
  ARRAY valueCount OF typeIdent
  ;

/* Value Count */

alias valueCount = constExpression ;


/* Record Type Constructor */

recordType :=
  RECORD ( '(' recTypeToExtend ')' )?
  fieldList ( ';' fieldList )* END
  ;


/* Record Type To Extend */

recTypeToExtend :=
  typeIdent | NIL
  ;


/* Field List */

alias fieldList = varDefinition ;


/* Pointer Type Constructor */

pointerType :=
  POINTER TO typeIdent
  ;


/* Opaque Type Declarator */

opaqueType :=
  OPAQUE ( '[' allocSize ']' )?
  ;

/* Allocation Size */

alias allocSize = constExpression ;


/* Procedure Type Constructor */

procedureType :=
  PROCEDURE ( '(' formalType ( ';' formalType )* ')' )? ( ':' returnedType )?
  ;


/* Formal Type */

formalType :=
  ( CONST | VAR )? nonAttrFormalType
  ;

/* Non-Attributed Formal Type */

nonAttrFormalType :=
  simpleFormalType | castingFormalType | variadicFormalType
  ;

/* Returned Type */

alias returnedType = typeIdent ;


/* Simple Formal Type */

simpleFormalType :=
  ( ARRAY OF )? typeIdent
  ;


/* Casting Formal Type */

castingFormalType :=
  CAST ( OCTETSEQ | ADDRESS )
  ;

/* Casting Syntax enabled by import of module UNSAFE */


/* Variadic Formal Type */

variadicFormalType :=
  ARGLIST OF simpleFormalType
  ;


/* Variable Definition */

varDefinition :=
  identList ':' ( typeIdent | anonType )
  ;

.anonType :=
  subrangeType | arrayType | procedureType
  ;


/* Procedure Header */

procedureHeader :=
  procBinding? procedureSignature
  ;
  
/* Procedure Binding */

procBinding :=
  '[' bindingSpecifier ']'
  ;

/* Binding Specifier */

.bindingSpecifier :=
  NEW ( ARGLIST | Ident=CAPACITY )? | RETAIN | RELEASE |
  READ NEW? | WRITE formatFlag? | procBindableIdent
  ;

/* Format Flag */

alias formatFlag = '#' ;

/* Procedure bindable identifiers */

.procBindableIdent :=
  Ident = (
    "ALLOC" | "APPEND" | "INSERT" | "ATINSERT" | "ATREMOVE" | "ATSTORE" |
    "ATVALUE" | "COUNT" | "DEALLOC" | "FIRST" | "LAST" | "LENGTH" | "NEXT" |
    "PREV" | "REMOVE" | "STDIN" | "STDOUT" | "STORE" | "SUCC" | "VALUE" )
  ;


/* Procedure Signature */

.procedureSignature :=
  ident ( '(' formalParams ( ';' formalParams )* ')' )? ( ':' returnedType )?
  ;


/* Formal Parameters */

formalParams :=
  ( CONST | VAR )? identList ':' nonAttrFormalType
  ;


/*** Implementation and Program Module Syntax ***/

/* Program Module */

programModule :=
  MODULE moduleIdent ';'
  privateImport* block moduleIdent '.'
  ;


/* Private Import */

privateImport :=
  IMPORT libIdent ( ',' libIdent )* ';'
  ;


/* Block */

block :=
  definition*
  BEGIN statementSequence END
  ;


/* Definition */

definition :=
  CONST ( constDefinition ';' )+ |
  TYPE ( pgmTypeDefinition ';' )+ |
  VAR ( varDefinition ';' )+ |
  procedureDefinition ';' |
  aliasDefinition ';' |
  toDoList ';'
  ;


/* Program Type Definition */

pgmTypeDefinition :=
  ident '=' programType
  ;
  
/* Intra-Program Type Constructor */

programType :=
  aliasType | derivedType | subrangeType | enumType | setType |
  arrayType | recordType | pointerType | procedureType
  ;

/* Procedure Definition */

procedureDefinition :=
  procedureHeader ';' block ident ';'
  ;


/* Implementation Module */

implementationModule :=
  IMPLEMENTATION MODULE moduleIdent ';'
  privateImport* privateBlock moduleIdent '.'
  ;


/* Private Block */

privateBlock :=
  privateDefinition*
  ( BEGIN statementSequence )? END
  ;


/* Private Definition */

privateDefinition :=
  CONST ( constDefinition ';' )+ |
  TYPE ( impTypeDefinition ';' )+ |
  VAR ( varDefinition ';' )+ |
  procedureHeader ';' block ident ';' |
  aliasDefinition ';' |
  toDoList ';'
  ;


/* Implementation Type Definition */

impTypeDefinition :=
  ident '=' implementationType
  ;
  
/* Intra-Implementation Type Constructor */

implementationType :=
  aliasType | derivedType | subrangeType | enumType | setType |
  arrayType | recordType | privatePointerType | procedureType
  ;  


/* Private Pointer Type */

privatePointerType :=
  POINTER TO ( determinateTarget | indeterminateTarget )
  ;

/* Determinate Target */

alias determinateTarget = typeIdent ;


/* Indeterminate Target */

indeterminateTarget :=
  RECORD ( fieldList ';' )* indeterminateField END
  ;

/* Indeterminate Field */

indeterminateField :=
  '+' ident ':' ARRAY capacityField OF typeIdent 
  ;

/* Capacity Field */

alias capacityField = ident ;


/* Alias Definition */

aliasDefinition :=
  UNQUALIFIED nameSelector ( ',' nameSelector )*
  ;

/* Name Selector */

nameSelector :=
  qualident wildcard?
  ;

/* Wildcard */

alias wildcard = '.*' ;


/* Statement Sequence */

statementSequence :=
  statement ( ';' statement )*
  ;


/* Statement */

statement :=
  memMgtOperation | updateOrProcCall | returnStatement |
  copyStatement | readStatement | writeStateent | ifStatement |
  caseStatement | loopStatement | whileStatement | repeatStatement |
  forStatement | toDoList | EXIT | NOP
  ;


/* Memory Management Operation */

.memMgtOperation :=
  newStatement | retainStatement | releaseStatement
  ;

newStatement :=
  NEW designator ( ':=' structuredValue | CAPACITY expression )?
  ;

retainStatement :=
  RETAIN designator
  ;

releaseStatement :=
  RELEASE designator
  ;


/* Update Or Procedure Call */

updateOrProcCall :=
  designator -> ( IncOrDecSuffix | '(' expressionList ')' )? |
  targetDesignator -> ':=' expression
  ;

/* Increment Or Decrement Suffix */

.IncOrDecSuffix := '++' | '--' ;


/* RETURN Statement */

returnStatement :=
  RETURN expression?
  ;


/* COPY Statement */

copyStatement :=
  COPY targetDesignator ':=' expression
  ;


/* READ Statement */

readStmt :=
  READ ( '@' chan ':' )?
  inputArg ( ',' inputArg )*
  ;

/* channel */

alias chan = designator ;

/* Input Argument */

inputArg := NEW? designator ;


/* WRITE Statement */

writeStmt :=
  WRITE ( '@' chan ':' )?
  outputArgs ( ',' outputArgs )*
  ;

/* Output Arguments */

outputArgs :=
  formattedArgs | unformattedArg
  ;

/* Formatted Arguments */

formattedArgs :=
  '#' '(' fmtStr, unformattedArgs ')'
  ;

/* Format String */

alias fmtStr = expression ;

/* Unformatted Argument */

alias unformattedArg = expression ;

/* Unformatted Arguments */

alias unformattedArgs = expressionList ;


/* IF Statement */

ifStatement :=
  IF boolExpression THEN statementSequence
  ( ELSIF boolExpression THEN statementSequence )*
  ( ELSE statementSequence )?
  END
  ;

/* Boolean Expression */

alias boolExpression = expression ;


/* CASE Statement */

caseStatement :=
  CASE expression OF ( '|' case )+ ( ELSE statementSequence )? END
  ;

/* Case */

case :=
  caseLabels ( ',' caseLabels )* : statementSequence
  ;

/* Case Labels */

caseLabels :=
  constExpression ( .. constExpression )?
  ;


/* LOOP Statement */

loopStatement :=
  LOOP statementSequence END
  ;


/* WHILE Statement */

whileStatement :=
  WHILE boolExpression DO statementSequence END
  ;


/* REPEAT Statement */

repeatStatement :=
  REPEAT statementSequence UNTIL boolExpression
  ;


/* FOR Statement */

forStatement :=
  FOR forLoopVariants IN iterableExpr DO statementSequence END
  ;

/* FOR Loop Variants */

forLoopVariants :=
  accessor descender? ( ',' value )?
  ;

/* Accesor and Value */

alias accessor, value = StdIdent ;


/* Descender */

alias descender = '--' ;


/* Iterable Expression */

iterableExpr :=
  subrangeType | qualident valueRange?
  ;


/* Designator */

designator :=
  qualident ( derefTail | subscriptTail )?
  ;


/* Dereferenced Designator Tail */

derefTail :=
  deref ( '.' designator | subscriptTail )?
  ;
  
  
/* Subscripted Designator Tail */

subscriptTail :=
  '[' expression ']' ( '.' designator | derefTail )?
  ;


/* Target Designator */

targetDesignator :=
  qualident ( derefTargetTail | bracketTargetTail )?
  ;


/* Dereferenced Target Designator Tail */

derefTargetTail :=
  deref ( '.' targetDesignator | bracketTargetTail )?
  ;


/* Bracketed Target Designator Tail */

bracketTargetTail :=
  '[' expression
  ( ']' ( '.' targetDesignator | derefTargetTail )? | '..' expression? ']' )?
  ;
  

/* Dereference */

deref := 
  ( '^' )+
  ;


/* Expression List */

expressionList :=
  expression ( ',' expression )*
  ;


/* Expression */

expression :=
  simpleExpression ( OperL1 simpleExpression )?
  ;

/* Level-1 Operator */

.OperL1 :=
  '=' | '#' | '<' | '<=' | '>' | '>=' | '==' | IN
  ;


/* Simple Expression */

simpleExpression :=
  term ( OperL2 term )* | '-' factor
  ;

/* Level-2 Operator */

.OperL2 :=
  '+' | '-' | OR | ConcatOp | SetDiffOp
  ;

/* Concatenation Operator */

alias ConcatOp = '&' ;

/* Set Difference Operator */

alias SetDiffOp = '\' ;


/* Term */

term :=
  simpleTerm ( OperL3 simpleTerm )*
  ;

/* Level-3 Operator */

.OperL3　 :=
  '*' | '/' | DIV | MOD | AND
  ;


/* Simple Term */

simpleTerm :=
  NOT? factor
  ;


/* Factor */

factor :=
  simpleFactor ( TypeConvOp typeIdent )?
  ;

/* Type Conversion Operator */

alias TypeConvOp = '::' ;


/* Simple Factor */

simpleFactor :=
  NumberLiteral | StringLiteral |
  structuredValue | sourceDesignator | '(' expression ')'
  ;

/* Source Designator */

sourceDesignator :=
  qualident ( functionCallTail | derefSourceTail | bracketSourceTail )?
  ;


/* Function Call Tail */

functionCallTail :=
  '(' expressionList? ')'
  ;


/* Dereferenced Source Designator Tail */

derefSourceTail :=
  deref ( '.' sourceDesignator | functionCallTail | bracketSourceTail )?
  ;


/* Bracketed Source Designator Tail */

bracketSourceTail :=
  '[' expression
  ( ']' ( '.' sourceDesignator | functionCallTail | derefSourceTail )? |
    '..' expression ']' )?
  ;


/* Structured Value */
 structuredValue :=
   '{' ( valueComponent ( ',' valueComponent )* | '*' ) '}'
   ;

/* Value Component */

valueComponent :=
  constExpression ( '..' constExpression )? |
  runtimeExpression
  ;

/* Runtime Expression */

alias runtimeExpression = expression ;


/* Technical Debt Management */

toDoList :=
  TO DO ( trackingRef? taskToDo ( ';' taskToDo )* END )?
  ;

/* Issue Tracking Reference */

trackingRef :=
  '(' issueId ( ',' severity ',' description )?  ')'
  ;

/* TO DO Task */

taskToDo :=
  description ( ',' estimatedTime timeUnit )?
  ;


/* Issue ID, Severity, Estimated Time */

alias issueId, severity, estimatedTime = wholeNumber ;


/* Time Unit */

alias timeUnit = StdIdent ;

/* By convention timeUnit identifiers should be
   w for weeks, d for days and h for hours */

/* Description */

alias description = StringLiteral ;

/* Whole Number */

alias wholeNumber = NumberLiteral ;



/* * *   T e r m i n a l   S y m b o l s   * * */

/* Identifier */

StdIdent :=
  Letter ( Letter | Digit )*
  ;

/* Letter Or Digit */

.LetterOrDigit := Letter | Digit ;


/* Pervasive */

.Pervasive := ( 'A' .. 'Z' )+ Digit? ;

/* Primitive */

.Primitive := ( 'A' .. 'Z' )+ ;


/* Number Literal */

NumberLiteral :=
  '0' ( RealNumberTail | 'b' Base2DigitSeq | ( 'x' | 'u' ) Base16DigitSeq )? |
  ( '1' .. '9' ) DecimalNumberTail?
  ;

/* Decimal Number Tail */

.DecimalNumberTail :=
  DigitSep? DigitSeq RealNumberTail?
  ;

/* Real Number Tail */

.RealNumberTail :=
  '.' DigitSeq ( 'e' ( '+' | '-' )? DigitSeq )?
  ;

/* Digit Sequence */

.DigitSeq :=
  Digit+ ( DigitSep Digit+ )*
  ;

/* Base-2 Digit Sequence */

.Base2DigitSeq :=
  Base2Digit+ ( DigitSep Base2Digit+ )*
  ;

/* Base-16 Digit Sequence */

.Base16DigitSeq :=
  Base16Digit+ ( DigitSep Base16Digit+ )*
  ;

/* Digit Separator */

alias DigitSep = "'" ;

/* Digit */

.Digit := '0' .. '9' ;

/* Base-2 Digit */

.Base2Digit := '0' | '1' ;

/* Base-16 Digit */

.Base16Digit := Digit | ( 'A' .. 'F' ) ;


/* String Literal */

StringLiteral :=
  SingleQuotedString | DoubleQuotedString
  ;

/* Single-Quoted String Literal */

.SingleQuotedString :=
  "'" ( QuotableCharacter | '"' )* "'"
  ;

/* Double-Quoted String Literal */

.DoubleQuotedString :=
  '"' ( QuotableCharacter | "'" )* '"'
  ;

/* Quotable Character */

.QuotableCharacter :=
  Digit | Letter | Space | NonAlphaNumQuotable | EscapedCharacter
  ;

/* Letter */

.Letter := 'a' .. 'z' | 'A' .. 'Z' ;

/* Whitespace */

.Space := 0u20 ;

/* Non-Alphanumeric Quotable Character */

.NonAlphaNumQuotable :=
  '!' | '#' | '$' | '%' | '&' | '(' | ')' | '*' | '+' | ',' |
  '-' | '.' | '/' | ':' | ';' | '<' | '=' | '>' | '?' | '@' |
  '[' | '\' | ']' | '^' | '_' | '`' | '{' | '|' | '}' | '~'
  ;

/* Escaped Character */

.EscapedCharacter :=
  '\' ( 'n' | 't' | '\' )
  ;


/* * *   I g n o r e   S y m b o l s   * * */

/* Whitespace */

Whitespace :=
  Space | Tabulator
  ;

/* Tabulator */
.Tabulator := 0u9 ;


/* Line Comment */

LineComment :=
  '!' CommentCharacter* EndOfLine
  ;


/* Block Comment */

BlockComment :=
  '(*' ( CommentCharacter | BlockComment | EndOfLine )* '*)'
  ;

/* Comment Character */

.CommentCharacter :=
  Digit | Letter | Whitespace | NonAlphaNumQuotable | '\' | "'" | '"'
  ; /* greedy */


/* End of Line Marker */

EndOfLine :=
  LF | CR ( LF )?
  ;

/* ASCII LF */

.LF := 0uA ;

/* ASCII CR */

.CR := 0uD ;


/* * *   P r a g m a s   * * */

/* INLINE Pragma */

inlinePragma := '<*' INLINE '*>' ;


/* DEPRECATED Pragma */

deprecatedPragma := '<*' DEPRECATED '*>' ;


/* PRIVATETO Pragma */

privatetoPragma := '<*' PRIVATETO '=' identList '*>' ;


/* FFI Pragma */

ffiPragma := '<*' FFI '=' ( "C" | "CLR" | "JVM" ) '*>' ;


/* FFIDENT Pragma */

ffidentPragma := '<*' FFIDENT '=' StringLiteral '*>' ;


/* Implementation Defined Pragma */

implDefPragma :=
  '<*' ( implPrefix '.' )? pragmaSymbol ( '=' constExpr )? '|' ctMsgMode '*>' ;


/* Compile Time Message Mode */

.ctMsgMode := INFO | WARN | ERROR | FATAL ;

/* Implementation Prefix and Pragma Symbol */

implPrefix, pragmaSymbol = <implementation-defined> ;

/* Implementation defined implPrefix and pragmaSymbol follow the syntax of StdIdent */



/* * *  O p t i o n a l  * * */

/* Recommended Debugging Aid */

/* Not part of the language specification */

/* Disabled Code Section */

DisabledCodeSection :=
  '?<' /* strictly in first column of a line */
  ( AnyPrintable | BlockComment | EndOfLine )*
  '>?' /* strictly in first column of a line */
  ;

.AnyPrintable := 0u20 .. 0u7E ; /* greedy */

endg m2bsk.

/* END OF FILE */