syntax.tex

\chapter{Modelica Concrete Syntax}\label{modelica-concrete-syntax}

\section{Lexical conventions}\label{lexical-conventions}

The following syntactic metasymbols are used (extended BNF):
\begin{center}
\begin{tabular}{c l}
\hline
\tablehead{Syntax} & \tablehead{Description}\\
\hline
\hline
\lstinline[language=grammar]![ $\ldots$ ]! & Optional\\
\lstinline[language=grammar]!{ $\ldots$ }! & Repeat zero or more times\\
\lstinline[language=grammar]!$\ldots$ | $\ldots$! & Alternatives\\
\lstinline[language=grammar]!"$\mathit{text}$"! & The $\mathit{text}$ is treated as a single token (no white-space between any characters)\\
\hline
\end{tabular}
\end{center}

The following lexical units are defined:
% Beware that the first lines of the lexing rules below are duplicated in \cref{identifiers}, and must be kept in sync.
\begin{lstlisting}[language=grammar]
IDENT = NON-DIGIT { DIGIT | NON-DIGIT } | Q-IDENT
Q-IDENT = "'" { Q-CHAR | S-ESCAPE } "'"
NON-DIGIT = "_" | letters "a" $\ldots$ "z" | letters "A" $\ldots$ "Z"
DIGIT = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
Q-CHAR = NON-DIGIT | DIGIT | "!" | "#" | "$\mbox{\textdollar}$" | "%" | "&" | "(" | ")"
   | "*" | "+" | "," | "-" | "." | "/" | ":" | ";" | "<" | ">" | "="
   | "?" | "@" | "[" | "]" | "^" | "{" | "}" | "|" | "~" | " " | """
S-ESCAPE = "\'" | "\"" | "\?" | "\\"
   | "\a" | "\b" | "\f" | "\n" | "\r" | "\t" | "\v"
STRING = """ { S-CHAR | S-ESCAPE } """
S-CHAR = see below
UNSIGNED-INTEGER = DIGIT { DIGIT }
UNSIGNED-REAL =
   UNSIGNED-INTEGER  "." [ UNSIGNED-INTEGER ]
   | UNSIGNED_INTEGER [ "." [ UNSIGNED_INTEGER ] ]
     ( "e" | "E" ) [ "+" | "-" ] UNSIGNED-INTEGER
   | "."  UNSIGNED-INTEGER [ ( "e" | "E" ) [ "+" | "-" ] UNSIGNED-INTEGER ]
\end{lstlisting}
\lstinline[language=grammar]!S-CHAR! is any member of the Unicode character set (\url{http://www.unicode.org}; see \cref{mapping-package-class-structures-to-a-hierarchical-file-system} for storing as UTF-8 on files) except double-quote `"', and backslash `\textbackslash{}'.

For identifiers the redundant escapes (`\lstinline!\?!' and `\lstinline!\"!') are the same as the corresponding non-escaped variants (`\lstinline!?!' and '\lstinline!"!').
The single quotes are part of an identifier.
For example, the identifiers \lstinline!'x'! and \lstinline!x! are different.

Note:
\begin{itemize}
\item
  White-space and comments can be used between separate lexical units and/or symbols, and also separates them. Each lexical unit will consume the maximum number of characters from the input stream.
  White-space and comments cannot be used inside other lexical units, except for \lstinline[language=grammar]!STRING! and \lstinline[language=grammar]!Q-IDENT! where they are treated as part of the \lstinline[language=grammar]!STRING! or \lstinline[language=grammar]!Q-IDENT! lexical unit.
\item
  Concatenation of string literals requires a binary expression.
  For example, \lstinline!"a" + "b"! evaluates to \lstinline!"ab"!.
  There is no support for the C/C++ style of concatenating adjacent string literal tokens (for example, \lstinline[language=C]!"a" "b"! becoming \lstinline[language=C]!"ab"!).
\item
  Modelica uses the same comment syntax as C++ and Java (i.e., \lstinline!//! signals the start of a line comment and \lstinline!/* $\ldots$ */! is a multi-line comment); comments may contain any Unicode character.
  Modelica also has structured comments in the form of annotations and string comments.
\item
  Each \lstinline[language=grammar]!description-string! or string in annotations (that is, a \lstinline[language=grammar]!STRING! with production \lstinline[language=grammar]!annotation-clause! in the grammar) may contain any member of the Unicode character set.
  All other strings have to contain only the subset of Unicode characters identical with the 7-bit US-ASCII character set.
  \begin{nonnormative}
  As a consequence, operators like `\lstinline!>!' or `\lstinline!<!', and external functions only operate on ASCII strings and not on Unicode-strings.
  Within a \lstinline[language=grammar]!description-string! the tags \lstinline!<HTML>! and \lstinline!</HTML>! or \lstinline!<html>! and \lstinline!</html>! define optionally begin and end of content that is HTML encoded.
  \end{nonnormative}
\item
  In the grammar, keywords of the Modelica language are highlighted with color, for example, \lstinline[language=grammar]!equation!.
\item
  Productions use hyphen as separator both in the grammar and in the text.
  (Previously the grammar used underscore.)
\end{itemize}

\section{Grammar}\label{grammar}

\subsection{Stored Definition -- Within}\label{stored-definition-within}

\begin{lstlisting}[language=grammar]
stored-definition :
   [ within [ name ] ";" ]
   { [ final ] class-definition ";" }
\end{lstlisting}

\subsection{Class Definition}\label{class-definition}

\begin{lstlisting}[language=grammar]
class-definition :
   [ encapsulated ] class-prefixes class-specifier

class-prefixes :
   [ partial ]
   ( class
     | model
     | [ operator ] record
     | block
     | [ expandable ] connector
     | type
     | package
     | [ pure | impure ] [ operator ] function
     | operator
   )

class-specifier :
   long-class-specifier | short-class-specifier | der-class-specifier

long-class-specifier :
   IDENT description-string composition end IDENT
   | extends IDENT [ class-modification ] description-string composition
     end IDENT

short-class-specifier :
   IDENT "=" base-prefix type-specifier [ array-subscripts ]
   [ class-modification ] description
   | IDENT "=" enumeration "(" ( [ enum-list ] | ":" ) ")" description

der-class-specifier :
   IDENT "=" der "(" type-specifier "," IDENT { "," IDENT } ")" description

base-prefix :
   [ input | output ]

enum-list :
   enumeration-literal { "," enumeration-literal }

enumeration-literal :
   IDENT description

composition :
   element-list
   { public element-list
     | protected element-list
     | equation-section
     | algorithm-section
   }
   [ external [ language-specification ]
     [ external-function-call ] [ annotation-clause ] ";"
   ]
   [ annotation-clause ";" ]

language-specification :
   STRING

external-function-call :
   [ component-reference "=" ]
   IDENT "(" [ expression-list ] ")"

element-list :
   { element ";" }

element :
   import-clause
   | extends-clause
   | [ redeclare ]
     [ final ]
     [ inner ] [ outer ]
     ( class-definition
       | component-clause
       | replaceable ( class-definition | component-clause )
         [ constraining-clause description ]
     )

import-clause :
   import
   ( IDENT "=" name
     | name [ ".*" | "." ( "*" | "{" import-list "}" ) ]
   )
   description

import-list :
   IDENT { "," IDENT }
\end{lstlisting}

\subsection{Extends}\label{extends}

\begin{lstlisting}[language=grammar]
extends-clause :
   extends type-specifier [ class-modification ] [ annotation-clause ]

constraining-clause :
   constrainedby type-specifier [ class-modification ]
\end{lstlisting}

\subsection{Component Clause}\label{component-clause}

\begin{lstlisting}[language=grammar]
component-clause :
   type-prefix type-specifier [ array-subscripts ] component-list

type-prefix :
   [ flow | stream ]
   [ discrete | parameter | constant ]
   [ input | output ]

component-list :
   component-declaration { "," component-declaration }

component-declaration :
   declaration [ condition-attribute ] description

condition-attribute :
   if expression

declaration :
   IDENT [ array-subscripts ] [ modification ]
\end{lstlisting}

\subsection{Modification}\label{modification}

\begin{lstlisting}[language=grammar]
modification :
   class-modification [ "=" expression ]
   | "=" expression
   | ":=" expression

class-modification :
   "(" [ argument-list ] ")"

argument-list :
   argument { "," argument }

argument :
   element-modification-or-replaceable
   | element-redeclaration

element-modification-or-replaceable :
   [ each ] [ final ] ( element-modification | element-replaceable )

element-modification :
   name [ modification ] description-string

element-redeclaration :
   redeclare [ each ] [ final ]
   ( short-class-definition | component-clause1 | element-replaceable )

element-replaceable :
   replaceable ( short-class-definition | component-clause1 )
   [ constraining-clause ]

component-clause1 :
   type-prefix type-specifier component-declaration1

component-declaration1 :
   declaration description

short-class-definition :
   class-prefixes short-class-specifier
\end{lstlisting}

\subsection{Equations}\label{equations1}

\begin{lstlisting}[language=grammar]
equation-section :
   [ initial ] equation { equation ";" }

algorithm-section :
   [ initial ] algorithm { statement ";" }

equation :
   ( simple-expression "=" expression
     | if-equation
     | for-equation
     | connect-clause
     | when-equation
     | component-reference function-call-args
   )
   description

statement :
   ( component-reference ( ":=" expression | function-call-args )
     | "(" output-expression-list ")" ":="
       component-reference function-call-args
     | break
     | return
     | if-statement
     | for-statement
     | while-statement
     | when-statement
   )
   description

if-equation :
   if expression then
     { equation ";" }
   { elseif expression then
     { equation ";" }
   }
   [ else
     { equation ";" }
   ]
   end if

if-statement :
   if expression then
     { statement ";" }
   { elseif expression then
     { statement ";" }
   }
   [ else
     { statement ";" }
   ]
   end if

for-equation :
   for for-indices loop
     { equation ";" }
   end for

for-statement :
   for for-indices loop
     { statement ";" }
   end for

for-indices :
   for-index { "," for-index }

for-index :
   IDENT [ in expression ]

while-statement :
   while expression loop
     { statement ";" }
   end while

when-equation :
   when expression then
     { equation ";" }
   { elsewhen expression then
     { equation ";" }
   }
   end when

when-statement :
   when expression then
     { statement ";" }
   { elsewhen expression then
     { statement ";" }
   }
   end when

connect-clause :
   connect "(" component-reference "," component-reference ")"
\end{lstlisting}

\subsection{Expressions}\label{expressions1}

\begin{lstlisting}[language=grammar]
expression :
   simple-expression
   | if expression then expression
     { elseif expression then expression }
     else expression

simple-expression :
   logical-expression [ ":" logical-expression [ ":" logical-expression ] ]

logical-expression :
   logical-term { or logical-term }

logical-term :
   logical-factor { and logical-factor }

logical-factor :
   [ not ] relation

relation :
   arithmetic-expression [ relational-operator arithmetic-expression ]

relational-operator :
   "<" | "<=" | ">" | ">=" | "==" | "<>"

arithmetic-expression :
   [ add-operator ] term { add-operator term }

add-operator :
   "+" | "-" | ".+" | ".-"

term :
   factor { mul-operator factor }

mul-operator :
   "*" | "/" | ".*" | "./"

factor :
   primary [ ("^" | ".^") primary ]

primary :
   UNSIGNED-NUMBER
   | STRING
   | false
   | true
   | ( component-reference | der | initial | pure ) function-call-args
   | component-reference
   | "(" output-expression-list ")"
   | "[" expression-list { ";" expression-list } "]"
   | "{" array-arguments "}"
   | end

UNSIGNED-NUMBER :
   UNSIGNED-INTEGER | UNSIGNED-REAL

type-specifier :
   ["."] name

name :
   IDENT { "." IDENT }

component-reference :
   [ "." ] IDENT [ array-subscripts ] { "." IDENT [ array-subscripts ] }

function-call-args :
   "(" [ function-arguments ] ")"

function-arguments :
   expression [ "," function-arguments-non-first | for for-indices ]
   | function-partial-application [ "," function-arguments-non-first ]
   | named-arguments

function-arguments-non-first :
   function-argument [ "," function-arguments-non-first ]
   | named-arguments

array-arguments :
   expression [ "," array-arguments-non-first | for for-indices ]

array-arguments-non-first :
   expression [ "," array-arguments-non-first ]

named-arguments: named-argument [ "," named-arguments ]

named-argument: IDENT "=" function-argument

function-argument :
   function-partial-application | expression

function-partial-application :
   function type-specifier "(" [ named-arguments ] ")"

output-expression-list :
   [ expression ] { "," [ expression ] }

expression-list :
   expression { "," expression }

array-subscripts :
   "[" subscript { "," subscript } "]"

subscript :
   ":" | expression

description :
   description-string [ annotation-clause ]

description-string :
   [ STRING { "+" STRING } ]

annotation-clause :
   annotation class-modification
\end{lstlisting}