# AllSpeak curriculum

A practical guide to writing idiomatic AllSpeak. Two tiers:

- **Reference** answers *what is this thing in AllSpeak?* — symbols, variables, control flow, modules. Stable, encyclopedic.
- **Idioms** answers *how do I do X the AllSpeak way?* — patterns with worked examples and explicit anti-patterns.

See [README.md](README.md) for how to view this curriculum and how to add or edit a page.

## Reference

1. [Structure](reference/01-structure.md) — domains, the compiler-tries-each-domain model, how plugins extend vocabulary.
2. [Symbols and layout](reference/02-symbols-and-layout.md) — the four punctuation symbols; doc-block markers; indenting and naming.
3. [Variables and arrays](reference/03-variables-and-arrays.md) — the cursor model; scratch variables; `variable` vs typed.
4. [Collections](reference/04-collections.md) — arrays, dictionaries, lists, properties; JS/Python divergence.
5. [Values and types](reference/05-values-and-types.md) — numbers, strings, booleans; automatic conversion.
6. [Conditions](reference/06-conditions.md) — equality, comparison, presence; combining with `and` / `or`.
7. [Arithmetic](reference/07-arithmetic.md) — integer-first model; scaled-integer pattern; trigonometry.
8. [Strings and text](reference/08-strings-and-text.md) — `length of`, slicing, `position of`, `replace`.
9. [Control flow](reference/09-control-flow.md) — `if`, `while`, `gosub` with parameters, `put parameter`, `stack`, `stop`, `exit`.
10. [Errors and recovery](reference/10-errors-and-recovery.md) — `or` (stop) vs `on failure` (continue).
11. [Cooperative multitasking](reference/11-cooperative-multitasking.md) — `fork`, `wait`, never-interrupted-mid-statement.
12. [Modules](reference/12-modules.md) — `run`, `release parent`, message passing.
13. [Plugins](reference/13-plugins.md) — the contract; the mixed-stack performance principle.
14. [Browser and Webson](reference/14-browser-and-webson.md) — DOM types, `attach`, the Webson layout dialect.
15. [Multilingual](reference/15-multilingual.md) — the `language` directive and the pack model.
16. [Doc blocks](reference/16-doc-blocks.md) — the `!!` / `!!!` convention; `asdoc-check`.
17. [Dev-environment commands](reference/17-dev-environment.md) — Python-runtime `system`, `download`, `browse` for shell, fetch, and tab-launch.
18. [JSON](reference/18-json.md) — `save` auto-encodes dict/list; `append … to json file`; `json of` for parsing; the parent-dir caveat.
19. [Testing](reference/19-testing.md) — `check` assertions, `test … end test` cases, failure clauses, the `--test` runner and exit codes.
20. [Desktop graphics (Qt)](reference/20-graphics.md) — the Python runtime's PySide6 GUI domain: `use graphics`, widgets, layouts, events, dialogs.

## Idioms

1. [`cat` and string building](idioms/01-cat-and-string-building.md) — infix `cat`, template patterns, greedy-parsing gotcha.
2. [Event handlers and array index](idioms/02-event-handlers-and-array-index.md) — single handler for an array of elements.
3. [Looping patterns](idioms/03-looping-patterns.md) — `while` vs label-driven loops.
4. [Picking a collection shape](idioms/04-picking-a-collection-shape.md) — variable-array vs dict vs list vs property.
5. [Floats and scaled integers](idioms/05-floats-and-scaled-integers.md) — fractional precision without floats.
6. [REST and async](idioms/06-rest-and-async.md) — `rest get`, failure clauses, yielding while waiting.
7. [MQTT pub/sub](idioms/07-mqtt-pubsub.md) — the connection block, dict-shaped payloads, request/reply.
8. [Webson and AS separation](idioms/08-webson-and-as-separation.md) — layout in `.json`, logic in `.as`.
9. [Extracting a module](idioms/09-extracting-a-module.md) — when and how to split a script.
10. [Writing language-neutral](idioms/10-writing-language-neutral.md) — what the language pack doesn't translate.
11. [Debugging .as](idioms/11-debugging-as.md) — `print`, `log`, tracer, `dummy`.
12. [Working with AI](idioms/12-working-with-ai.md) — the AI-writes / human-reviews workflow.
13. [Server as application](idioms/13-server-as-application.md) — running `server.as -t edit,<project>` so the server *is* the app and the browser tabs are its UI.
14. [Building a desktop window](idioms/14-desktop-gui.md) — a PySide6 window in AllSpeak: declarations, layout, `on` handlers, and the event-loop model.
15. [Boolean flags](idioms/15-boolean-flags.md) — the on/off state idiom: `clear X` to initialize, `set X`/`clear X` to toggle, bare `if X` to test.