The implementation language is Python, fixed by this Target's `TECHNOLOGY_STACK.md` and governed by `stack/python.md`.
The interface contract
Exit codes follow jq's own, and the distinction is load-bearing because the harness grades on it:
It writes each value the program produces to **stdout** as one compact JSON value per line, and exits `0`.
Follow `sources/lexer.l` and `sources/parser.y` directly. Produce an AST.
Precedence, `?` suffixes, string interpolation, and the `def` forms are all settled there.
jq is a small language with a large semantic core.
The module *grammar* cases are **not** excluded and must pass.
Almost every filter is a **generator**:
it takes one input and produces a stream of zero, one, or many outputs, and downstream
filters run once per upstream output.
A case may legitimately emit several values and then raise; the harness compares the values
produced before the raise, so exit `5` is not by itself a failure.
`reduce`, `foreach`, `limit`, `first`,
`label`/`break`, and the `?//` destructuring alternative are all defined in terms of it.
Numbers and edge cases. `nan`, `infinite`, integer/float equality, large literals,
and the `have_decnum` builtin — return `false` from it and the corpus takes its
non-decNumber branch, which native floats satisfy.
field access, iteration, arithmetic, comparison, and
`empty`.
Get the core correctly before reaching for coverage.
Builtins. Work outward from `sources/builtin.jq` and the manual: strings, arrays, objects,
These four files are the exam. They are hash-verified against the import and restored
before grading, so a modification is reported as tampering rather than honoured:
Every later feature is expressed in terms of this.
`//`,
`reduce`, `foreach`, `label`/`break`, `limit`, `first`, `last`, `until`, `while`,
`recurse`.
Control flow. `if`/`then`/`elif`/`else`/`end`, `try`/`catch` and `?`, `//`,
`label`/`break`
`reduce`, `foreach`, `limit`, `first`, `last`, `until`, `while`,
`recurse`.
Functions, variables, and destructuring.
`def` with arity and closures,
`def` with arity and closures, `as`
bindings,
object and array patterns, and the `?//` alternative operator.
Paths and assignment. `path(f)`, getpath, setpath, delpaths, del,
`path(f)`, `getpath`, `setpath`, `delpaths`, `del`,
and then `=`, `|=`, `+=`, and friends.
Assignment is defined over path expressions, so this
cannot precede step 2.
Builtins. Work outward from `sources/builtin.jq` and the manual: strings, arrays, objects,
`sort_by`/`group_by`/`unique_by`,
objects,
`in`,
strings,
`@base64`/`@uri`/`@csv`/`@tsv`/`@sh`
formats,
the date functions, `tostream`, `input`/`inputs`, `$__loc__`, `debug`.
the date functions,
`input`/`inputs`,
`$__loc__`, `debug`.
`tostream`,
Every other story runs its own slice, and the slice executes cases.
Definition of Done