About this book

Pinax is a small scripting language to embed in C programs. It takes one block of memory and runs only inside it; it has no garbage collector and no heap. Words pass values over a stack, and inside a word values have names. Types and the depth of the stack are all checked when a program is loaded.

This book is for people who write programs in Pinax. It is meant to be read in order, from start to end. Each chapter opens with what it builds on and the questions it answers, and ends with a summary. Each rule in a summary names the clause of the standard that states it. Where this book and the standard disagree, the standard is right.

Every program in the book was run, and the output printed is the output captured then. The book also shows many programs that are refused, because knowing why a program is refused is the quickest way to know the rules of a language. The output of a refused program is the processor’s message, word for word.

There are no exercises. The Q&A boxes in the text answer, on the spot, a question likely to come up while reading. The Common mistake boxes are the places where people new to the language really do stumble.

A stack machine is new to many readers, so the book often follows a line of code through a table: each row is one token, the stack after it (the top on the right) and what happened. Chapter 2 explains the stack from the ground up; if the order of values and words ever seems backwards, go back to it. The remarks in the examples (after rem) say what each line does. Chapter 16 lists the messages you are most likely to meet, with what they mean and how to fix them. The index at the end points to where a term is defined and where a word is first introduced.

The examples are in docs/manual/examples/ of the repository; run one with pnx FILE.