The tutorial vault is the reading club the HQL book runs
against: seven books, five authors, the links between them, one relation card,
the librarian agent card, and an embedding index built for the questions the
book asks. Every program in doc/public/learn/ runs against it.
The notebook documents are rendered against the tutorial vault: a reading list whose cells share values by id, and a meeting note whose cells retrieve evidence, run an agent over the draft and remember the answer, written as design.
The birds wiki pairs HyperMarkDown cards with runnable HQL programs for collection types. It includes two intentional errors to show where sorted-key constraints and duplicate-key checks are enforced.
The mapreduce shelf is six book cards to filter, group and reduce, read as a chain of steps.
The structural cases read Data as declared
types: closed records, open views over Data, and {:} as a declared map,
from HQL-0030.
The decimal cases compute with Decimal, the exact
decimal number a literal with a decimal point is: exact sums, the scale kept
for display, Int widening, half-even round, and JSON, YAML and CSV
carrying every digit, from HQL-0031.
The braces cases tell a set from Data by the colon:
{} is the empty set and {:} the empty record, from
HQL-0029.
The functions cases declare, bind, pass and return functions, with one intentional error for a parameter type.
The streams cases generate values with yield, end an
unbounded stream with take, and refuse yield outside a fn block body.
The windows cases rank and compare rows within their
partition with over, and order ties with then, from
HQL-0050.
The crypto cases are design input for
HQL-0053: Bytes, keys read from
PEM, signatures over text and canonical JSON, HMAC, Argon2id password
hashes, encryption under a shared key and to an age recipient, encrypted
files, and keys reached through a configured key vault.
The slicing cases take a position with xs[i] and a
slice with xs[a:b] over strings, lists, documents, streams and a declared
type, from HQL-0026.
The constructors cases call a type's constructor
and pipe into it, declare a program's own constructors told apart by their
first parameter, pass one to map, parse text by constructing Data, from
HQL-0018, and build a Table that each
format writes with its columns in the order named, from
HQL-0017.
The overloads cases call the standard operations a
name declares more than once: positional arguments, forms chosen by their
arguments' types, steps lifted over absence, and the narrowing filter.
The receivers cases call a declaration that takes
self as value.f(), and refuse it for one whose first parameter is not a
receiver, from HQL-0024 part 12.
The generic traits cases give a trait and an
implementation type parameters, impl<T> Index<T> for Ring<T>, and infer a
bound's open parameter from the implementation a call reaches, from
HQL-0027.
The traits cases name a trait's type,
trait Shape as Figure, the union of the types that implement it, from
HQL-0039.
The error handling cases are each wrong on purpose: a syntax failure, a name error, a type error, a broken trait contract or an evaluation failure, and an effect before each error shows whether the program ran, from HQL-0044.
The I/O cases read a JSON Lines file and a CSV file with
source, each document decoded as the record its binding declares, from
HQL-0021.
The file system cases list a folder, walk a tree in sorted
order, match a glob and test a path with io.fs, from
HQL-0040.
The data sources cases read the sources a vault's
hql.toml configures by id with source("id"): two vaults side by side, a
CSV file and a JSON array, typed from the configuration before anything is
read, from HQL-0012.
The pipelines shop is the vault Part II of the book runs against: files, a SQLite table, PostgreSQL, Kafka, NATS and a lakehouse, each under an id. What is on this machine runs here; a program over a server is checked here and runs in the hql-demo repository, from HQL-0046 and HQL-0049.
The doc strings sessions print /// doc strings
with :help, :type and hql help: a program's own function, overloads
documented in part, a standard overload set, a citation printed as a
versioned URL, and an unknown name, from
HQL-0042.
The todo board lists open tasks and architecture decisions
with hql#eval cells, reading typed sort keys out of card metadata.
The Mighty Types programs walk the language as a
textbook would: records, unions, options, results, traits, operators, generics,
closures, iterators, the standard library, modules written in HQL with their
private helpers and the dataflow operations of a dataframe. Its lib/ folder
is a module root, not a set of cases.
Build the CLI from the repository root with cargo build --locked, then follow
the commands in the example's README. Query headers record their expected type
or diagnostic; the cards form the vault those queries read. A header may also
say status: proposed with implementation: pending and a proposal: naming
the record that specifies it: such a case is a design input, pinned before it
runs, and the harness asserts it does not check yet. A modules: line names a
module root under examples/ that the program imports from, and io: sandbox
says the program reads and writes files relative to its own directory, so the
harness runs it in a temporary copy of its example.