The code language

The twelve axes

CXPath supports twelve axes. The default axis is child, so name ≡ child::name. The full set:

The common idioms, one per axis — all descendants of a section, the section enclosing a code block, the users after the first, the table around a row, the sibling just before a code block, an attribute filter, and the attribute axis spelled in full (//user/attribute::email is //user/@email):

          [doc
  [section [h2 'T'] [code 'x'] [p 'q']]
  [users
    [user role='admin' email='a@example.org']
    [user role='user'  email='b@example.org']]
  [table [tr [td 1]]]]
        

          ([$count //section/descendant::*],
 [$name [$first //code/ancestor::section]],
 //user[1]/following-sibling::user/@email,
 [$name [$first //tr/parent::table]],
 [$name [$first //code/preceding-sibling::*[1]]],
 //user[= $_@role 'admin']/@email,
 //user/attribute::email)
        

          $ cx --data=input.cx prog.cx
(3, section, [email b@example.org], table, h2, [email a@example.org], ([email a@example.org], [email b@example.org]))
        

The same step vocabulary applies from a binding (grammar [135a]): $u/name (child), $u//item (descendant), $u@email (attribute), $u/.. (parent), and $m.key (map-key access on a map-valued binding). See bindings.

Predicates — positional, attribute, function, composite

A predicate is [...] after a step. The predicate body is prefix CX code over the context node $_ — plus a small set of atomic shorthands. The admitted shapes:

• Positional — INT selects the Nth match (1-indexed). //section[1] is the first section. Negative positions are NOT supported; [$_last] selects the last, [= $_position N] the Nth.
• Attribute test — [@name] (attribute present) and [@!name] (attribute absent). Value comparisons are prefix forms: [= $_@name V], [!= …], [< …] etc.
• Step-existence — a bare child name: [h2] keeps elements that have an h2 child.
• Prefix expression — any prefix CX form over $_: comparisons ([= $_@id 42]), boolean combinators ([and …] / [or …] / [not …]), and function calls ([$strings:contains $_@email '@example.com']).

          [site
  [user id=42 active=true email='ada@example.com' age=30 country='US']
  [user id=7 email='bob@else.org' age=17 country='US']
  [section [h2 'A'] [p 'x']]
  [section [p 'y']]]
        

          [?lib 'cx-stdlib/strings']
(//user[1]/@id,
 //user[= $_@id 42]/@email,
 [$count //user[@active]],
 //user[$strings:contains $_@email '@example.com']/@id,
 //user[and [>= $_@age 18] [= $_@country 'US']]/@id,
 [$count //section[h2]],
 [$count //section[and [$count $_/h2] [$count $_/p]]])
        

          $ cx --data=input.cx prog.cx
([id 42], [email ada@example.com], 1, [id 42], [id 42], 1, 1)
        

Predicates chain: //user[= $_@active true][1] is the first active user — the second predicate filters the result of the first. The order matters.

Comparison — one operator family

One operator syntax: = != < <= > >=. No keyword synonyms (eq / ne / lt / ...) — they are not in the grammar. Semantics are value-comparison: both sides must be single values; a multi-valued operand raises CXER0103; no type coercion.

This is the deliberate divergence from XPath 3.1's general-comparison default. In XPath, //x = 1 is true if any x equals 1 — a common gotcha when the path silently returns multiple nodes. In CX, the path must return a single value, or the comparison raises. To express "any equals", filter the sequence itself: [$exists //user/tag[= [$text $_] 'admin']].

          [site
  [user age=42 email='ada@example.com' [tag 'admin'] [tag 'dev']]
  [section [p 1] [p 2] [p 3] [p 4]]]
        

          (//user[= $_@age 42]/@email,
 [$count //section[> [$count $_/p] 3]],
 //user[= $_@email 'ada@example.com']/@age,
 [$exists //user/tag[= [$text $_] 'admin']])
        

          $ cx --data=input.cx prog.cx
([email ada@example.com], 1, [age 42], true)
        

Paths on bindings

A CXPath rooted at a binding navigates from that value instead of from the document root:

$u/name is the direct child, $u/* all children, $u//item the descendants, $u@active the attribute shorthand and $u/@active the full axis form:

          [?let [= $u [user active=true region='EU'
             [name 'Ada'] [item 1] [item 2]]]
  ($u/name, $u/*, $u//item, $u@active, $u/@active)]
        

          $ cx prog.cx
(Ada, ([name Ada], [item 1], [item 2]), ([item 1], [item 2]), true, true)
        

The path operators that work on bindings are the same operators that work on the implicit document — one vocabulary. The leading // form is anchored at the document root, regardless of context; $u//x is anchored at $u. Use //x to escape upward when you already have a binding. Parent and map-key steps ride the same surface (grammar [135a]): $u/.. steps to the parent, and $m.key reads a key from a map-valued binding.

Where CXPath values are accepted

CXPath is a value kind. Every construct that takes "a selector" accepts a CXPath value:

          [site [admin 'root'] [meta config='prod'] [user active=true status='new'] [prose 'p']]
        

          [?let [= $n [$first //prose]]
  ([?for [in $u //user[= $_@active true]] [yield [seen $u@status]]],
   [?if //admin [then [admin-panel]] [else ()]],
   [?match $n [case //prose [p [$text $n]]] [else ()]],
   [?let [= $cfg //meta/@config] [$string $cfg]],
   [?modify $doc //user/@status [set 'verified']],
   [$count //user[= $_@active true]])]
        

          $ cx --data=input.cx prog.cx
([seen new], [admin-panel], [p p], prod, [site [admin root] [meta config=prod] [user active=true status=verified] [prose p]], 1)
        

A path appears as a [?for] generator, as an [?if] condition, as a [?match] arm, as a [?let] initializer, as a [?modify] focus, and as a builtin argument — the six positions above, in that order. This is the unification we ratify: no separate "path syntax" per construct.

Status note. CXPath value-kind at non-[?for] positions is production-ready in V; full Tier-2 binding parity is tracked in spec/03-approved/misc/parity-matrix.md.

Deliberate divergences from XPath 3.1

CXPath is a working subset of XPath 3.1 + deliberate changes. The normative treatment is spec/03-approved/core/code.md §5.5; the headline differences:

• One comparison family (= != < <= > >=) — XPath's split into general (=) and value (eq) is gone; CX uses value-comparison semantics exclusively. Rationale: the general-comparison gotcha is XPath's most-reported source of subtle bugs.
• Path is a value kind — XPath paths are syntactic fragments inside XPath expressions only. In CX they are first-class values.
• 1-indexed positions — adopted from XPath verbatim (//x[1] is the first), but CX explicitly rejects [0] (raises CXER0100); XPath silently yields the empty sequence.
• No general-purpose for / let inside paths — CX moves binding into the [?for] / [?let] directive surface; predicates take expressions but not binding clauses. Use the surrounding directive.
• No paren-calls anywhere — XPath's count(//user) spelling does not exist; every call is the head-dispatch form [$count //user], in predicates too ([> [$count $_/*] 0]). position() / last() are the reserved predicate bindings $_position / $_last.

The normative CXPath treatment — semantics, the desugar table, and predicate evaluation — is spec/03-approved/core/code.md §5.5; the XPath 3.1 parity corpus is conformance/xpath_31_parity.cxd.

Element-shape patterns

An element-shape pattern matches an element by name, attributes, and (recursively) body content. The pattern uses ordinary CX syntax with bind-holes where you want to capture values:

[user email=$e] binds the email attribute; [user @active=true $u] filters on an attribute and binds the whole user; [user @id=42 [name $n]] binds a child's body; [post author=$a body=$b] binds two attributes:

          [site
  [user id=42 active=true email='ada@example.com' [name 'Ada']]
  [post author='ada' body='hello']]
        

          ([?for [user email=$e] [yield $e]],
 [?for [user @active=true $u] [yield $u@id]],
 [?for [user @id=42 [name $n]] [yield $n]],
 [?for [post author=$a body=$b] [yield [pair $a $b]]])
        

          $ cx --data=input.cx prog.cx
('ada@example.com', 42, Ada, [pair 'ada' 'hello'])
        

Binding semantics depend on context. A pattern [NAME $x] without attribute predicates auto-unwraps the body — text body binds the string, scalar body binds the scalar, empty body binds the element itself, structured body binds the element. A pattern [NAME @attr… $x] with attribute predicates always binds $x to the matched element. The rationale is in spec/03-approved/core/code.md §5.2 rule 5: when you name attributes you are filtering "what kind of element", so the bind value is the element; when you don't, the bind value is the inner content.

Scalar literal patterns

Scalar literals are valid patterns. They match by value-equality:

          [?for [in $status (200, 404, 500, 'admin', true, null, 7)]
  [yield [?match $status
    [case 200     :ok]
    [case 404     :not-found]
    [case 500     :server-error]
    [case 'admin' :elevated]
    [case true    :enabled]
    [case null    :missing]
    [else         :unknown]]]]
        

          $ cx prog.cx
:ok
:not-found
:server-error
:elevated
:enabled
:missing
:unknown
        

Integers, floats, strings, bools, dates, datetimes, and null are all matchable as scalar literals. Float equality follows IEEE-754 — nan is never equal to nan. Test for NaN explicitly with [?lib 'cx-stdlib/math'] and [$math:is-nan $x].

CXPath patterns

A CXPath value used as a pattern matches if the candidate value is in the path's result sequence:

          [doc [heading 'Title'] [prose 'Body.']]
        

          [?let [= $node [$first //heading]]
  [?match $node
    [case //heading [h2 [$text $node]]]
    [case //prose   [p  [$text $node]]]
    [else           $node]]]
        

          $ cx --data=input.cx prog.cx
[h2 Title]
        

In a [?for] body, the same CXPath as the generator selects directly:

          [users [user email='ada@example.org' active=true]
       [user email='bob@example.org' active=false]]
        

          [?for [in $u //user[= $_@active true]] [yield $u@email]]
        

          $ cx --data=input.cx prog.cx
'ada@example.org'
        

CXPath patterns and element-shape patterns compose in the same arm list — [?match] can dispatch on a mix of both, with first-match-wins ordering (see match).

Wildcards — *, **, _

Three wildcard forms:

• * — any single element. [* $x] matches any element and binds it. [section * $body] matches any section and binds the body wildcard slot.
• ** — recursive descent. [**] matches any element at this position or deeper. Wrapping an inner pattern — [** [user $u]] — matches a user anywhere in the body and binds it.
• _ — anything, no bind. _ matches any value (including non-elements) without binding it. The idiomatic catch-all in [?match].

          [?let [= $node [section [h2 'T'] [code 'x = 1']]]
  [?match $node
    [case [section * $body] [matched-section]]
    [case [** [code $c]]    [highlighted $c]]
    [case _                 $node]]]
        

          $ cx prog.cx
[matched-section]
        

Named bindings — $name

$name (lowercase, leading $) is a binding hole. It appears in attribute-value position ([user email=$e]), in body position ([user $u]), and in a destructuring [?for] generator ([?for [in [user $u] /users/user] …]).

A bind hole always succeeds at its position; the bind value depends on what the surrounding pattern dictates (see pattern-element-shape). Naming collisions inside one arm raise CXER0100 (PARSE_ERROR) — [user @id=$x @name=$x] would require the values be equal, which the current spec does not support; use a single bind and check with a [when …] clause.

Type-guard heads

A type guard :TypeName at pattern-head position narrows by schema-typed shape:

          [?let [= $cfg [server-config host='a.example.org']]
  [?match $cfg
    [case [:ServerConfig $c] [server $c]]
    [case [:ClientConfig $c] [client $c]]
    [else [result status=err reason='unknown config']]]]
        

          $ cx prog.cx
error: cx-err:CXER0100: [:ServerConfig] names schema type `ServerConfig` but NO schema is in scope — declare one with `[?cx schema=PATH.cxs]`, carry it inline with `[?cx schema-inline …]`, or pin it in cx.lock (schema.md §13; code.md §5.4)
        

Type-guard resolution is by the document's schema binding (see schema in the data section); with no schema in scope a type guard is refused at program load, as the fixture above shows (CXER0100, naming the type and the three ways to bring a schema into scope). Pair with schema binding ([?cx schema='…']) for type-driven dispatch.

[?for] — iteration

[?for] is the iteration / comprehension primitive. The expression in the [in …] clause is either a CXPath (yields a sequence to iterate), a pattern (matches the generator — the [?find] replacement), or any expression that evaluates to a sequence.

          [site
  [user id=1 email='ada@example.com'   age=36 active=true]
  [user id=2 email='grace@example.com' age=17 active=false]
  [post author=1 [title 'Notes']]
  [request 'r1'] [request 'r2']
  [logs [row 'a'] [row 'b']]]
        

          ([; the path generator ]
 ([?for [in $u //user] [yield $u@email]]),
 [; the pattern generator ]
 [?for [user @active=true $u] [yield $u@email]],
 [; a where filter ]
 [?for [in $u //user] [where [>= $u@age 18]] [yield $u@id]],
 [; two generators, in declared order ]
 [?for [in $u //user]
       [in $p //post[= $_@author $u@id]]
       [yield [pair user=$u@id post=[$text $p/title]]]],
 [; parallel evaluation, results in source order ]
 ([?for [in $r //request] [par] [yield [got [$text $r]]]]),
 [; lazy evaluation over a large input ]
 ([?for [in $row //logs/row] [lazy] [yield [$text $row]]]))
        

          $ cx --data=input.cx prog.cx
(('ada@example.com', 'grace@example.com'), 'ada@example.com', 1, [pair user=1 post=Notes], ([got r1], [got r2]), (a, b))
        

[par] and [lazy] are evaluation-modifier clauses — same surface, different scheduler. [par] distributes iterations across a bounded worker pool (min(4, ncpu) workers by default; [par N] caps it at N) and always reassembles results in source order — the retired [ordered] clause survives as a tombstoned no-op. [lazy] couples the generator to a streaming input source so that the iteration runs in bounded memory regardless of input size. Full semantics in spec/03-approved/core/code.md §7.

Multiple [where …] clauses AND together; multiple [yield …] clauses concatenate (per the sequence-flat principle — yields never produce a list-of-lists).

[?match] — dispatch (single + multi-arm)

[?match] is pattern dispatch. CX supports two forms: 2-arg destructure (single arm, asserts the value matches or raises) and multi-arm (first-match- wins across N arms). The multi-arm form is a recent addition.

Single-arm form — pattern-bind a value and assert the shape:

          [?let [= $result [ok 42]]
  [?match $result [ok $v] [yield [rendered $v]]]]
        

          $ cx prog.cx
[rendered 42]
        

Multi-arm form — first-match-wins across [case …] / [when …] / [else …] clauses. Arms may mix element-shape patterns, scalar literals, CXPath paths, wildcards, and predicate-only [when …] clauses:

          ([?let [= $node [code 'x = 1']]
   [?match $node
     [case [prose $p]   [p $p]]
     [case [code $c]    [pre $c]]
     [case 'separator'  [hr]]
     [else              ()]]],
 [; predicate-only arms, no scrutinee ]
 [?let [= $x 120] [= $y 10]
   [?match
     [when [> $x 100]   :big]
     [when [> $y 50]    :medium]
     [else              :small]]],
 [; a guard on a case arm ]
 [?let [= $req [http-get '/admin']]
   [?match $req
     [case [http-get $u] [where [= $u '/admin']] [route $u]]
     [case [http-get $u]                         [status 403]]
     [else                                       [status 400]]]])
        

          $ cx prog.cx
([pre x = 1], :big, [route /admin])
        

Arm semantics:

• [case PAT R] — match against pattern PAT. Arms evaluate top-to-bottom; the first one whose pattern matches "wins". Later arms are not tried, even if they would also have matched.
• [when PRED R] — match iff predicate truthy. No pattern; the predicate is evaluated with the scrutinee in scope as $_ (and any earlier [case …] bindings still in scope only if the same arm).
• [else R] — catch-all, always last. Equivalent to [case _ R]. Multiple [else …] clauses raise CXER0100.
• [case PAT [where PRED] R] — guard on a case arm. The pattern must match AND the predicate must be truthy.
• No implicit EBV in [case …]. [case …] tests pattern equality / structural match; it does not apply EBV. [when …] uses EBV.

No-match behavior differs by form. The 2-arg form raises CXER0100; the multi-arm form yields () (the empty sequence) if no arm matches and no [else …] is present. An unreachable arm (covered by an earlier arm with no guard) raises a warning at parse time but does not fail compilation.

Status. Multi-arm [?match] is fully spec'd. V's evaluator carries the production-ready implementation; Tier-2 binding parity is per spec/03-approved/misc/parity-matrix.md.

[?if] — boolean branch (with EBV)

[?if cond [then E1] [else E2]] is the explicit boolean branch. The condition is evaluated with the EBV (Effective Boolean Value) rule — see ebv below.

          [site [admin 'root'] [config debug=false]]
        

          ([?if //admin [then [admin-panel]] [else [user-panel]]],
 [?let [= $age 36]
   [?if [>= $age 18] [then :adult] [else :minor]]],
 [?let [= $cfg [$first //config]]
   [?if $cfg@debug [then [debug-trace]] [else ()]]])
        

          $ cx --data=input.cx prog.cx
([admin-panel], :adult)
        

For multi-way conditionals prefer [?match] multi-arm (see match). [?if] stays separate from [?match] because they have different contracts — [?if] uses EBV (truthy/falsy with container rules), [?match] [case …] does not (it tests strictly by structural equality / pattern match).

The [else …] clause is optional. When omitted, an untrue condition yields () (the empty sequence). Many CX idioms exploit this — [?if $n@hidden [then ()] [else [$render $n]]] reads as "render unless hidden".

[?let] — binding

[?let] introduces a local binding. The bound name is in scope inside the body that follows.

          [meta host='api.example.com' port='8443']
        

          [?let [= $meta [$first //meta]]
      [= $base [$string $meta@host]]
      [= $port [$string $meta@port]]
      [= $url  [$concat 'https://' $base ':' $port]]
  [endpoint target=$url]]
        

          $ cx --data=input.cx prog.cx
[endpoint target='https://api.example.com:8443']
        

[?let] is the only way to give an expression a name currently — there is no def inside a function body, no inline where (that is a [?for] filter). To name a value that is used multiple times, [?let] is idiomatic.

[?modify] — pure-functional updates

[?modify] is the update directive. It takes a document (or sub-tree), a CXPath focus, and one or more action slots; it returns a new document with the action applied at every focus match. The original is unchanged (pure-functional).

The eleven action slots are:

Every action on one document, in the table's order — then a three-step pipeline (see pipe); each result is a new document, and the twelve results below share one unchanged original:

          [doc
  [user id=1 name='Ada' active=true]
  [user id=2 name='Bob' active=false banned=true]
  [section id='intro' [para 'Hi.']]
  [list [item 'a']]
  [h2 'T'] [code 'x'] [price 10.0] [para 'p'] [deprecated 'old']]
        

          ([?modify $doc //user[= $_@id 1]/@name [set 'Alice']],
 [?modify $doc //user[= $_@active false] [delete]],
 [?modify $doc //price [using [?fn ($p) [* $p 1.1]]]],
 [?modify $doc //para [rename p]],
 [?modify $doc //user [set-attr verified true]],
 [?modify $doc //user [delete-attr banned]],
 [?modify $doc //section[= $_@id 'intro'] [append [para 'Added.']]],
 [?modify $doc //list [prepend [item 'header item']]],
 [?modify $doc //h2 [insert-before [hr]]],
 [?modify $doc //code [insert-after [aside 'note']]],
 [?modify $doc //deprecated [replace ()]],
 [?pipe $doc
   [?modify //user/@status [set 'verified']]
   [?modify //user[= $_@banned true] [delete]]
   [?modify //user [set-attr last-audit '2026-05-22']]])
        

          $ cx --data=input.cx prog.cx
([doc [user id=1 name=Alice active=true] [user id=2 name=Bob active=false banned=true] [section id=intro [para Hi.]] [list [item a]] [h2 T] [code x] [price 10.0] [para p] [deprecated old]], [doc [user id=1 name=Ada active=true] [section id=intro [para Hi.]] [list [item a]] [h2 T] [code x] [price 10.0] [para p] [deprecated old]], [doc [user id=1 name=Ada active=true] [user id=2 name=Bob active=false banned=true] [section id=intro [para Hi.]] [list [item a]] [h2 T] [code x] 11.00 [para p] [deprecated old]], [doc [user id=1 name=Ada active=true] [user id=2 name=Bob active=false banned=true] [section id=intro [p Hi.]] [list [item a]] [h2 T] [code x] [price 10.0] [p p] [deprecated old]], [doc [user id=1 name=Ada active=true verified=true] [user id=2 name=Bob active=false banned=true verified=true] [section id=intro [para Hi.]] [list [item a]] [h2 T] [code x] [price 10.0] [para p] [deprecated old]], [doc [user id=1 name=Ada active=true] [user id=2 name=Bob active=false] [section id=intro [para Hi.]] [list [item a]] [h2 T] [code x] [price 10.0] [para p] [deprecated old]], [doc [user id=1 name=Ada active=true] [user id=2 name=Bob active=false banned=true] [section id=intro [para Hi.] [para Added.]] [list [item a]] [h2 T] [code x] [price 10.0] [para p] [deprecated old]], [doc [user id=1 name=Ada active=true] [user id=2 name=Bob active=false banned=true] [section id=intro [para Hi.]] [list [item header item] [item a]] [h2 T] [code x] [price 10.0] [para p] [deprecated old]], [doc [user id=1 name=Ada active=true] [user id=2 name=Bob active=false banned=true] [section id=intro [para Hi.]] [list [item a]] [hr] [h2 T] [code x] [price 10.0] [para p] [deprecated old]], [doc [user id=1 name=Ada active=true] [user id=2 name=Bob active=false banned=true] [section id=intro [para Hi.]] [list [item a]] [h2 T] [code x] [aside note] [price 10.0] [para p] [deprecated old]], [doc [user id=1 name=Ada active=true] [user id=2 name=Bob active=false banned=true] [section id=intro [para Hi.]] [list [item a]] [h2 T] [code x] [price 10.0] [para p] ()], [doc [user id=1 name=Ada active=true status=verified last-audit='2026-05-22'] [section id=intro [para Hi.]] [list [item a]] [h2 T] [code x] [price 10.0] [para p] [deprecated old]])
        

Pure-functional — structural sharing. [?modify] does not copy the whole tree. Only the spine from root to each matched node is copied; unchanged branches are shared with the original (immutable persistent data structure). The new allocation is O(depth × matches) — the spine, not the document size — and the original $doc value is still valid for read or hash.

Multi-match. The focus path selects a sequence; the action applies to every node in that sequence. Zero matches returns the original unchanged (not an error — the no-match-no-op invariant lets pipelines compose safely). All-matches-at-once means there is no ordering hazard between matches.

Identity invariant. [?modify $doc //x [set v]] where //x matches no nodes returns $doc unchanged — same canonical bytes, same SHA-256. [?modify $doc //x [delete]] where every //x is removed returns a value where [$count //x] is 0. Round-trip through ast-bin / data-bin / JSON preserves the post-modify shape exactly.

Status. [?modify] is fully spec'd. The V evaluator carries the production-ready implementation. Tier-2 binding parity is tracked in spec/03-approved/misc/parity-matrix.md.

Pipelines and composition

The [?pipe] directive threads the output of one expression into the input of the next. Pipelines compose [?modify], [?for], builtins, and user-defined functions into readable top-to-bottom data flow.

          [shop [user active=true age=30]
      [user active=true age=20]
      [user active=false age=40]]
        

          [?pipe //user[= $_@active true]
  [?fn ($us) [?for [in $u $us] [yield $u@age]]]
  [$reverse]
  [$nth _ 1]]
        

          $ cx --data=input.cx prog.cx
20
        

Stages are bare transforms. [?pipe SRC STAGE …] evaluates SRC, then supplies the value to each STAGE left-to-right. A stage is a transform — a bare name, a $ref, or a [$call …] — never wrapped in a keyword (there is no [through] clause). [?pipe 5 add1 add1] → 7.

Stage invocation (§8.9.1). How the value is supplied depends on the stage shape: a hole-form stage carries a single partial-application hole _ and the value fills it ([$get _ '/users/42'] → get(client, '/users/42')); a no-hole stage receives the value appended as its final positional argument (count ≡ [$count _]). A pipe threads exactly one value, so a stage may carry at most one _ (two or more → cx-err:CXER0100). A non-callable stage (a literal, map, or data element) is cx-err:CXER0100 — it never silently passes the value through.

Fan-out behavior. When SRC evaluates to a sequence, a stage sees the whole sequence as a single value (the sequence-flat principle — no implicit per-item dispatch). For a per-item transform, thread a [?fn] lambda that runs the comprehension:

          [users [user name=ada] [user name=bob]]
        

          [?pipe //user
  [?fn ($us) [?for [in $u $us] [yield [decorated name=$u@name]]]]
  [$count]]
        

          $ cx --data=input.cx prog.cx
2
        

[tap f] — observe without diverting (§8.9.2). A [tap f] stage applies f to the current value for its side effect; the value passes through unchanged and f's return is discarded. Inside a stage, _ names the current value, so [tap [$log:info 'seen' fields={v: _}]] logs and flows on. A tap propagates an [err] only when its code is CXER0001 (panic) or CXER0260 (cancellation); every other error is discarded for the data flow (the error-hook still observes it).

Railway short-circuit (§8.9.3). The pipe is a single-channel failure railway: the first stage to yield [err …] skips every remaining stage — taps included — and that [err] is the result. An empty result is not a short-circuit; it flows to the next stage. There is no infix | and no [through] wrapper — both retired.

Sequence built-ins

Operate on a Sequence. Argument may be a CX program sequence, the implicit document, or a single non-sequence value (treated as a 1-element sequence).

Set combinators are reserved operator heads, not [$…] builtins: [union A B], [intersect A B], [except A B]. Slicing / windowing / ordering / grouping are directives and comprehension clauses: [?take], [?drop], [?filter], [?flatten], [order-by …], [group-by …] (see for).

          [site [user active=true] [user active=false]
      [tag 'a'] [tag 'b'] [tag 'a']]
        

          ([$count //user[= $_@active true]],
 [$distinct [?for [in $t //tag] [yield [$text $t]]]],
 [?take 3 [$range 1 100]],
 [union (1, 2) (2, 3)])
        

          $ cx --data=input.cx prog.cx
(1, (a, b), (1, 2, 3), (1, 2, 3))
        

String built-ins

Operate on a String scalar. Non-string scalars are stringified by the canonical scalar printer; element arguments raise CXER0100 unless documented otherwise.

The wider string toolkit — trim, split/join, replace, case-folding variants, padding — is the cx-stdlib/strings module ([?lib 'cx-stdlib/strings'], then [$strings:trim …], [$strings:split …], [$strings:join …], [$strings:replace …]). Regular expressions are cx-stdlib/re. See the Standard-library pages.

          [?lib 'cx-stdlib/strings']
([$upper 'hello world'],
 [$contains 'ada@example.com' '@example.com'],
 [$strings:join ('a', 'b', 'c') ', '],
 [$strings:split 'a,b,c' ','],
 [$strings:replace 'foofoo' 'foo' 'bar'])
        

          $ cx prog.cx
('HELLO WORLD', true, 'a, b, c', (a, b, c), barbar)
        

Numeric built-ins

Operate on numeric scalars. sum/min/max/avg operate on a sequence and skip non-numeric items; floor/ceiling/round/abs operate on a single value. A numeric operand is an int, a float, or one of the exact kinds decimal / bigint — and the exact kinds are their own family, not floats in disguise: a decimal or bigint operand folds exactly (int embeds losslessly), while mixing one with a float raises CXER0100 — [cast] is the only bridge. That is the arithmetic heads' rule; the aggregates are a different operand shape, never a different numeric semantics.

Exact division either terminates or says so: a decimal/bigint quotient that does not terminate raises CXER3002 and the refusal names $math:div-decimal, the verb carrying an explicit precision + mode. There is no default rounding context. /, div and an exact avg are one implementation, so they never disagree. idiv is exempt — an integral quotient always terminates.

Type coercion is the single explicit cast operator — [cast '42' :int], [cast 3 :float], [cast 42 :string] — there is no to-int / to-float family; a failed cast is CXER0290 (E_CAST_FAILED). CX floats are IEEE-754: NaN and ±Inf exist and follow IEEE-754 semantics — test for NaN with [$math:is-nan] from cx-stdlib/math. CXER0101 (E_ARITH_DIVIDE_ZERO) is division or modulo by zero, specifically. Exponentiation is [$math:pow] in cx-stdlib/math.

          [orders [order amount=10] [order amount=32]]
        

          ([$sum [?for [in $o //order] [yield $o@amount]]],
 [$round 3.7],
 [$mod 17 5],
 [cast '42' :int])
        

          $ cx --data=input.cx prog.cx
(42, 4, 2, 42)
        

Logical built-ins

Boolean combinators and EBV-aware tests. and / or short-circuit; not is total over any EBV-typed argument.

and / or / not are bare operator heads ([and P Q], no $ sigil), and so is =: over elements it is structural equality, the same comparison the value operators use. There is no xor / if() / instance-of builtin — branch with [?if], and test types by schema validation or [?match] shape dispatch.

          [site [user verified=true active=true banned=false] [error 'e1']]
        

          [?let [= $u [$first //user]]
  ([and $u@verified $u@active [not $u@banned]],
   [$exists //error],
   [= [a 1] [a 1]])]
        

          $ cx --data=input.cx prog.cx
(true, true, true)
        

Node-accessor built-ins

Operate on an Element node — read structural properties. Script-level equivalents of the Layer-1 binding methods (see layer-1).

Structural navigation is CXPath, not accessor calls: children are $e/*, the parent is //x/parent::* (document-anchored), attributes are $e@name. Inside a predicate the reserved bindings $_position and $_last replace XPath's position() / last() — there are no zero-arity accessor calls.

          [doc [section 'one'] [section 'two']]
        

          ([$name [$first //section]],
 [$string [$first //section]],
 //section[$_last],
 //section[= $_position 1])
        

          $ cx --data=input.cx prog.cx
(section, one, ([section one], [section two]), [section one])
        

Error code registry (CXER0100–0299)

The CXER0100–0299 range is reserved for code-language errors. Errors are organized into subsystems by tens digits. The complete normative map is in spec/03-approved/core/code.md §9.5 — this subsection is the developer-facing summary.

Parse / arithmetic / application — CXER010x:

Nearby classes that are not CXER010x: anchor / merge errors are data-language E codes (spec/03-approved/core/cxdm.md §11); a sized-integer literal out of range is the lex-time CXERLEX-RANGE refusal; a failed cast is CXER0290 (E_CAST_FAILED), recovered by matching on the code or spelling a representable value — coercion is always the explicit [cast V :int] form.

Resilience — CXER014x / CXER015x:

Services — CXER016x:

Client — CXER018x:

Concurrency — CXER020x / CXER022x:

Async — CXER024x / CXER026x:

Visualization — CXER028x:

The CXER0000–0099 range is reserved for data-language errors (parse, validate, canonicalize); see limits in the data section. CXER0300+ is reserved for future subsystems.

Services and clients

[?http-service] declares a named HTTP service with resource handlers. [?http-client] is its client side. Resources handle requests and return responses; the bodies are ordinary CX code.

Service definition:

          [?test-service-client
   [service [?http-service on=http port=0 name="svc-001"
              [resource [get "/hello"] [response status=200 body="world"]]]]
   [client-call [?let [= $c [?http-client target=$test-target]] [?pipe $c [$get _ "/hello"]]]]]
        

          $ cx prog.cx
[response status=200 body=world]
        

The service above is declared on port=0 (the harness picks a free port) and the client call rides through the corpus's own [?test-service-client] helper, which binds $test-target to the running service; the tunables — read-timeout=, write-timeout=, max-body-bytes=, max-connections=, grace-period= — are attributes on the same element.

Resource parameters. Each [resource] declares method=METHOD path=PATH, optional produces= / consumes= MIME attributes, optional [auth …] predicate-expression clause, and a body expression in positional position. PATH supports :name parameter binding — /users/:id exposes $request/path-params/id inside the body.

Request and response shapes:

          [exchange
  [request method='GET' path='/users/42'
    [path-params [id 42]]
    [query-params]
    [headers [header name='Accept' value='application/cx']]
    [body]]
  [response status=200
    [headers [header name='Content-Type' value='application/cx']]
    [body [user id=42]]]]
        

          (//request/@method, //request/path-params/id, //response/@status, //response/body/user/@id)
        

          $ cx --data=input.cx prog.cx
([method GET], [id 42], [status 200], [id 42])
        

Lifecycle. [?http-service] returns a handle. [?service-handle name=N] looks up an existing service. [?stop $handle] initiates graceful shutdown — drains in-flight requests for up to grace-period=, then force-closes; new requests during drain receive HTTP 503 (CXER0166). Process SIGTERM / SIGINT also triggers graceful shutdown.

HTTP client. [?http-client target=URL …] returns a client value; operations pipe through it:

          [?test-service-client
   [service [?http-service on=http port=0 name="svc-002"
              [resource [post "/echo"] [response status=200 [body $request/body]]]]]
   [client-call [?let [= $c [?http-client target=$test-target]] [?pipe $c [$post _ "/echo" [payload value=42]]]]]]
        

          $ cx prog.cx
[response status=200 [body [payload value=42]]]
        

A client takes timeout= and a [resilience …] child (any of the resilience directives) on the same element as target=.

Status. Services are a stable surface; Tier-1 V binding ships the full implementation. Tier-2 bindings expose [?http-client] and [?service-handle] lookup but service-hosting may defer to the host's native HTTP framework. See bindings.

Workers and channels

[?worker] spawns a concurrent worker. [?channel] creates a FIFO message queue. [?send] and [?receive] move values across. [?select] is the multi-way receive.

          [?let [= $ch    [?channel name='jobs' buffer=8]]
      [= $sent1 [?send 1 to=$ch]]
      [= $sent2 [?send 2 to=$ch]]
  ([?receive from=$ch], [?receive from=$ch])]
        

          $ cx prog.cx
(1, 2)
        

A producer worker and a consumer over one channel keep the producer's order:

          [?let [= $ch [?channel name="c8" buffer=4]] [= $_ [?for [in $i (1, 2, 3, 4)] [yield [?send $i to=$ch]]]] [?for [in $j (1, 2, 3, 4)] [yield [?receive from=$ch]]]]
        

          $ cx prog.cx
1
2
3
4
        

Channel semantics. [?channel name=… buffer=N] has a bounded FIFO buffer. buffer=0 is synchronous (rendezvous — send blocks until receive). FIFO ordering is preserved per producer-consumer pair; with multiple producers, per-producer FIFO is preserved but there is no global cross-producer ordering.

Send / receive variants.

• [?send V to=CH] — block when buffer full; returns [ok] once buffered. Returns CXER0200 (CHANNEL_CLOSED) if CH is closed.
• [?try-send V to=CH timeout=DURATION] — same but returns CXER0201 (SEND_TIMEOUT) on buffer-full timeout.
• [?receive from=CH] — block when empty; returns next value. Returns CXER0200 when CH is closed and drained.
• [?try-receive from=CH timeout=DURATION] — same but returns CXER0202 (RECV_TIMEOUT) on empty-channel timeout.
• [?close CH] — mark closed. Subsequent [?send] fails immediately; subsequent [?receive] drains buffered values then returns CHANNEL_CLOSED. Double-close raises CXER0203.

Worker observability. Workers are handle-addressable:

          [?let [= $w [?worker name="w3" [body 42]]] [= $_ [?wait-for worker=$w]] [= $_ [?cancel worker=$w]] [?wait-for worker=$w]]
        

          $ cx prog.cx
42
        

[?wait-for worker=$w] blocks until the worker is done, [?cancel worker=$w] requests cooperative cancellation (a no-op once the worker has finished, as above), and [?check-cancel] is the polling point inside a hot loop (see async).

Select — multi-way receive. Evaluates all [case …] clauses concurrently; proceeds with the first ready. Uniform-random selection on simultaneous readiness:

          [?let [= $jobs   [?channel name='jobs' buffer=1]]
      [= $signal [?channel name='sig'  buffer=1]]
      [= $sent   [?send 42 to=$jobs]]
  [?select
    [case [from $jobs $job]   [handled $job]]
    [case [from $signal $sig] [signalled $sig]]
    [case [timeout 5s]        [heartbeat]]]]
        

          $ cx prog.cx
[handled 42]
        

Shape. [?select] clauses are clause-children: [case [from CH $msg] HANDLER] for a receive and [case [timeout DURATION] HANDLER] for a deadline. The spec/03-approved/core/code.md §10.4.7 registry holds the authoritative shape. The v0.7.x :case [:from CH $msg H] [; version-literal-ok ] colon-slot form is retired — there is no dual-accept.

Async, await, and cancellation

[?async EXPR] evaluates EXPR in a new async context and returns a future immediately:

          [?let [= $f1 [?async [+ 1 1]]]
      [= $f2 [?async [* 2 2]]]
      [= $f3 [?async [$upper 'go']]]
  [?await-all ($f1, $f2, $f3)]]
        

          $ cx prog.cx
(2, 4, GO)
        

Future state machine. Futures progress through pending → running → done / failed / cancelled. Once terminal, the state is immutable.

Barrier variants:

• [?await $f] — block until terminal; return value on done, propagate err on failed, CANCELLED on cancelled.
• [?await $f timeout=DURATION] — add a hard deadline; on expiry return CXER0241 (AWAIT_TIMEOUT). The future continues running — timeout= bounds the caller's wait, not the future itself.
• [?await-all FUTURES] — block until all terminal. If all done, yield sequence of values. If any failed/cancelled, yield CXER0240 with a [causes …] child carrying every non-done cause in input order.
• [?await-any FUTURES] — yield first to terminate. Other futures continue running; their results are discarded.
• [?await-race FUTURES] — yield first to terminate; other futures are cancelled. Use for "I only need one".

Cooperative cancellation contract. [?cancel $f] requests cancellation — it is a signal, not a kill. The runtime guarantees cancellation observation at:

• HTTP client calls at next network read/write boundary.
• [?sleep DURATION] — immediately.
• [?send] / [?receive] / [?try-send] / [?try-receive] — immediately, returning CXER0260 (CANCELLED).
• [?for] — at every iteration boundary.
• [?await] — immediately.

Pure CPU loops without yield points do NOT observe cancellation. Authors who want a cancellable hot loop must insert [?check-cancel] at appropriate boundaries — it evaluates to [ok] normally, or CXER0260 (CANCELLED) if cancellation is pending.

          [?def cancellable-compute impure ($n)
  [?for [in $i [$range 1 $n]]
    [where [= [?check-cancel] [ok]]]
    [yield [* $i $i]]]]
[$cancellable-compute 4]
        

          $ cx prog.cx
1
4
9
16
        

Composition with resilience. [?async] composes with every resilience directive. [?async [?timeout 5s [$slow-call]]] returns a future that resolves to CXER0141 (TIMEOUT) after 5s if slow-call hasn't completed.

Status. Async/await is a stable surface of the reference evaluator; binding parity ships per spec/03-approved/misc/parity-matrix.md.

[?retry] — bounded re-run with backoff

Re-run an inner body on [err …] return, up to max= attempts, sleeping between attempts per backoff= / delay= / jitter=. Terminal failure raises CXER0140 (RETRY_EXHAUSTED).

Backoff formulas (delay for attempt N, N ≥ 1): constant = delay=; linear = delay × N; exponential = delay × 2^(N-1); fibonacci = delay × fib(N).

Jitter modes (D = pre-jitter delay): none = D; full = uniform(0, D); equal = D/2 + uniform(0, D/2); decorrelated = uniform(delay, last_delay × 3).

The full policy reads [?retry max=5 backoff=exponential delay=200ms jitter=equal [on [?fn ($e) [= $e@code 'CXER0163']]] BODY] — retry only on a timeout. The fixture below retries a body that fails twice and succeeds on the third attempt:

          [?retry max=5 [?test-err-then-ok err-count=2 ok-value=done]]
        

          $ cx prog.cx
done
        

[?timeout] — hard deadline

Bound execution time of an inner body. On expiry, cooperatively cancel the body and return the [on-timeout …] clause body (if present) or [result status=err code='cx-err:CXER0141' elapsed=DURATION].

          [?timeout 100ms
   [?let [= $_ [?sleep 500ms mock]] never]
   [on-timeout fallback]]
        

          $ cx prog.cx
fallback
        

[?circuit-breaker] — fail-fast on consecutive failures

Three states: closed (passes through), open (rejects with CXER0150 (BREAKER_OPEN) without calling :body), half-open (allows one probe). Transitions:

• Closed → open when failure ratio in rolling window= exceeds threshold=, with at least min-samples= recorded.
• Open → half-open after reset= elapses.
• Half-open → closed if probe succeeds.
• Half-open → open if probe fails.

          [?for [in $i (1, 2, 3, 4, 5)]
      [yield [?circuit-breaker threshold=0.5 window=60s reset=30s
                               min-samples=2 name="cb-002" [?test-always-err]]]]
        

          $ cx prog.cx
[err code=test-failure message='test failure' at='3:60']
[err code=test-failure message='test failure' at='3:60']
[err code=cx-err:CXER0150 message='circuit breaker open' at='2:14' [until [instant 30s]]]
[err code=cx-err:CXER0150 message='circuit breaker open' at='2:14' [until [instant 30s]]]
[err code=cx-err:CXER0150 message='circuit breaker open' at='2:14' [until [instant 30s]]]
        

[?fallback] — alternative on error

If primary returns [err …], evaluate secondary and return its value (which may itself be [err] — [?fallback] does not wrap that case).

          [?fallback [body [err code='down' message='service down']] [recover-with secondary]]
        

          $ cx prog.cx
secondary
        

$err in the recovery scope. Inside the recovery scope, $err is bound to the primary's [err …] value, so recovery can introspect the failure (e.g. [recover-with [response status=500 reason=$err/@message]]). The clause-child [recover-with …] form is the sole accepted shape (no legacy colon-slot).

[?rate-limit] — token-bucket cap

Permits at most max= invocations per per= window. Excess invocations return CXER0151 (RATE_LIMITED) with a retry-after=DURATION attribute — the time until the next token frees.

          [?for [in $i (1, 2, 3, 4)]
      [yield [?rate-limit max=2 per=1s name="rl-002" $i]]]
        

          $ cx prog.cx
1
2
[err code=cx-err:CXER0151 message='rate limit exceeded' at='2:14' retry-after::duration=1s]
[err code=cx-err:CXER0151 message='rate limit exceeded' at='2:14' retry-after::duration=1s]
        

[?bulkhead] — bound concurrent calls

Bounds concurrent invocations. If max-concurrent= slots are busy and queue= slots are full, returns CXER0152 (BULKHEAD_FULL). Queued requests wait FIFO for a free slot.

          [?test-concurrent tasks=(
   [?bulkhead max-concurrent=1 queue=0 name="bh-002" [?let [= $_ [?sleep 500ms mock]] first]],
   [?bulkhead max-concurrent=1 queue=0 name="bh-002" second])]
        

          $ cx prog.cx
([err code=cx-err:CXER0152 message='bulkhead saturated' at='3:4' max=1], first)
        

Composition

Resilience directives compose by nesting. The outermost runs first, so its policy sees the inner policies' err codes. Standard pattern reads top-down:

          [?retry max=3 backoff=constant delay=10ms jitter=none [?timeout 100ms
            [?let [= $_ [?sleep 500ms mock]] never]]]
        

          $ cx prog.cx
[err code=cx-err:CXER0140 message='retry budget exhausted after 3 attempts' at='1:1' attempts=3 [cause [err code=cx-err:CXER0141 message='operation timed out after 100ms' at='1:55' elapsed::duration=100ms]]]
        

Reading: retry up to 3 times a deadline-bounded body; the timeout's CXER0141 is what [?retry] sees on each attempt, and the exhausted retry names it as the cause. A breaker in the same position surfaces CXER0150, and [?retry] decides whether to keep retrying (the default [on …] predicate returns truthy → yes; override to scope which errs retry).

State identity (stateful directives). [?circuit-breaker], [?rate-limit], and [?bulkhead] carry state across invocations. By default state is keyed by lexical source-text position — every evaluation of the same source node (including iterated under [?for] or [?map … [par]]) shares state. Pass name=STR to key by name instead, enabling cross-position sharing (one rate-limit budget enforced by callers in different modules).

Directives turn data into a language

A directive is a CX element whose name starts with ?. It carries semantics — iteration, branching, substitution, include, function call — that the evaluator interprets when running a CX program. Directives parse as regular CX, evaluate to text or values, and compose with each other through their slot bodies.

        EXPR                                     [; bare expression evaluates ]
           [?for [in $x PATH] [yield BODY]]         [; iterate ]
           [?if COND [then THEN] [else ELSE]]       [; branch ]
           [?let [= $x EXPR] BODY]                  [; bind a name ]
           [?def name ($a $b) BODY]                 [; define a function ]
      

Pattern matching — walking the tree

The current program surface replaces XPath-style queries with [?for] pattern generators and CXPath path values ([?find] retired). A pattern is a CX literal where element names match by shape, attribute predicates restrict by value, and $bindings capture matched subtrees. [?for] walks the tree (deep by default) and binds for each match; [?match] tests a single value (multi-arm dispatch).

          [shop
  [user [name 'Ada']]
  [item active=true 'i1']
  [pizza [name 'Margherita'] [price 12]]]
        

          ([?for [user [name $n]] [yield $n]],
 [?for [item @active=true $i] [yield $i]],
 [?for [pizza [name $n] [price $p]]
       [yield [hit name=$n price=$p]]])
        

          $ cx --data=input.cx prog.cx
(Ada, [item active=true i1], [hit name=Margherita price=12])
        

Comprehensions and composition

[?for] iterates a sequence (or matches a pattern across the tree) and yields per-iteration values; [where …] filters, [order-by …] sorts, [group-by …] aggregates. [?let] binds names; [?if] branches. The [?pipe] directive composes them.

          (([?for [in $x (1, 2, 3)] [where [> $x 1]] [yield [* $x $x]]]),
 [?let [= $a 10] [= $b 32] [+ $a $b]],
 [?pipe (1, 2, 3, 4) [$count]])
        

          $ cx prog.cx
((4, 9), 42, 4)
        

            [?def $odds [$range 1 99 2]]
[?def $first-ten $odds[:10]]
[?def $squares [?for [in $x $first-ten] [yield [* $x $x]]]]
$squares
          

            $ cx prog.cx
error: cx-err:CXER0100: [?def] parse: CXDEF_PARSE: missing function name at line 1:1
          

Quick reference

In order: every user; every active user; the active users' emails; the third user in document order; everything two levels under the root; the siblings after the first user; the ancestors of a [para]; a general predicate — prefix code over $_; a range; and the three set heads union, intersect, except:

          [org
  [team
    [user active=true  age=30 email='a@example.org']
    [user active=false age=40 email='b@example.org']
    [user active=true  age=17 email='c@example.org']
    [para 'p']]
  [a 1] [b 2]]
        

          ([$count //user],
 [$count //user[= $_@active true]],
 //user[= $_@active true]/@email,
 //user[3]/@email,
 [$count /*/*],
 [$count //user[1]/following-sibling::user],
 ([?for [in $e //para/ancestor::*] [yield [$name $e]]]),
 //user[and [>= $_@age 18] $_@active]/@email,
 [$range 1 10],
 [union //a //b],
 [intersect //user //team/user[= $_@active true]],
 [except //user //user[= $_@active false]])
        

          $ cx --data=input.cx prog.cx
(3, 2, ([email a@example.org], [email c@example.org]), [email c@example.org], 3, 2, (org, team), [email a@example.org], (1, 2, 3, 4, 5, 6, 7, 8, 9, 10), ([a 1], [b 2]), ([user active=true age=30 email='a@example.org'], [user active=true age=17 email='c@example.org']), ([user active=true age=30 email='a@example.org'], [user active=true age=17 email='c@example.org']))
        

Four leading forms

Every CXPath has one of four leading-token forms. - // descendant — //user — descendant-or-self::node()/child::user; the most common shape. - / absolute — /root/item — child of the document root; rare in well-shaped data. - relative — user/email — applied against the current evaluation context. - $name/ binding — $u/email — rooted at a previously-bound value (per [?for] / [?let] / (bind $name)).

Twelve axes

Every step can specify an axis. The default axis is child::; the attribute:: axis has the dedicated @ sigil. CX implements all twelve XPath 3.1 axes: child, descendant, descendant-or-self, parent, ancestor, ancestor-or-self, self, following-sibling, preceding-sibling, following, preceding, attribute.

Composite shortcut forms: /name ≡ child::name; //name ≡ descendant-or-self::node()/child::name; @name ≡ attribute::name; .. ≡ parent::node(); . ≡ self::node(). Attribute axis is name-disjoint from element axes — //user/@name selects the attribute only; //user/name selects the child element only.

General predicate + reserved bindings

Predicates filter the step sequence. A predicate body is prefix CX code coerced to a boolean via the Effective Boolean Value (EBV) rule. The atomic shorthands — [@name] / [@!name] (attribute present / absent), [N] (position), a bare child name (step-existence) — remain available and round-trip via canonical re-emit. Value comparisons are always prefix: [= $_@name V].

Three reserved bindings in scope inside every predicate body: $_ (current candidate item, type matches the candidate kind), $_position (1-based int index — equivalent to XPath position()), $_last (int cardinality of the candidate sequence — equivalent to XPath last()). Predicates are eagerly materialised, so $_last is known on every predicate evaluation.

Comparison sigils are value-comparison only: =, !=, <, <=, >, >=. No keyword synonyms (no eq/ne/lt/etc.). Comparing a sequence with more than one item raises CXER0103. Purity — every predicate body MUST be pure; impure callees fail load with CXER0230.

Cross-step reference — nested generators

To reference an outer step's focus from an inner predicate ("leads of teams with at least three members"), stack [?for] generators — each generator names its focus, and every later clause sees the earlier bindings:

          [org
  [team [member role='lead' [name 'a']] [member [name 'b']] [member [name 'c']]]
  [team [member role='lead' [name 'e']]]]
        

          [?for [in $t //team]
      [in $m $t/member]
      [where [and [= $m@role 'lead'] [>= [$count $t/member] 3]]]
  [yield $m/name]]
        

          $ cx --data=input.cx prog.cx
a
        

The grammar reserves a (bind $name) path-step annotation (grammar.ebnf [160a]) for naming a step's focus inline; the nested-generator form above is the conformance-exercised idiom.

In the host bindings

Every binding exposes CXPath identically through its Layer-1 Doc.select_all — the same selector string, the same bytes returned across the C ABI; the bindings page shows each spelling. The selector, run here by cx itself:

          [users
  [user active=true  email='ada@example.org']
  [user active=false email='bob@example.org']
  [user active=true  email='cy@example.org']]
        

          //user[= $_@active true]/@email
        

          $ cx --data=input.cx prog.cx
[email ada@example.org]
[email cy@example.org]
        

Capability and runtime caps

- CXER0271 — capability denied at an effect point. Capabilities are deny-by-default; the param-less eval entry points run with the empty capability set — "pure-only" is the empty set, not a pragma. - CXER0272 — E_STACK_EXHAUSTED: the evaluator's native-stack exhaustion guard.

Purity and eval gates

- CXER0230 — purity gate: an impure callee where purity is required (e.g. inside a CXPath predicate) is rejected at parse / module-load. - CXER0233 — a pure def reaching [?eval] / cx:eval-tree (tree-eval is impure, like cx:eval). - CXER4113 — lib-widen gate: [?lib] inside an eval tree may not widen the capability set. - CXER4114 — eval depth gate: cx:eval / [?eval] recursion exceeded the shared depth budget.

E9xx — include resolver

- E901 — absolute path rejected. - E902 — path escapes include root (lexical or symlink). - E903 — URL-scheme path rejected. - E904 — cycle detected. - E905 — max depth exceeded. - E906 — file not found. - E907 — file not readable. - E908 — path is a directory. - E909 — I/O error during read. - E910 — non-UTF-8 content. - E911 — included file parse failure.

Recovering with [?match]

An ungranted read answers CXER0271 — the capability refusal, an err value like any other:

          [?lib 'cx-stdlib/io']
[$io:read-file "/var/log/app.log"]
        

          $ cx prog.cx
[err code=cx-err:CXER0271 message='E_CAP_DENIED: read capability required for io-read-file; none granted (grant via --allow-read)' at='2:1']
        

Under --allow-read, a read of a missing file answers CXER3401; either way a [case [err @code=$c] …] arm dispatches on the code by name, and the catch-all arms take whatever is left:

          [?lib 'cx-stdlib/io']
[?match [$io:read-file '/no/such/file.cx']
  [case [err @code=$c] [where [= $c 'cx-err:CXER0271']] [needs-capability]]
  [case [err$e] [other-error code=$e@code]]
  [else :ok]]
        

          $ cx --allow-read prog.cx
[other-error code=cx-err:CXER3401]