This is the manual for Structured (for GNU Jitter version 0.9.294, last updated on 19 January 2023), a programming language implementation using a Jittery VM, conceived as an example for GNU Jitter.
Copyright © 2017-2021 Luca Saiu
Copyright © 2021 p≡p Foundation
Updated in 2022 by Luca Saiu
Written by Luca Saiu.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Front-Cover texts and with the Back-Cover text being “You have freedom to copy and modify this manual, like GNU software.”.
A copy of the GNU Free Documentation License is distributed in electronic form along with the software in the file doc/COPYING.DOC, and available on the web at the URL https://www.gnu.org/licenses/fdl.html.
All the code examples contained in this manual are released into the public domain, up to the extent of the applicable law.
The author’s personal web site https://ageinghacker.net contains his contact information.
[FIXME: ]
(see The GNU Jitter manual)
Around 2017 José Marchesi had already started his poke project, later accepted as part of GNU (see The GNU poke Manual). He had decided early on to use a Jittery VM, after an informal demo of mine.
However at the time nobody, me included, had any real experience with Jitter’s code generation API; even JitterLisp (see The JitterLisp manual) did not exist yet. In order to figure out how to proceed José asked me for a simple but complete example of a Jittery system, at least as a stopgap solution before I could prepare proper documentation.
And so I decided to spend a weekend writing an implementation of a very simple programming language, suitable as a first example. The VM was based on a stack and the code generator worked by recursion on abstract syntax trees. There were no procedures, and variables (integer-only) were declared implicitly.
The resulting language was “Structured”, an eminently uninteresting imperative structured programming language similar to Pascal. I tried to keep the implementation clear and didactic, also accessible to relative beginners and not only to experienced programmers like José.
The example served its purpose making the development of poke easier. I seem to remember that some Jitter API changes also came from the experience of writing Structured, which was expected.
At some point Structured gained an example build system, in two versions, showing how to package a Jittery system using GNU Autoconf and Automake; I just needed some Jittery program to package as an example, and Structured was there.
Structured now comes with a few examples of its own, intended as micro-benchmarks and also executed as part of the Jitter test suite.
The language has evolved to a moderate degree: 2021 additions include
procedures, which can be called recursively. Variables are no longer
all global, and now need to be declared.
More importantly, the implementation has evolved: there are two
separate and independent code generators, the original one based on a
stack and a new one based on VM registers. The two code generators
amount in fact to two different tutorial examples: the register-based
generator is less easy to understand but generates superior code.
Tail calls are compiled correctly without leaking stack
space1.
At this time the procedure calling
conventions are not very efficient, and the implementation could be
optimised.
The balance between source code clarity and “realism” remains
delicate.
Since Jitter became part of the GNU Project in December 2021 documenting this sub-project, now more visible, has become important.
I wish to thank José Marchesi for the initial stimulus, and Mohammad-Reza Nabipoor for his interest and his many motivating questions.
Starting in Summer 2021 and as of 2022 my employer p≡p Foundation (https://pep.foundation) is allowing me to partly develop this software on work hours. Such support is greatly appreciated.
Structured is distributed as an example within GNU Jitter, and can be obtained along with the Jitter source code. The main web page for Jitter, containing a link to a publicly readable git repository, is on the GNU Project web site at https://www.gnu.org/software/jitter/.
As of 2022 Structured development takes place on the public git
repository for GNU Jitter, normally in the master branch:
see Working with the Jitter sources in The GNU Jitter Manual.
[FIXME: talk about build system examples using structured: it is in fact trivial to generate clean source tarballs for structured.]
I welcome feedback. If you need to contact me or want to discuss about Structured please see Contacting the author in The GNU Jitter Manual.
I argue that consuming a finite resource during code execution at run time while an alternative exists is not lack of an “optimisation”, but lack of correctness. Leaking stack space has been historically perceived in a sense as more socially acceptable than leaking heap space. This perception is irrational and should change: artificially establishing a limit on the depth of dynamically nested calls forces the programmer to avoid some perfectly correct solutions and constrains expressivity.