diff options
| author | Eugen Wissner <belka@caraus.de> | 2026-02-12 21:17:32 +0100 |
|---|---|---|
| committer | Eugen Wissner <belka@caraus.de> | 2026-02-12 23:44:22 +0100 |
| commit | d7c27f1c6328198d0513d94bfd6462ad8ac7d2d5 (patch) | |
| tree | f7b37300b32db45fd1d9b5c954d0c0e8a17328d6 /doc | |
| parent | b37eb0690c9905b84c224cc693bbf1cab84f55fd (diff) | |
| download | elna-d7c27f1c6328198d0513d94bfd6462ad8ac7d2d5.tar.gz | |
Split documentation chapters into files
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/appendix.tex | 178 | ||||
| -rw-r--r-- | doc/credits.bib | 5 | ||||
| -rw-r--r-- | doc/language.tex | 374 | ||||
| -rw-r--r-- | doc/report.tex | 46 | ||||
| -rw-r--r-- | doc/type-system.tex | 158 |
5 files changed, 402 insertions, 359 deletions
diff --git a/doc/appendix.tex b/doc/appendix.tex new file mode 100644 index 0000000..9d92d53 --- /dev/null +++ b/doc/appendix.tex @@ -0,0 +1,178 @@ +\part{Appendix} + +\addchap{Syntax} + +\begin{grammar} +<letter> = `A' | `B' | … | `Z' | `a' | `b' | … | `z' | `\_'. + +<counting-digit> = `1' | `2' | `3' | `4' | `5' | `6' | `7' | `8' | `9'. + +<decimal-digit> = `0' | <counting-digit>. + +<hex-digit> = <decimal-digit> | `A' | `B' | … | `F' | `a' | `b' | … | `f'. + +<binary-digit> = `0' | `1'. + +<hex-character> = `\\x' <hex-digit> <hex-digit>. + +<escaped-character> = `\\' \\ + (`n' | `a' | `b' | `t' | `f' | `r' | `v' | `\\' | `\textquotesingle' | `\textquotedbl' | `?\@' | `0'). + +<printable-character> = \enspace? a printable ASCII character\space?. + +<character> = <printable-character> | <escaped-character> | <hex-digit>. + +<identifier> = <letter> \{<letter> | <decimal-digit>\}. + +<identifier-definition> = <identifier> [`*']. + +<trait-identifier> = `#' <identifier>. + +<integer-literal> = `0' | <counting-digit> \{<decimal-digit>\}. + +<word-literal> = <integer-literal> `u' + \alt{} `0' (`X' | `x') <hex-digit> \{<hex-digit>\} + \alt{} `0' (`B' | `b') <binary-digit> \{<binary-digit>\}. + +<real-literal> = <integer-literal> `.\@' <decimal-digit> \{<decimal-digit>\} + \alt{} <integer-literal>\} `e' [`+' | `-'] <decimal-digit> \{<decimal-digit>\}. + +<string-literal> = `\textquotedbl' \{<character>\} `\textquotedbl'. + +<character-literal> = `\textquotesingle' <character> `\textquotesingle'. + +<literal> = <integer-literal> | <word-literal> | <real-literal> + \alt{} <string-literal> | <character-literal> + \alt{} `true' | `false' | `nil'. + +<trait> = <trait-identifier> `(' [<types>] `)'. + +<cast> = `cast' `(' <expression> `:\@' <type> `)'. + +<procedure-call> = <designator> `(' [<expressions>] `)'. + +<relation-operator> = `=' | `<>' | `<' | `>' | `<=' | `>='. + +<multiplication-operator> = `*' | `/' | `\%'. + +<addition-operator> = `+' | `-'. + +<shift-operator> = `<<' | `>>'. + +<unary-operator> = `@' | `~' | `-'. + +<selector> = `[' <expression> `]' | `.\@' <identifier> | `^'. + +<case> = <expressions> `:\@' <optional-statements>. + +<designator> = <reference> <selector> | <identifier>. + +<reference> = <literal> + \alt{} <designator> + \alt{} <trait> + \alt{} <cast> + \alt{} <procedure-call> + \alt{} `(' <expression> `)'. + +<factor> = <unary-operator> <factor> | <reference>. + +<term> = <factor> \{<multiplication-operator> <factor>\}. + +<simple-expression> = <term> \{<addition-operator> <term>\}. + +<comparand> = <simple-expression> \{<shift-operator> <simple-expression>\}. + +<relation> = <comparand> \{<relation-operator> <comparand>\}. + +<operand> = <relation> \{`&' <relation>\}. + +<expression> = <operand> \{(`or' | `xor') <operand>\}. + +<expressions> = <expression> \{`,' <expression>\}. + +<identifier-definitions> = <identifier-definition> \{`,' <identifier-definition>\}. + +<types> = <type> \{`,' <type>\}. + +<required-statements> = <statement> \{`;' <statement>\}. + +<optional-statements> = [<required-statements>]. + +<return-declaration> = [`->' `!\@' | `->' type]. + +<field> = <identifier> `:\@' <type>. + +<array-type> = `[' <expression> `]' <type>. + +<pointer-type> = `^' <type>. + +<record-type> = `record' [`(' <identifier> `)'] [<field> \{`;' <field>\}] `end'. + +<enumeration-type> = `(' <identifier> \{`,' <identifier>\} `)'. + +<procedure-type> = `proc' `(' [<types>] `)' <return-declaration>. + +<type> = <array-type> + \alt{} <pointer-type> + \alt{} <record-type> + \alt{} <enumeration-type> + \alt{} <procedure-type> + \alt{} <identifier>. + +<assignment> = <designator> `:=' <expression>. + +<if-statement> = `if' <expression> `then' <optional-statements> \\ + \{`elsif' <expression> `then' <optional-statements>\} \\ + {[`else' <optional-statements>]} `end'. + +<while-statement> = `while' <expression> `do' <optional-statements> \\ + \{`elsif' <expression> `do' <optional-statements>\} `end'. + +<defer-statement> = `defer' <optional-statements> `end'. + +<case-statement> = `case' <expression> `of' <case> \{`|' case\} \\ + {[`else' <optional-statements>]} `end'. + +<label-declaration> = `.\@' <identifier>. + +<goto-statement> = `goto' <identifier>. + +<statement> = <assignment> | <procedure-call> | <defer-statement> + | <label-declaration> | <goto-statement> | + | <while-statement> | <if-statement> | <case-statement>. + +<statement-part> = [`begin' <required-statements> + \alt{} `return' <expression> + \alt{} `begin' <required-statements> `;' `return' <expression>]. + +<constant-declaration> = <identifier-definition> `:=' <expression>. + +<constant-part> = [`const' \{<constant-declaration> `;'\}]. + +<variable-declaration> = <identifier-definitions> `:\@' <type> \\ + {[`:=' (<expression> | `extern')]}. + +<variable-part> = [`var' \{<variable-declaration> `;'\}]. + +<type-declaration> = <identifier-definition> `=' <type>. + +<type-part> = [`type' \{<type-declaration> `;'\}]. + +<import-declaration> = <identifier> \{`.\@' <identifier>\}. + +<import-part> = [`import' \{import-declaration `;'\}]. + +<procedure-heading> = `proc' <identifier-definition> \\ + `(' [<field> \{`,' <field>\}] `)' <return-declaration>. + +<block> = <constant-part> <variable-part> <statement-part> `end'. + +<procedure-declaration> = <procedure-heading> `;' (block | `extern'). + +<declaration-sequence> = <import-part> \\ + <constant-part> <type-part> <variable-part> \\ + \{<procedure-declaration> `;'\}. + +<program> = `program' `;' <declaration-sequence> <statement-part> `end' `.\@' + \alt{} `module' `;' <declaration-sequence> `end' `.\@'. +\end{grammar} diff --git a/doc/credits.bib b/doc/credits.bib new file mode 100644 index 0000000..0af1709 --- /dev/null +++ b/doc/credits.bib @@ -0,0 +1,5 @@ +@book{oberon, + author = "Niklaus Wirth", + title = "The Programming Language Oberon", + year = 2016 +} diff --git a/doc/language.tex b/doc/language.tex index bfa21cb..a18dac8 100644 --- a/doc/language.tex +++ b/doc/language.tex @@ -1,27 +1,23 @@ -\documentclass{scrreprt} - -\usepackage[T1]{fontenc} -\usepackage{tabularx} -\usepackage{booktabs} -\usepackage{listings} -\usepackage{syntax} - -\title{The programming language Elna} - -\begin{document} +\part{Language} -\maketitle -\tableofcontents +An Elna program consists of one or more source files, called \textbf{modules}. -\chapter{Introduction} +Each module can declare \textbf{types}, \textbf{global variables} and +\textbf{procedures}, used by this module or exported to be used by other +modules. -Elna is a simple, imperative, low-level programming language. +Each procedure can get some input and produce an output as a result of +executing a \textbf{statement block}, a list, where each \textbf{statement} +is executed in the order it appears in the block. -It is intendet to accompany other languages in the areas, where a high-level -language doesn't fit well. It is also supposed to be an intermediate -representation for a such high-level hypothetical programming language. +Statement components are other statement blocks and \textbf{expressions}, +where a statement has control over the evaluation of its components. +Statements can also modify the state of the procedure or the program by +mutating variables. -\part{Language} +Most simple expressions are identifiers referencing program's symbols and +literals. These atomic expressions can be combined to more complex expressions +by applying various operations to one or more expressions. \chapter{Expressions} @@ -76,343 +72,3 @@ bitwise not. \chapter{Conditional statements} \chapter{Loop statements} - -\part{Type system} - -\begin{grammar} -<type> = <array-type> - \alt{} <pointer-type> - \alt{} <record-type> - \alt{} <enumeration-type> - \alt{} <procedure-type> - \alt{} <identifier>. -\end{grammar} - -\chapter{Primitive types} - -\begin{itemize} - \item Pointer - \item Word - \item Int - \item Bool - \item String - \item Char -\end{itemize} - -\chapter{Pointer types} - -\begin{grammar} -<pointer-type> = `^' <type>. -\end{grammar} - -\begin{lstlisting}[caption=Example] -program; -var - x: Int; - y: ^Int; -begin - y := @x; - y^ := 0 -end. -\end{lstlisting} - -\chapter{Static array} - -\begin{grammar} -<array-type> = `[' <expression> `]' <type>. -\end{grammar} - -\begin{lstlisting}[caption=Example] -program; -var - array: [3]Int := [1, 2, 3]; -begin - array[1] := array[2] -end. -\end{lstlisting} - -\chapter{Procedure types} - -\begin{grammar} -<procedure-heading> = `proc' <identifier-definition> \\ - `(' [<field> \{`,' <field>\}] `)' <return-declaration>. - -<block> = <constant-part> <variable-part> <statement-part> `end'. - -<procedure-declaration> = <procedure-heading> `;' (block | `extern'). - -<return-declaration> = [`->' `!\@' | `->' type]. - -<procedure-type> = `proc' `(' [<types>] `)' <return-declaration>. -\end{grammar} - -\begin{lstlisting}[caption=Example] -program; -var - a: proc(Int) -> Int; - -proc f(x: Int) -> Int; -end; - -begin - a := f; - a(0) -end. -\end{lstlisting} - -\chapter{Records} - -\begin{grammar} -<field> = <identifier> `:\@' <type>. - -<record-type> = `record' [`(' <identifier> `)'] [<field> \{`;' <field>\}] `end'. -\end{grammar} - -\begin{lstlisting}[caption=Example] -program; -type - T = record - x: Int - end; - U = record(T) - y: Int; - z: Int - end; - -var - u: U; -begin - u := U(0, 1, 2); - u.x := 3 -end. -\end{lstlisting} - -\chapter{Enumerations} - -\begin{grammar} -<enumeration-type> = `(' <identifier> \{`,' <identifier>\} `)'. -\end{grammar} - -\begin{lstlisting}[caption=Example] -program; -type - E = (one, two, three); -var - e: E; -begin - e := E.one -end. -\end{lstlisting} - -\chapter{Type operations} - -\chapter{Cast} - -\begin{grammar} -<cast> = `cast' `(' <expression> `:\@' <type> `)'. -\end{grammar} - -The type of an object can be reinterpreted with a cast expression: \\ -\verb|cast(object: Type)|. - -\chapter{Traits} - -\begin{grammar} -<trait-identifier> = `#' <identifier>. - -<trait> = <trait-identifier> `(' [<types>] `)'. -\end{grammar} - -Traits allow to query some information about the types, like their size or -field offset or alignment. Calling a trait looks like a procedure call but -traits names start with a \verb|#| and their arguments are type expressions and -not value expressions. - -Supported compiler traits: - -\begin{itemize} - \item \verb|#size(T)| queries type size. - \item \verb|#align(T)| queries type alignment. - \item \verb|#offset(T, F)| queries the offset of the field \verb|F| in the record \verb|T|. -\end{itemize} - -\part{Appendix} - -\chapter{Syntax} - -\begin{grammar} -<letter> = `A' | `B' | … | `Z' | `a' | `b' | … | `z' | `\_'. - -<counting-digit> = `1' | `2' | `3' | `4' | `5' | `6' | `7' | `8' | `9'. - -<decimal-digit> = `0' | <counting-digit>. - -<hex-digit> = <decimal-digit> | `A' | `B' | … | `F' | `a' | `b' | … | `f'. - -<binary-digit> = `0' | `1'. - -<hex-character> = `\\x' <hex-digit> <hex-digit>. - -<escaped-character> = `\\' \\ - (`n' | `a' | `b' | `t' | `f' | `r' | `v' | `\\' | `\textquotesingle' | `\textquotedbl' | `?\@' | `0'). - -<printable-character> = \enspace? a printable ASCII character\space?. - -<character> = <printable-character> | <escaped-character> | <hex-digit>. - -<identifier> = <letter> \{<letter> | <decimal-digit>\}. - -<identifier-definition> = <identifier> [`*']. - -<trait-identifier> = `#' <identifier>. - -<integer-literal> = `0' | <counting-digit> \{<decimal-digit>\}. - -<word-literal> = <integer-literal> `u' - \alt{} `0' (`X' | `x') <hex-digit> \{<hex-digit>\} - \alt{} `0' (`B' | `b') <binary-digit> \{<binary-digit>\}. - -<real-literal> = <integer-literal> `.\@' <decimal-digit> \{<decimal-digit>\} - \alt{} <integer-literal>\} `e' [`+' | `-'] <decimal-digit> \{<decimal-digit>\}. - -<string-literal> = `\textquotedbl' \{<character>\} `\textquotedbl'. - -<character-literal> = `\textquotesingle' <character> `\textquotesingle'. - -<literal> = <integer-literal> | <word-literal> | <real-literal> - \alt{} <string-literal> | <character-literal> - \alt{} `true' | `false' | `nil'. - -<trait> = <trait-identifier> `(' [<types>] `)'. - -<cast> = `cast' `(' <expression> `:\@' <type> `)'. - -<procedure-call> = <designator> `(' [<expressions>] `)'. - -<relation-operator> = `=' | `<>' | `<' | `>' | `<=' | `>='. - -<multiplication-operator> = `*' | `/' | `\%'. - -<addition-operator> = `+' | `-'. - -<shift-operator> = `<<' | `>>'. - -<unary-operator> = `@' | `~' | `-'. - -<selector> = `[' <expression> `]' | `.\@' <identifier> | `^'. - -<case> = <expressions> `:\@' <optional-statements>. - -<designator> = <reference> <selector> | <identifier>. - -<reference> = <literal> - \alt{} <designator> - \alt{} <trait> - \alt{} <cast> - \alt{} <procedure-call> - \alt{} `(' <expression> `)'. - -<factor> = <unary-operator> <factor> | <reference>. - -<term> = <factor> \{<multiplication-operator> <factor>\}. - -<simple-expression> = <term> \{<addition-operator> <term>\}. - -<comparand> = <simple-expression> \{<shift-operator> <simple-expression>\}. - -<relation> = <comparand> \{<relation-operator> <comparand>\}. - -<operand> = <relation> \{`&' <relation>\}. - -<expression> = <operand> \{(`or' | `xor') <operand>\}. - -<expressions> = <expression> \{`,' <expression>\}. - -<identifier-definitions> = <identifier-definition> \{`,' <identifier-definition>\}. - -<types> = <type> \{`,' <type>\}. - -<required-statements> = <statement> \{`;' <statement>\}. - -<optional-statements> = [<required-statements>]. - -<return-declaration> = [`->' `!\@' | `->' type]. - -<field> = <identifier> `:\@' <type>. - -<array-type> = `[' <expression> `]' <type>. - -<pointer-type> = `^' <type>. - -<record-type> = `record' [`(' <identifier> `)'] [<field> \{`;' <field>\}] `end'. - -<enumeration-type> = `(' <identifier> \{`,' <identifier>\} `)'. - -<procedure-type> = `proc' `(' [<types>] `)' <return-declaration>. - -<type> = <array-type> - \alt{} <pointer-type> - \alt{} <record-type> - \alt{} <enumeration-type> - \alt{} <procedure-type> - \alt{} <identifier>. - -<assignment> = <designator> `:=' <expression>. - -<if-statement> = `if' <expression> `then' <optional-statements> \\ - \{`elsif' <expression> `then' <optional-statements>\} \\ - {[`else' <optional-statements>]} `end'. - -<while-statement> = `while' <expression> `do' <optional-statements> \\ - \{`elsif' <expression> `do' <optional-statements>\} `end'. - -<defer-statement> = `defer' <optional-statements> `end'. - -<case-statement> = `case' <expression> `of' <case> \{`|' case\} \\ - {[`else' <optional-statements>]} `end'. - -<label-declaration> = `.\@' <identifier>. - -<goto-statement> = `goto' <identifier>. - -<statement> = <assignment> | <procedure-call> | <defer-statement> - | <label-declaration> | <goto-statement> | - | <while-statement> | <if-statement> | <case-statement>. - -<statement-part> = [`begin' <required-statements> - \alt{} `return' <expression> - \alt{} `begin' <required-statements> `;' `return' <expression>]. - -<constant-declaration> = <identifier-definition> `:=' <expression>. - -<constant-part> = [`const' \{<constant-declaration> `;'\}]. - -<variable-declaration> = <identifier-definitions> `:\@' <type> \\ - {[`:=' (<expression> | `extern')]}. - -<variable-part> = [`var' \{<variable-declaration> `;'\}]. - -<type-declaration> = <identifier-definition> `=' <type>. - -<type-part> = [`type' \{<type-declaration> `;'\}]. - -<import-declaration> = <identifier> \{`.\@' <identifier>\}. - -<import-part> = [`import' \{import-declaration `;'\}]. - -<procedure-heading> = `proc' <identifier-definition> \\ - `(' [<field> \{`,' <field>\}] `)' <return-declaration>. - -<block> = <constant-part> <variable-part> <statement-part> `end'. - -<procedure-declaration> = <procedure-heading> `;' (block | `extern'). - -<declaration-sequence> = <import-part> \\ - <constant-part> <type-part> <variable-part> \\ - \{<procedure-declaration> `;'\}. - -<program> = `program' `;' <declaration-sequence> <statement-part> `end' `.\@' - \alt{} `module' `;' <declaration-sequence> `end' `.\@'. -\end{grammar} - -\end{document} diff --git a/doc/report.tex b/doc/report.tex new file mode 100644 index 0000000..e3ed640 --- /dev/null +++ b/doc/report.tex @@ -0,0 +1,46 @@ +\documentclass{scrreprt} + +\usepackage[T1]{fontenc} +\usepackage{tabularx} +\usepackage{booktabs} +\usepackage{listings} +\usepackage{syntax} +\usepackage[backend=biber,style=verbose-ibid,dashed=false]{biblatex} + +% Do not start chapter on a new page. +\RedeclareSectionCommand[ + style=section, + indent=0pt +]{chapter} + +\bibliography{credits} + +\title{The programming language Elna} +\author{Eugen Wissner} + +\begin{document} + +\maketitle +\tableofcontents + +\addchap{Introduction} + +Elna is a simple, imperative, low-level programming language. + +It is intendet to accompany other languages in the areas, where a high-level +language doesn't fit well. It is also supposed to be an intermediate +representation for a such high-level hypothetical programming language. + +\addchap{Credits} + +Since Elna syntactically resembles Oberon larger parts of this specification +are derived from the Oberon report\footnote{\cite[]{oberon}}. + +\include{language} +\include{type-system} +\include{appendix} + +% \addcontentsline{toc}{chapter}{References} +\printbibliography[heading=bibintoc, title=References]{} + +\end{document} diff --git a/doc/type-system.tex b/doc/type-system.tex new file mode 100644 index 0000000..4ac36e4 --- /dev/null +++ b/doc/type-system.tex @@ -0,0 +1,158 @@ +\part{Type system} + +\begin{grammar} +<type> = <array-type> + \alt{} <pointer-type> + \alt{} <record-type> + \alt{} <enumeration-type> + \alt{} <procedure-type> + \alt{} <identifier>. +\end{grammar} + +\chapter{Primitive types} + +\begin{itemize} + \item Pointer + \item Word + \item Int + \item Bool + \item String + \item Char +\end{itemize} + +\chapter{Pointer types} + +\begin{grammar} +<pointer-type> = `^' <type>. +\end{grammar} + +\begin{lstlisting}[caption=Example] +program; +var + x: Int; + y: ^Int; +begin + y := @x; + y^ := 0 +end. +\end{lstlisting} + +\chapter{Static array} + +\begin{grammar} +<array-type> = `[' <expression> `]' <type>. +\end{grammar} + +\begin{lstlisting}[caption=Example] +program; +var + array: [3]Int := [1, 2, 3]; +begin + array[1] := array[2] +end. +\end{lstlisting} + +\chapter{Procedure types} + +\begin{grammar} +<procedure-heading> = `proc' <identifier-definition> \\ + `(' [<field> \{`,' <field>\}] `)' <return-declaration>. + +<block> = <constant-part> <variable-part> <statement-part> `end'. + +<procedure-declaration> = <procedure-heading> `;' (block | `extern'). + +<return-declaration> = [`->' `!\@' | `->' type]. + +<procedure-type> = `proc' `(' [<types>] `)' <return-declaration>. +\end{grammar} + +\begin{lstlisting}[caption=Example] +program; +var + a: proc(Int) -> Int; + +proc f(x: Int) -> Int; +end; + +begin + a := f; + a(0) +end. +\end{lstlisting} + +\chapter{Records} + +\begin{grammar} +<field> = <identifier> `:\@' <type>. + +<record-type> = `record' [`(' <identifier> `)'] [<field> \{`;' <field>\}] `end'. +\end{grammar} + +\begin{lstlisting}[caption=Example] +program; +type + T = record + x: Int + end; + U = record(T) + y: Int; + z: Int + end; + +var + u: U; +begin + u := U(0, 1, 2); + u.x := 3 +end. +\end{lstlisting} + +\chapter{Enumerations} + +\begin{grammar} +<enumeration-type> = `(' <identifier> \{`,' <identifier>\} `)'. +\end{grammar} + +\begin{lstlisting}[caption=Example] +program; +type + E = (one, two, three); +var + e: E; +begin + e := E.one +end. +\end{lstlisting} + +\chapter{Type operations} + +\chapter{Cast} + +\begin{grammar} +<cast> = `cast' `(' <expression> `:\@' <type> `)'. +\end{grammar} + +The type of an object can be reinterpreted with a cast expression: \\ +\verb|cast(object: Type)|. + +\chapter{Traits} + +\begin{grammar} +<trait-identifier> = `#' <identifier>. + +<trait> = <trait-identifier> `(' [<types>] `)'. +\end{grammar} + +Traits allow to query some information about the types, like their size or +field offset or alignment. Calling a trait looks like a procedure call but +traits names start with a \verb|#| and their arguments are type expressions and +not value expressions. + +Supported compiler traits: + +\begin{itemize} + \item \verb|#size(T)| queries type size. + \item \verb|#align(T)| queries type alignment. + \item \verb|#offset(T, F)| queries the offset of the field \verb|F| in the record \verb|T|. +\end{itemize} |
