Guide

One page per mechanism: what it does, how it works, and why it is shaped that way. The pages do not depend on being read in order; start with the one whose topic has come up in your code.

Reading and evaluation

Page	Covers
Model of evaluation	Forms; the read, expand, compile, and evaluate stages; which stage an error names; code as data
Koskari and s-expressions	Each layout rule beside the s-expression it reads to, and where parentheses stay
Brackets and the call convention	( ) is a call and [ ] is data; the bracket-pair marker and its pragma
Name resolution and prefixes	The runtime, compile-time, and layout slots; how (foo ...) resolves; compile/ and layout/

Names and values

Page	Covers
Bindings and refs	var, def, let, set!, shadowing; namespaces, bind versus store, ref, deref, resolve, unpack
References and storage indirection	Refs as location handles, &, writing through a ref, bind!, take!, dynamic refs
Data structures	Python containers, pairs, quote and quasiquote, symbols and keywords
Types and annotations	:: annotations, where they land, checking values at runtime

Functions and control

Page	Covers
Functions	Formals, defaults, rest collectors, return and multiple values, closures, recursion and named let, thunks
Decorators	The @ surface end to end: reader, decorate, graft and call-time families, extending it
Control flow	if, cond, when, unless, while, for-each, break with a value, the -each family
Match patterns	The match pattern language: sequences, classes, mappings, typed captures, guards
Idiomatic Koskari	The direct form over the assembled one: item-slice, dotted set!, var patterns, None?, unless

Programs

Page	Covers
Modules and packages	The shape of a file, imports, the entry point, packages on disk, the .py/.ki same-name trap, sys.path
I/O and effects	print, with, exceptions and try as an expression, stores, async effects
Demand, async, and defer	Ambient await, the demand path, defer, and which construct to reach for
Hosting Koskari from Python	The import hook, running a file into a namespace, awaiting Koskari functions from Python
Packaging an installed command	koskari_scripts entry points and the setuptools plugin
Runtime tuning	The per-site attribute cache and read-only code storage, and their pragmas

Syntax extension

Page	Covers
Macros and hygiene	What a macro is for, syntax, templates versus procedures, hygiene, expansion order
Hygiene	What capture is, the gensym a template symbol becomes, how the expander scopes an expansion, how the compiler resolves it
Fences	Foreign literals as compile-time transliteration; when a format earns one
Pragmas and feature settings	Setting and reading a pragma; every reader/*, compiler/*, and pragma/* setting