[Contents][Index]

Structured ¶

This is the manual for Structured (for GNU Jitter version 0.7.312, last updated on 27 May 2024), a programming language implementation using a Jittery VM, conceived as an example for GNU Jitter.

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.

Part I:
Overview
- 1 Introduction
  - 1.1 History and purpose
    - 1.1.1 Thanks
  - 1.2 Obtaining the software
- 2 Using Structured
  - 2.1 Invoking ‘structured’
Part II:
Internals

Next: Using Structured, Up: Structured [Contents][Index]

Part I:
Overview ¶

Introduction
Using Structured

1 Introduction ¶

[FIXME: ]

(see The GNU Jitter manual)

History and purpose
Obtaining the software

1.1 History and purpose ¶

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 space¹. 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.

Thanks

1.1.1 Thanks ¶

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.

1.2 Obtaining the software ¶

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.

Next: Architecture, Previous: Introduction, Up: Structured [Contents][Index]

2 Using Structured ¶

Invoking ‘structured’

Up: Using Structured [Contents][Index]

2.1 Invoking ‘`structured`’ ¶

[FIXME: Foo]

Jump to:	A B C D E F G H I J L M N O P R S T U

	Index Entry	Section

A
	API, code generation, Jitter	Introduction
	architecture	Architecture
	author, contacting	Introduction
	Autoconf, GNU	Introduction
	Automake, GNU	Introduction

B
	benchmark, micro-	Introduction
	branch, git	Introduction
	build system	Introduction

C
	C	Introduction
	calling convention	Introduction
	code generation API, Jitter	Introduction
	concept index	Concept index
	contacting the author	Introduction

D
	distribution	Introduction
	distribution	Introduction
	downloading	Introduction

E
	example	Introduction
	example	Introduction
	execution, register-based	Register-based execution
	execution, stack-based	Stack-based execution

F
	feedback	Introduction
	Foundation, p≡p	Introduction
	frontend	Frontend

G
	git	Introduction
	git branch	Introduction
	GNU	Introduction
	GNU	Introduction
	GNU poke	Introduction

H
	heap memory leak	Introduction

I
	index, for concepts	Concept index
	invoking, ‘`structured`’	Invoking ‘`structured`’

J
	JitterLisp	Introduction
	José Marchesi	Introduction
	José Marchesi	Introduction

L
	leak	Introduction
	leak, memory	Introduction
	leak, memory	Introduction
	Luca Saiu, contacting	Introduction

M
	Marchesi, José	Introduction
	Marchesi, José	Introduction
	`master`, git branch	Introduction
	micro-benchmark	Introduction
	Mohammad-Reza Nabipoor	Introduction

N
	Nabipoor, Mohammad-Reza	Introduction

O
	obtaining	Introduction

P
	p≡p Foundation	Introduction
	poke	Introduction
	procedure	Introduction

R
	register-based execution	Register-based execution

S
	Saiu, Luca, contacting	Introduction
	source	Introduction
	stack memory leak	Introduction
	stack-based execution	Stack-based execution
	‘`structured`’, invoking	Invoking ‘`structured`’

T
	tail call	Introduction
	tail call	Introduction
	test suite, Jitter	Introduction

U
	using Structured	Using Structured

Jump to:	A B C D E F G H I J L M N O P R S T U

Footnotes

(1)

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.

Structured ¶

Table of Contents

Part I:
Overview ¶

1 Introduction ¶

1.1 History and purpose ¶

1.1.1 Thanks ¶

1.2 Obtaining the software ¶

2 Using Structured ¶

2.1 Invoking ‘`structured`’ ¶

Part II:
Internals ¶

3 Architecture ¶

4 Frontend ¶

5 Stack-based execution ¶

6 Register-based execution ¶

Concept index ¶

Footnotes

(1)

Structured ¶

Table of Contents

Part I: Overview ¶

1 Introduction ¶

1.1 History and purpose ¶

1.1.1 Thanks ¶

1.2 Obtaining the software ¶

2 Using Structured ¶

2.1 Invoking ‘structured’ ¶

Part II: Internals ¶

3 Architecture ¶

4 Frontend ¶

5 Stack-based execution ¶

6 Register-based execution ¶

Concept index ¶

Footnotes

(1)

Part I:
Overview ¶

2.1 Invoking ‘`structured`’ ¶

Part II:
Internals ¶