m2bsk-grammar.gll

/* M2BSK -- EBNF Grammar for Modula-2 R10 Bootstrap Kernel (subset).
 *
 * Copyright (c) 2016, 2020 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, DEFINITION, DIV, DO,
  ELSE, ELSIF, END, EXIT, FOR, IF, IMPLEMENTATION, IMPORT, IN, 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 :=
  definitionModule | implementationModule | programModule
  ;


/*** Definition Module Syntax ***/

/* Definition Module */

definitionModule :=
  DEFINITION MODULE moduleIdent ';'
  import* definition* END moduleIdent '.'
  ;

/* Module Identifier */

alias moduleIdent = StdIdent ;


/* Import */

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

/* Library Identifier */

alias libIdent = StdIdent ;

alias reExport = '+' ;


/* Definition */

definition :=
  CONST ( constDefinition ';' )+ |
  TYPE ( typeDefinition ';' )+ |
  VAR ( identList ':' typeIdent ';' )+ |
  procedureHeader ';' |
  toDoList ';'
  ;


/* Constant Definition */

constDefinition :=
  constBinding | constDeclaration
  ;
  
constBinding :=
  '[' ( COLLATION | TLIMIT ) ']' '=' constExpression ;


/* Constant Declaration */

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


/* Identifier */

alias ident = StdIdent ;


/* Constant Expression */

alias constExpression = expression ;


/* Type Definition */

typeDefinition :=
  ident '='
    ( aliasType | derivedType | subrangeType | enumType | setType |
      arrayType | recordType | pointerType | opaqueType | procedureType )
  ;


/* Alias Type */

aliasType :=
  ALIAS OF typeIdent
  ;

/* Type Identifier */

alias typeIdent = qualident ;


/* Qualified Identifier */

qualident :=
  StdIdent | Qualident
  ;


/* Derived Type */

alias derivedType = typeIdent ;


/* Subrange Type */

subrangeType :=
  constRange OF countableType
  ;

/* Constant Range */

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

/* Lower Bound  */

alias lowerBound = constExpression ;

/* Upper Bound */

alias upperBound = constExpression ;

/* Countable Type */

alias countableType = typeIdent ;


/* Enumeration Type */

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

/* Enumeration Type To Extend */

alias enumTypeToExtend = enumTypeIdent ;

/* Enumeration Type Identifier */

alias enumTypeIdent = typeIdent ;


/* Identifier List */

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


/* Set Type */

setType :=
  SET OF enumTypeIdent
  ;


/* Array Type */

arrayType :=
  ARRAY valueCount OF typeIdent
  ;

/* Value Count */

alias valueCount = constExpression ;


/* Record Type */

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


/* Record Type To Extend */

recTypeToExtend :=
  typeIdent | NIL
  ;


/* Field List */

fieldList :=
  identList ':' ( typeIdent | arrayType | subrangeType | procedureType )
  ;


/* Pointer Type */

pointerType :=
  POINTER TO typeIdent
  ;


/* Opaque Type */
opaqueType :=
  OPAQUE ( '[' allocSize ']' | POINTER )?
  ;

/* Allocation Size */

alias allocSize = constExpression ;


/* Procedure Type */

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 )
  ;

/* Syntax enabled by import of module UNSAFE */


/* Variadic Formal Type */

variadicFormalType :=
  ARGLIST OF simpleFormalType
  ;


/* Procedure Header */

procedureHeader :=
  PROCEDURE ( '[' bindingSpecifier ']' )? procedureSignature
  ;
  
/* Binding Specifier */

bindingSpecifier :=
  NEW ( argListFlag | capacityFlag )? | RETAIN | RELEASE |
  READ allocFlag? | WRITE formatFlag? | bindableIdent
  ;

/* Flags */

alias argListFlag = '+' ;

alias capacityFlag = '*' ;

alias allocFlag = '*' ;

alias formatFlag = '#' ;


/* Bindable Identifier */

.bindableIdent :=
  Pervasive | Primitive
  ;


/* 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 :=
  declaration*
  BEGIN statementSequence END
  ;


/* Implementation Module */

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


/* Possibly Empty Block */

possiblyEmptyBlock :=
  declaration*
  ( BEGIN statementSequence )? END
  ;


/* Declaration */

declaration :=
  CONST ( constDeclaration ';' )+ |
  TYPE ( typeDeclaration ';' )+ |
  VAR ( varDeclaration ';' )+ |
  procedureHeader ';' block ident ';' |
  aliasDeclaration ';' |
  toDoList ';'
  ;

/* Type Declaration */

typeDeclaration :=
  ident '='
    ( aliasType | derivedType | subrangeType | enumType | setType |
      arrayType | recordType | octetSeqType | privatePointerType |
      procedureType )
  ;


/* Octet Sequence Type */

octetSeqType :=
  OCTETSEQ '[' valueCount ']'
  ;


/* 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 ;


/* Variable Declaration */

alias varDeclaration = fieldList ;


/* Alias Declaration */

aliasDeclaration :=
  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 or YIELD 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, unformattedArg ')'
  ;

/* Format String */

alias fmtStr = expression ;

/* Unformatted Argument */

alias unformattedArg = expression ;


/* 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 :=
  collectionOrType valueRange?
  ;

/* Collection or Type */

alias collectionOrType = qualident ;


/* Value Range */

valueRange :=
  '[' firstValue '..' lastValue ']'
  ;

/* First and Last Value */

alias firstValue, lastValue = expression ;


/* 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 ;


/* Qualified Identifier */

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


/* 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 */