The FormScript tutorial

Seventeen short sections, in the order that makes them easiest to learn. Each one explains one idea and shows it in a form you can run.

Every example on these pages is a complete document. Copy one into the playground and press run — the playground loads the reference implementation itself, so what you see is what a conforming runtime produces.

The sections

• 1What FormScript isThe idea of the language, and a first form that runs.
• 2SyntaxThe shape of a document, from the version line to the closing brace.
• 3Fields and typesEvery type a field can have, and why integer and number are not the same.
• 4Values and defaultsvalue, default, and the reactive model in one page.
• 5ExpressionsThe operators, and the rule that no expression ever fails.
• 6Absence and logicThe four kinds of not-an-answer, and why logic is three-valued.
• 7The builtin librarySixty-eight functions, grouped by purpose.
• 8Lists and comprehensionsReading a list, and writing the expressions that read it.
• 9Validationrequired, min, max, pattern, custom — the rules an answer must satisfy.
• 10Conditional questionswhen, applicability, and the rule that a new element reads its own guard.
• 11Groups, repeats, choices, sectionsgroup, repeat, choice, section, page — and what each one means.
• 12Statestate, save-and-resume, and where a state name lives.
• 13The output documentThe output document, the output block, and the four ways a field can be missing from it.
• 14Text and languagesLabels live in a text block, and t() reads them.
• 15Errors and diagnosticsThe diagnostics, their codes, and the order they are reported in.
• 16RenderingThe renderer contract: intents in, widgets out.
• 17Tools and runtimesHow to run FormScript, and how to check an implementation against the words.

What you need to know first

Nothing. FormScript is not JavaScript, not SQL and not HTML, and none of those habits are useful here. The language has fourteen types, no implicit conversions and no exceptions, so the only thing you need is a willingness to read what a document says.

If you would rather read the whole language in one page, there is the language section by section. If you want the formal version, there is the specification.

How to read the course

Each section stands on its own, but the order matters: a section uses the vocabulary of the sections before it. The ideas that are hardest in a language like this one — what an unanswered question is, and when a computed value recomputes — get a section each, in the middle of the course, where you have the rest of the vocabulary to read them with.

The last three sections are about the tooling: how to read a diagnostic, how a renderer is given a form, and how to run the language outside this site.