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} + = `A' | `B' | … | `Z' | `a' | `b' | … | `z' | `\_'. + + = `1' | `2' | `3' | `4' | `5' | `6' | `7' | `8' | `9'. + + = `0' | . + + = | `A' | `B' | … | `F' | `a' | `b' | … | `f'. + + = `0' | `1'. + + = `\\x' . + + = `\\' \\ + (`n' | `a' | `b' | `t' | `f' | `r' | `v' | `\\' | `\textquotesingle' | `\textquotedbl' | `?\@' | `0'). + + = \enspace? a printable ASCII character\space?. + + = | | . + + = \{ | \}. + + = [`*']. + + = `#' . + + = `0' | \{\}. + + = `u' + \alt{} `0' (`X' | `x') \{\} + \alt{} `0' (`B' | `b') \{\}. + + = `.\@' \{\} + \alt{} \} `e' [`+' | `-'] \{\}. + + = `\textquotedbl' \{\} `\textquotedbl'. + + = `\textquotesingle' `\textquotesingle'. + + = | | + \alt{} | + \alt{} `true' | `false' | `nil'. + + = `(' [] `)'. + + = `cast' `(' `:\@' `)'. + + = `(' [] `)'. + + = `=' | `<>' | `<' | `>' | `<=' | `>='. + + = `*' | `/' | `\%'. + + = `+' | `-'. + + = `<<' | `>>'. + + = `@' | `~' | `-'. + + = `[' `]' | `.\@' | `^'. + + = `:\@' . + + = | . + + = + \alt{} + \alt{} + \alt{} + \alt{} + \alt{} `(' `)'. + + = | . + + = \{ \}. + + = \{ \}. + + = \{ \}. + + = \{ \}. + + = \{`&' \}. + + = \{(`or' | `xor') \}. + + = \{`,' \}. + + = \{`,' \}. + + = \{`,' \}. + + = \{`;' \}. + + = []. + + = [`->' `!\@' | `->' type]. + + = `:\@' . + + = `[' `]' . + + = `^' . + + = `record' [`(' `)'] [ \{`;' \}] `end'. + + = `(' \{`,' \} `)'. + + = `proc' `(' [] `)' . + + = + \alt{} + \alt{} + \alt{} + \alt{} + \alt{} . + + = `:=' . + + = `if' `then' \\ + \{`elsif' `then' \} \\ + {[`else' ]} `end'. + + = `while' `do' \\ + \{`elsif' `do' \} `end'. + + = `defer' `end'. + + = `case' `of' \{`|' case\} \\ + {[`else' ]} `end'. + + = `.\@' . + + = `goto' . + + = | | + | | | + | | | . + + = [`begin' + \alt{} `return' + \alt{} `begin' `;' `return' ]. + + = `:=' . + + = [`const' \{ `;'\}]. + + = `:\@' \\ + {[`:=' ( | `extern')]}. + + = [`var' \{ `;'\}]. + + = `=' . + + = [`type' \{ `;'\}]. + + = \{`.\@' \}. + + = [`import' \{import-declaration `;'\}]. + + = `proc' \\ + `(' [ \{`,' \}] `)' . + + = `end'. + + = `;' (block | `extern'). + + = \\ + \\ + \{ `;'\}. + + = `program' `;' `end' `.\@' + \alt{} `module' `;' `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,28 +1,24 @@ -\documentclass{scrreprt} - -\usepackage[T1]{fontenc} -\usepackage{tabularx} -\usepackage{booktabs} -\usepackage{listings} -\usepackage{syntax} - -\title{The programming language Elna} - -\begin{document} - -\maketitle -\tableofcontents - -\chapter{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. - \part{Language} +An Elna program consists of one or more source files, called \textbf{modules}. + +Each module can declare \textbf{types}, \textbf{global variables} and +\textbf{procedures}, used by this module or exported to be used by other +modules. + +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. + +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. + +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} The expression \verb|@r.field| includes 3 expressions: @@ -76,343 +72,3 @@ bitwise not. \chapter{Conditional statements} \chapter{Loop statements} - -\part{Type system} - -\begin{grammar} - = - \alt{} - \alt{} - \alt{} - \alt{} - \alt{} . -\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} - = `^' . -\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} - = `[' `]' . -\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} - = `proc' \\ - `(' [ \{`,' \}] `)' . - - = `end'. - - = `;' (block | `extern'). - - = [`->' `!\@' | `->' type]. - - = `proc' `(' [] `)' . -\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} - = `:\@' . - - = `record' [`(' `)'] [ \{`;' \}] `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} - = `(' \{`,' \} `)'. -\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' `(' `:\@' `)'. -\end{grammar} - -The type of an object can be reinterpreted with a cast expression: \\ -\verb|cast(object: Type)|. - -\chapter{Traits} - -\begin{grammar} - = `#' . - - = `(' [] `)'. -\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} - = `A' | `B' | … | `Z' | `a' | `b' | … | `z' | `\_'. - - = `1' | `2' | `3' | `4' | `5' | `6' | `7' | `8' | `9'. - - = `0' | . - - = | `A' | `B' | … | `F' | `a' | `b' | … | `f'. - - = `0' | `1'. - - = `\\x' . - - = `\\' \\ - (`n' | `a' | `b' | `t' | `f' | `r' | `v' | `\\' | `\textquotesingle' | `\textquotedbl' | `?\@' | `0'). - - = \enspace? a printable ASCII character\space?. - - = | | . - - = \{ | \}. - - = [`*']. - - = `#' . - - = `0' | \{\}. - - = `u' - \alt{} `0' (`X' | `x') \{\} - \alt{} `0' (`B' | `b') \{\}. - - = `.\@' \{\} - \alt{} \} `e' [`+' | `-'] \{\}. - - = `\textquotedbl' \{\} `\textquotedbl'. - - = `\textquotesingle' `\textquotesingle'. - - = | | - \alt{} | - \alt{} `true' | `false' | `nil'. - - = `(' [] `)'. - - = `cast' `(' `:\@' `)'. - - = `(' [] `)'. - - = `=' | `<>' | `<' | `>' | `<=' | `>='. - - = `*' | `/' | `\%'. - - = `+' | `-'. - - = `<<' | `>>'. - - = `@' | `~' | `-'. - - = `[' `]' | `.\@' | `^'. - - = `:\@' . - - = | . - - = - \alt{} - \alt{} - \alt{} - \alt{} - \alt{} `(' `)'. - - = | . - - = \{ \}. - - = \{ \}. - - = \{ \}. - - = \{ \}. - - = \{`&' \}. - - = \{(`or' | `xor') \}. - - = \{`,' \}. - - = \{`,' \}. - - = \{`,' \}. - - = \{`;' \}. - - = []. - - = [`->' `!\@' | `->' type]. - - = `:\@' . - - = `[' `]' . - - = `^' . - - = `record' [`(' `)'] [ \{`;' \}] `end'. - - = `(' \{`,' \} `)'. - - = `proc' `(' [] `)' . - - = - \alt{} - \alt{} - \alt{} - \alt{} - \alt{} . - - = `:=' . - - = `if' `then' \\ - \{`elsif' `then' \} \\ - {[`else' ]} `end'. - - = `while' `do' \\ - \{`elsif' `do' \} `end'. - - = `defer' `end'. - - = `case' `of' \{`|' case\} \\ - {[`else' ]} `end'. - - = `.\@' . - - = `goto' . - - = | | - | | | - | | | . - - = [`begin' - \alt{} `return' - \alt{} `begin' `;' `return' ]. - - = `:=' . - - = [`const' \{ `;'\}]. - - = `:\@' \\ - {[`:=' ( | `extern')]}. - - = [`var' \{ `;'\}]. - - = `=' . - - = [`type' \{ `;'\}]. - - = \{`.\@' \}. - - = [`import' \{import-declaration `;'\}]. - - = `proc' \\ - `(' [ \{`,' \}] `)' . - - = `end'. - - = `;' (block | `extern'). - - = \\ - \\ - \{ `;'\}. - - = `program' `;' `end' `.\@' - \alt{} `module' `;' `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} + = + \alt{} + \alt{} + \alt{} + \alt{} + \alt{} . +\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} + = `^' . +\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} + = `[' `]' . +\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} + = `proc' \\ + `(' [ \{`,' \}] `)' . + + = `end'. + + = `;' (block | `extern'). + + = [`->' `!\@' | `->' type]. + + = `proc' `(' [] `)' . +\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} + = `:\@' . + + = `record' [`(' `)'] [ \{`;' \}] `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} + = `(' \{`,' \} `)'. +\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' `(' `:\@' `)'. +\end{grammar} + +The type of an object can be reinterpreted with a cast expression: \\ +\verb|cast(object: Type)|. + +\chapter{Traits} + +\begin{grammar} + = `#' . + + = `(' [] `)'. +\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} diff --git a/rakelib/doc.rake b/rakelib/doc.rake index d719c80..54f5d35 100644 --- a/rakelib/doc.rake +++ b/rakelib/doc.rake @@ -7,17 +7,26 @@ require 'pathname' require 'rake/clean' CLEAN.include 'build/doc' - directory 'build/doc' -rule /build\/doc\/\w+.pdf/ => lambda { |t| - [ - Pathname.new(t).relative_path_from('build').sub_ext('.tex').to_path, - 'build/doc' - ] -} do |t| - sh 'pdflatex', '--output-directory', 'build/doc', t.prerequisites.first +rule '.bbl' => '.bcf' do |t| + task_target = Pathname.new t.name + chdir = 'doc' + output_directory = task_target.dirname.relative_path_from(chdir).to_path + source = task_target.basename('.bbl').to_path + + sh 'biber', '-output-directory', output_directory, source, chdir: +end + +namespace :doc do + task :tex do + sh 'pdflatex', '-output-directory', '../build/doc', 'report', chdir: 'doc' + end end desc 'Generate documentation' -task doc: 'build/doc/language.pdf' +task doc: 'doc:tex' do + Rake::Task['build/doc/report.bbl'].invoke + Rake::Task['doc:tex'].reenable + Rake::Task['doc:tex'].invoke +end