1 Scope
(1) This document defines the embeddable scripting language Pinax: which Pinax programs are conforming, what a conforming program does when it runs, how a processor refuses a program that does not conform, and how a C program drives a processor.
(2) This document defines:
- the characters and tokens of a source (clause 6), types and values (7), declarations (8), words and the stack (9), control (10);
- failures and faults (11), memory (12), modules (13), tasks (14);
- the core words (15), the standard modules (16), the host modules (17), calling C functions (18);
- the host interface (19) and the command
pnx(20); - annexes: the whole grammar (A), the diagnostics (B), size limits (C), what is not in this edition (D).
(3) This document does not define:
- how a processor translates and executes source. The shape of bytecode and the way it runs are the processor’s business, except for what can be observed through the host interface of clause 19;
- figures of speed and memory use;
- the features that are not in this edition (annex D). They survive only as names (reserved words) or are refused.
(4) This document is not written against one processor. Still, every example in it was run with the implementation in the same repository (pnx, libpinax), and the output printed is the output captured then. Where an example and the text disagree, the text wins.
Note
Pinax is a scripting language that runs inside one fixed block of memory. It has no garbage collector, no heap allocation, no pointers, no objects, no dynamic types and no exceptions. On the surface it is a typed Forth: words pass values over a stack, and inside a word values have names. The rest of this document spells that sentence out.1.1 How to read this document
(5) This document defines rules. Someone learning Pinax for the first time will find the manual easier to start with. This document is for checking a rule exactly where the manual points to it (“standard 9.3”).
(5a) The index at the end points, for each term, to the clause and page that define it. Annex B collects the diagnostic messages of the clauses in one place.
(6) Each clause has these parts in this order, leaving out the empty ones:
- Syntax: how it is written in a source (EBNF, annex A).
- Constraints: what is refused at load. Each constraint has a refused example and its message.
- Semantics: what running does.
- Faults and failures: when a run stops, and when a word fails.
- Diagnostics: a table of the messages the processor gives when it refuses.
- Examples: programs that were run, with their output. They show the rules; the text defines them.
(7) A change of the stack is written before → after, with the top on the right: a b → b a exchanges the top two values. “shall” is a rule for programs; “the processor refuses” is a rule for implementations. A paragraph number such as (3a) is a paragraph inserted later; a number once used is never changed.