Skip to main content

arb/
jqlang.rs

1//! `jqlang` — a complete jq language engine.
2//!
3//! # Why this exists next to `crate::jq`
4//!
5//! [`crate::jq`] is a TRANSLATOR: it rewrites a jq literal into arb's linear
6//! `Vec<QueryOp>` line-stream pipeline. That shape is exactly right for the
7//! constructs arb's own verbs already cover (a path, an iterate, a `select`, a
8//! `map`) and it keeps arb's line-stream promises — notably that identity and
9//! `select` emit the SOURCE line verbatim, so `{ "a" : 1 }` keeps its spacing
10//! and `1.50` keeps its literal.
11//!
12//! It is structurally incapable of the REST of jq. A `Vec<QueryOp>` is a
13//! sequence of one-line-in/one-line-out (or reducing) stages; jq is a language
14//! of GENERATORS, where every filter maps one input to a STREAM of outputs, and
15//! where `reduce`/`foreach`/`label`/`try` are control flow over that stream.
16//! `.a, .b` alone cannot be expressed as a stage list. So `crate::jq` refused
17//! everything it could not translate, and SPEC §8 listed those refusals.
18//!
19//! This module is the other half: a real jq lexer, parser and evaluator with
20//! jq's own value model, so the constructs that used to be refused are now
21//! ANSWERED, byte-for-byte as `jq` answers them. `crate::jq` still handles what
22//! it handled (unchanged, so the line-stream passthrough guarantees are intact)
23//! and hands anything else here instead of erroring.
24//!
25//! # The value model
26//!
27//! Not `serde_json::Value`, for two measured reasons:
28//!
29//! * **Key order is observable in jq.** `{"b":1,"a":2} | to_entries` is
30//!   `[{"key":"b",…},{"key":"a",…}]` and `keys_unsorted` is `["b","a"]`.
31//!   `serde_json::Map` is a `BTreeMap`, which re-sorts both.
32//! * **Number literals survive unmodified values.** `jq -c .` on
33//!   `{"a":1.50,"b":1E+2}` prints `{"a":1.50,"b":1E+2}`, and `12345678901234567890`
34//!   round-trips exactly. An `f64` loses all three. jq only reformats a number it
35//!   COMPUTED (`.a+0` is `1.5`), so the literal is carried alongside the double
36//!   and dropped the moment arithmetic touches it.
37//!
38//! Containers are `Rc`-shared so a clone is a refcount bump, which is what makes
39//! `reduce`/`foreach`/path updates affordable — the same choice jq's own
40//! refcounted `jv` makes.
41
42use std::borrow::Cow;
43use std::cell::RefCell;
44use std::cmp::Ordering;
45use std::fmt::Write as _;
46use std::rc::Rc;
47
48// ─────────────────────────────────────────────────────────────────────────────
49// Value model
50// ─────────────────────────────────────────────────────────────────────────────
51
52/// Where a number came from, which is what jq 1.8's decNumber build keys its
53/// number semantics on. A number PARSED from text (the document, the program,
54/// `tonumber`, `fromjson`) is a decimal literal: it prints as written, negates
55/// exactly, and two of them compare as decimals (`3.000000000000000000000001 ==
56/// 3` is false). A number COMPUTED by arithmetic or a builtin is a plain double
57/// and compares as one, so `(3 | . + 0) == 3.000000000000000000000001` is true.
58///
59/// Nearly every parsed number prints as its own double's shortest form, so the
60/// text is stored only when it differs; `Canonical` records that the number is
61/// a literal without paying for a string per number on the JSON reader's
62/// innermost path.
63#[derive(Debug, Clone)]
64pub enum NumLit {
65    /// Built by arithmetic or a builtin: a double and nothing more.
66    Computed,
67    /// Parsed from text that IS the double's shortest round-trip form, so
68    /// [`fmt_num`] reproduces it exactly and nothing need be kept.
69    Canonical,
70    /// Parsed from text that prints differently from the double (`1.50`,
71    /// `1E+17`, a 20-digit integer), kept in decNumber's canonical spelling.
72    Text(Rc<str>),
73}
74
75impl NumLit {
76    /// The stored spelling, when one had to be kept.
77    pub fn text(&self) -> Option<&str> {
78        match self {
79            NumLit::Text(t) => Some(t),
80            _ => None,
81        }
82    }
83
84    /// The exact decimal this literal denotes, for a decNumber-style
85    /// comparison; `None` for a computed number, which jq compares as a double.
86    fn decimal(&self, n: f64) -> Option<Cow<'_, str>> {
87        match self {
88            NumLit::Computed => None,
89            NumLit::Canonical => Some(Cow::Owned(fmt_num(n))),
90            NumLit::Text(t) => Some(Cow::Borrowed(t)),
91        }
92    }
93}
94
95/// A jq value. `Num` carries its provenance ([`NumLit`]) so a literal keeps
96/// jq's decimal semantics until arithmetic touches it: `1.50` prints back as
97/// `1.50` and compares as the decimal it spells.
98#[derive(Debug, Clone)]
99pub enum JqVal {
100    Null,
101    Bool(bool),
102    Num(f64, NumLit),
103    Str(Rc<str>),
104    Arr(Rc<Vec<JqVal>>),
105    /// Insertion-ordered key/value pairs. jq objects are small in practice, so a
106    /// vector with a linear scan beats a hash map on both lookup and clone while
107    /// preserving the order jq exposes through `keys_unsorted`/`to_entries`.
108    Obj(Rc<Vec<(Rc<str>, JqVal)>>),
109    /// A YAML NODE: one of the six values above plus the metadata YAML records
110    /// about it — comments, anchor, alias, tag, style, position. See
111    /// [`crate::ynode`] for why the metadata rides alongside the value instead
112    /// of replacing it.
113    ///
114    /// **Only [`crate::yaml`] constructs this.** `parse_json` cannot, so a JSON
115    /// program never sees the variant and every jq answer is reached through
116    /// exactly the arms it was reached through before. Every operation that
117    /// cares about the VALUE calls [`JqVal::bare`] first; the yq metadata
118    /// builtins are the only ones that look at the box.
119    Node(Rc<crate::ynode::YNode>),
120}
121
122impl JqVal {
123    pub fn num(v: f64) -> Self {
124        JqVal::Num(v, NumLit::Computed)
125    }
126    pub fn str(s: impl Into<Rc<str>>) -> Self {
127        JqVal::Str(s.into())
128    }
129    pub fn arr(v: Vec<JqVal>) -> Self {
130        JqVal::Arr(Rc::new(v))
131    }
132    pub fn obj(v: Vec<(Rc<str>, JqVal)>) -> Self {
133        JqVal::Obj(Rc::new(v))
134    }
135
136    /// The value with any YAML node box removed.
137    ///
138    /// Every operation whose answer is about the VALUE goes through this, so a
139    /// commented YAML scalar compares, sorts, renders and arithmetics exactly as
140    /// the same scalar read from JSON would. The box is one level deep by
141    /// construction ([`JqVal::wrap`] collapses a re-wrap), so this never
142    /// recurses more than once.
143    pub fn bare(&self) -> &JqVal {
144        match self {
145            JqVal::Node(n) => &n.val,
146            other => other,
147        }
148    }
149
150    /// The YAML metadata on this node, or `None` for a plain value.
151    pub fn meta(&self) -> Option<&crate::ynode::NodeMeta> {
152        match self {
153            JqVal::Node(n) => Some(&n.meta),
154            _ => None,
155        }
156    }
157
158    /// Box `v` with `meta`, or hand `v` back untouched when the metadata is
159    /// [`crate::ynode::NodeMeta::is_bare`] — a document with no comments,
160    /// anchors, tags or quoting pays no allocation and produces values that are
161    /// bit-identical to the JSON reader's.
162    pub fn wrap(v: JqVal, meta: crate::ynode::NodeMeta) -> JqVal {
163        if meta.is_bare() {
164            return v;
165        }
166        // Never nest: re-wrapping replaces the metadata rather than layering it,
167        // which is what `.x | (. tag = "!!str") | anchor = "a"` needs.
168        let val = match v {
169            JqVal::Node(n) => n.val.clone(),
170            other => other,
171        };
172        JqVal::Node(Rc::new(crate::ynode::YNode { meta, val }))
173    }
174
175    /// Replace this node's metadata, keeping the value. Used by every `… = …`
176    /// metadata assignment (`anchor`, `tag`, `style`, the three comments).
177    pub fn with_meta(&self, f: impl FnOnce(&mut crate::ynode::NodeMeta)) -> JqVal {
178        let mut meta = self.meta().cloned().unwrap_or_default();
179        f(&mut meta);
180        JqVal::wrap(self.bare().clone(), meta)
181    }
182
183    /// jq's `type`.
184    pub fn type_name(&self) -> &'static str {
185        match self.bare() {
186            JqVal::Null => "null",
187            JqVal::Bool(_) => "boolean",
188            JqVal::Num(..) => "number",
189            JqVal::Str(_) => "string",
190            JqVal::Arr(_) => "array",
191            JqVal::Obj(_) => "object",
192            JqVal::Node(_) => unreachable!("bare() never returns a Node"),
193        }
194    }
195
196    /// jq truthiness: only `false` and `null` are falsy. `0`, `""`, `[]` and
197    /// `{}` are all TRUE, which is the rule `select` rides on.
198    pub fn truthy(&self) -> bool {
199        !matches!(self.bare(), JqVal::Null | JqVal::Bool(false))
200    }
201
202    fn as_f64(&self) -> Option<f64> {
203        match self.bare() {
204            JqVal::Num(n, _) => Some(*n),
205            _ => None,
206        }
207    }
208
209    /// The rank of this value's type in jq's total order:
210    /// `null < false < true < numbers < strings < arrays < objects`.
211    fn order_rank(&self) -> u8 {
212        match self.bare() {
213            JqVal::Null => 0,
214            JqVal::Bool(false) => 1,
215            JqVal::Bool(true) => 2,
216            JqVal::Num(..) => 3,
217            JqVal::Str(_) => 4,
218            JqVal::Arr(_) => 5,
219            JqVal::Obj(_) => 6,
220            JqVal::Node(_) => unreachable!("bare() never returns a Node"),
221        }
222    }
223
224    /// Look a key up in an object, unboxing the container first. The public
225    /// twin of `obj_get`, for the yq encoders that walk a value they did not
226    /// build.
227    pub fn obj_lookup(&self, k: &str) -> Option<&JqVal> {
228        self.obj_get(k)
229    }
230
231    fn obj_get(&self, k: &str) -> Option<&JqVal> {
232        match self.bare() {
233            JqVal::Obj(m) => m.iter().find(|(key, _)| &**key == k).map(|(_, v)| v),
234            _ => None,
235        }
236    }
237}
238
239/// jq's order over values (`<`, `==`, `min`, `max`, `unique`, `group_by`).
240///
241/// Ported from jq 1.8.2 `src/jv.c:jv_cmp`. Objects compare by their SORTED key
242/// list first and only then by the values at those keys, which is why
243/// `{"a":1} < {"b":0}` even though `1 > 0`. A NaN compares as `null` against a
244/// number -- below every number, itself included -- so `nan < 1`, `nan < nan`
245/// and `nan != nan` are all true, which makes this NOT a total order; sorting
246/// uses [`cmp_sort`].
247pub fn cmp_vals(a: &JqVal, b: &JqVal) -> Ordering {
248    cmp_with(a, b, false)
249}
250
251/// The order `sort` and `sort_by` use: [`cmp_vals`] with two NaNs equal, so a
252/// sort is handed a total order. Where jq's `nan < nan` would have the sort
253/// place one NaN before another, the two are indistinguishable anyway.
254pub fn cmp_sort(a: &JqVal, b: &JqVal) -> Ordering {
255    cmp_with(a, b, true)
256}
257
258/// Compare two finite decimal literals exactly (`None` for anything else, such
259/// as a non-finite one). The value is `±0.DIGITS × 10^pos`: the sign decides
260/// first (every zero is equal), then the position of the leading digit, then
261/// the digits themselves with trailing zeros removed.
262fn cmp_decimal(a: &str, b: &str) -> Option<Ordering> {
263    fn parts(s: &str) -> Option<(bool, i64, String)> {
264        let (neg, s) = match s.strip_prefix('-') {
265            Some(r) => (true, r),
266            None => (false, s.strip_prefix('+').unwrap_or(s)),
267        };
268        let (mant, exp) = match s.find(['e', 'E']) {
269            Some(i) => (&s[..i], s[i + 1..].parse::<i64>().ok()?),
270            None => (s, 0),
271        };
272        let (int, frac) = mant.split_once('.').unwrap_or((mant, ""));
273        if !(int.bytes().chain(frac.bytes())).all(|c| c.is_ascii_digit()) {
274            return None;
275        }
276        let all = format!("{int}{frac}");
277        let lead = all.len() - all.trim_start_matches('0').len();
278        let digits = all[lead..].trim_end_matches('0').to_string();
279        // Position of the leading digit relative to the decimal point.
280        let pos = exp + int.len() as i64 - lead as i64;
281        Some((neg && !digits.is_empty(), pos, digits))
282    }
283    let (na, pa, da) = parts(a)?;
284    let (nb, pb, db) = parts(b)?;
285    let mag = |p: i64, d: &String, q: i64, e: &String| match (d.is_empty(), e.is_empty()) {
286        (true, true) => Ordering::Equal,
287        (true, false) => Ordering::Less,
288        (false, true) => Ordering::Greater,
289        _ => p.cmp(&q).then_with(|| d.cmp(e)),
290    };
291    Some(match (na, nb) {
292        (false, true) => Ordering::Greater,
293        (true, false) => Ordering::Less,
294        (false, false) => mag(pa, &da, pb, &db),
295        (true, true) => mag(pb, &db, pa, &da),
296    })
297}
298
299/// Two number LITERALS compare as decimals, as jq 1.8's `jvp_number_cmp` does
300/// with decNumber: `100000000000000000001` is greater than
301/// `100000000000000000000` though both are one double, and
302/// `3.000000000000000000000001` is greater than `3`. A COMPUTED number on either
303/// side (`None`) compares as the double it is. Two canonical literals order as
304/// their doubles do, so the formatter is not run for the common case.
305fn cmp_literals(x: f64, la: &NumLit, y: f64, lb: &NumLit) -> Option<Ordering> {
306    if matches!((la, lb), (NumLit::Canonical, NumLit::Canonical)) {
307        return None;
308    }
309    cmp_decimal(&la.decimal(x)?, &lb.decimal(y)?)
310}
311
312fn cmp_with(a: &JqVal, b: &JqVal, total: bool) -> Ordering {
313    let (ra, rb) = (a.order_rank(), b.order_rank());
314    if ra != rb {
315        return ra.cmp(&rb);
316    }
317    // Order is a property of the VALUE. A YAML node's comment or anchor must not
318    // reorder a sort, so both sides are unboxed before the comparison.
319    let (a, b) = (a.bare(), b.bare());
320    match (a, b) {
321        (JqVal::Num(x, la), JqVal::Num(y, lb)) => match (x.is_nan(), y.is_nan()) {
322            (true, true) if total => Ordering::Equal,
323            (true, _) => Ordering::Less,
324            (false, true) => Ordering::Greater,
325            _ => cmp_literals(*x, la, *y, lb)
326                .unwrap_or_else(|| x.partial_cmp(y).unwrap_or(Ordering::Equal)),
327        },
328        (JqVal::Str(x), JqVal::Str(y)) => x.cmp(y),
329        (JqVal::Arr(x), JqVal::Arr(y)) => {
330            for (ea, eb) in x.iter().zip(y.iter()) {
331                let c = cmp_with(ea, eb, total);
332                if c != Ordering::Equal {
333                    return c;
334                }
335            }
336            x.len().cmp(&y.len())
337        }
338        (JqVal::Obj(x), JqVal::Obj(y)) => {
339            let mut ka: Vec<&Rc<str>> = x.iter().map(|(k, _)| k).collect();
340            let mut kb: Vec<&Rc<str>> = y.iter().map(|(k, _)| k).collect();
341            ka.sort();
342            kb.sort();
343            let c = ka.cmp(&kb);
344            if c != Ordering::Equal {
345                return c;
346            }
347            for k in ka {
348                let c = cmp_with(
349                    a.obj_get(k).unwrap_or(&JqVal::Null),
350                    b.obj_get(k).unwrap_or(&JqVal::Null),
351                    total,
352                );
353                if c != Ordering::Equal {
354                    return c;
355                }
356            }
357            Ordering::Equal
358        }
359        _ => Ordering::Equal,
360    }
361}
362
363/// jq's `==`: the total order's equality, so type counts (`1` is not `"1"`).
364pub fn eq_vals(a: &JqVal, b: &JqVal) -> bool {
365    cmp_vals(a, b) == Ordering::Equal
366}
367
368// ─────────────────────────────────────────────────────────────────────────────
369// Errors
370// ─────────────────────────────────────────────────────────────────────────────
371
372/// A jq runtime signal. `Break` is how `label $l | … | break $l` unwinds, and
373/// how `first`/`limit`/`any`/`all` stop early. In jq a `break` IS an error —
374/// `break $l` compiles to `$l | error`, the label's value being the object
375/// GENLABEL pushed — so a `try`/`?` between the `break` and its label catches
376/// it with that object as the payload (see `caught_payload`).
377#[derive(Debug)]
378pub enum JqErr {
379    /// `error(v)`. The payload is a jq VALUE, because `try f catch .` receives it.
380    Err(JqVal),
381    /// Unwind to the matching `label`.
382    Break(u64),
383    /// `halt` / `halt_error`: stop the whole program with this exit status.
384    Halt(i32, Option<JqVal>),
385}
386
387impl JqErr {
388    fn msg(s: impl Into<String>) -> Self {
389        JqErr::Err(JqVal::str(s.into()))
390    }
391    /// The one-line text jq prints for this error on stderr.
392    pub fn to_message(&self) -> String {
393        match self {
394            JqErr::Err(JqVal::Str(s)) => s.to_string(),
395            JqErr::Err(v) => format!("{} ({}) not a string", v.type_name(), render(v)),
396            JqErr::Break(_) => "break".to_string(),
397            JqErr::Halt(..) => "halt".to_string(),
398        }
399    }
400}
401
402type R<T> = Result<T, JqErr>;
403/// Where a filter's output stream goes. Returning `Err` aborts the stream, which
404/// is what makes `limit`/`first`/`any` stop pulling instead of materializing.
405type Sink<'a> = &'a mut dyn FnMut(JqVal) -> R<()>;
406
407// ─────────────────────────────────────────────────────────────────────────────
408// JSON: parse (literal-preserving) and render (jq-compatible)
409// ─────────────────────────────────────────────────────────────────────────────
410
411/// Parse one JSON document, preserving each number's source literal.
412///
413/// Hand-written rather than delegated to `serde_json` for the reason the module
414/// header gives: the two things this keeps — key ORDER and the number LITERAL —
415/// are precisely the two `serde_json::Value` discards.
416///
417/// This strict reader is the fast path. What it refuses is offered to jq's own
418/// reader ([`crate::jvparse`], the `jv_parse.c` port) before the line counts as
419/// text, because jq reads its input with that parser: a leading byte-order
420/// mark, `nan`/`NaN`/`Infinity`, `01`, `.5` and `+1` are all JSON values to it.
421/// The strict reader's message is kept for the refusal.
422pub fn parse_json(src: &str) -> Result<JqVal, String> {
423    parse_json_with(src).or_else(|e| crate::jvparse::parse(src).map_err(|_| e))
424}
425
426fn parse_json_with(src: &str) -> Result<JqVal, String> {
427    let b = src.as_bytes();
428    let mut p = JsonParser { b, i: 0 };
429    p.ws();
430    let v = p.value()?;
431    p.ws();
432    if p.i != b.len() {
433        return Err(format!("trailing garbage at byte {}", p.i));
434    }
435    Ok(v)
436}
437
438/// Parse a stream of whitespace-separated JSON documents (jq's own input model).
439pub fn parse_json_stream(src: &str) -> Result<Vec<JqVal>, String> {
440    let b = src.as_bytes();
441    let mut p = JsonParser { b, i: 0 };
442    let mut out = Vec::new();
443    loop {
444        p.ws();
445        if p.i >= b.len() {
446            return Ok(out);
447        }
448        out.push(p.value()?);
449    }
450}
451
452/// jq's refusals for the two string bodies this reader used to repair instead:
453/// a raw control byte, and a high surrogate with no low one after it.
454const UNESCAPED_CONTROL: &str =
455    "Invalid string: control characters from U+0000 through U+001F must be escaped";
456const BAD_SURROGATE_PAIR: &str = "Invalid \\uXXXX\\uXXXX surrogate pair escape";
457
458struct JsonParser<'a> {
459    b: &'a [u8],
460    i: usize,
461}
462
463impl JsonParser<'_> {
464    fn ws(&mut self) {
465        while self.i < self.b.len() && matches!(self.b[self.i], b' ' | b'\t' | b'\n' | b'\r') {
466            self.i += 1;
467        }
468    }
469    fn value(&mut self) -> Result<JqVal, String> {
470        match self.b.get(self.i) {
471            None => Err("unexpected end of input".into()),
472            Some(b'n') => self.lit("null", JqVal::Null),
473            Some(b't') => self.lit("true", JqVal::Bool(true)),
474            Some(b'f') => self.lit("false", JqVal::Bool(false)),
475            Some(b'"') => Ok(JqVal::Str(self.string_rc()?)),
476            Some(b'[') => self.array(),
477            Some(b'{') => self.object(),
478            Some(_) => self.number(),
479        }
480    }
481    fn lit(&mut self, w: &str, v: JqVal) -> Result<JqVal, String> {
482        if self.b[self.i..].starts_with(w.as_bytes()) {
483            self.i += w.len();
484            Ok(v)
485        } else {
486            Err(format!("expected `{w}` at byte {}", self.i))
487        }
488    }
489    fn number(&mut self) -> Result<JqVal, String> {
490        let start = self.i;
491        if matches!(self.b.get(self.i), Some(b'-') | Some(b'+')) {
492            self.i += 1;
493        }
494        while matches!(self.b.get(self.i), Some(c) if c.is_ascii_digit()) {
495            self.i += 1;
496        }
497        if self.b.get(self.i) == Some(&b'.') {
498            self.i += 1;
499            while matches!(self.b.get(self.i), Some(c) if c.is_ascii_digit()) {
500                self.i += 1;
501            }
502        }
503        if matches!(self.b.get(self.i), Some(b'e') | Some(b'E')) {
504            self.i += 1;
505            if matches!(self.b.get(self.i), Some(b'-') | Some(b'+')) {
506                self.i += 1;
507            }
508            while matches!(self.b.get(self.i), Some(c) if c.is_ascii_digit()) {
509                self.i += 1;
510            }
511        }
512        if self.i == start {
513            return Err(format!("unexpected byte at {start}"));
514        }
515        let text = std::str::from_utf8(&self.b[start..self.i]).map_err(|e| e.to_string())?;
516        let n: f64 = text
517            .parse()
518            .map_err(|_| format!("bad number `{text}` at byte {start}"))?;
519        // Only carry the literal when re-rendering the double would CHANGE it.
520        // Storing it unconditionally would make every `1` an allocation for no
521        // observable gain, and the equality check is the exact condition under
522        // which the literal is load-bearing.
523        Ok(num_from_literal(n, text))
524    }
525    /// A string, built straight from the source slice when it holds no escape —
526    /// which is the overwhelmingly common case, and saves a `String` build plus a
527    /// copy into the `Rc` for every key and every string value in the stream.
528    fn string_rc(&mut self) -> Result<Rc<str>, String> {
529        debug_assert_eq!(self.b[self.i], b'"');
530        let start = self.i + 1;
531        let mut j = start;
532        while let Some(c) = self.b.get(j) {
533            match c {
534                b'"' => {
535                    let raw = std::str::from_utf8(&self.b[start..j]).map_err(|e| e.to_string())?;
536                    self.i = j + 1;
537                    return Ok(Rc::from(raw));
538                }
539                b'\\' => break,
540                0..=0x1f => return Err(UNESCAPED_CONTROL.into()),
541                _ => j += 1,
542            }
543        }
544        if self.b.get(j).is_none() {
545            return Err("unterminated string".into());
546        }
547        Ok(Rc::from(self.string()?.as_str()))
548    }
549
550    fn string(&mut self) -> Result<String, String> {
551        debug_assert_eq!(self.b[self.i], b'"');
552        self.i += 1;
553        let mut s = String::new();
554        loop {
555            match self.b.get(self.i) {
556                None => return Err("unterminated string".into()),
557                Some(b'"') => {
558                    self.i += 1;
559                    return Ok(s);
560                }
561                Some(b'\\') => {
562                    self.i += 1;
563                    let c = *self.b.get(self.i).ok_or("unterminated escape")?;
564                    self.i += 1;
565                    match c {
566                        b'"' => s.push('"'),
567                        b'\\' => s.push('\\'),
568                        b'/' => s.push('/'),
569                        b'b' => s.push('\u{8}'),
570                        b'f' => s.push('\u{c}'),
571                        b'n' => s.push('\n'),
572                        b'r' => s.push('\r'),
573                        b't' => s.push('\t'),
574                        b'u' => {
575                            let hi = self.hex4()?;
576                            // jv_parse.c's `found_string`: a high surrogate must be
577                            // followed by a `\u` low one, or the whole text is
578                            // refused. A lone LOW surrogate is kept, and becomes
579                            // U+FFFD the way `jv_string_sized` repairs it.
580                            let cp = if (0xD800..0xDC00).contains(&hi) {
581                                if self.b.get(self.i..self.i + 2) != Some(&b"\\u"[..]) {
582                                    return Err(BAD_SURROGATE_PAIR.into());
583                                }
584                                self.i += 2;
585                                let lo = self.hex4()?;
586                                if !(0xDC00..0xE000).contains(&lo) {
587                                    return Err(BAD_SURROGATE_PAIR.into());
588                                }
589                                0x1_0000 + ((hi - 0xD800) << 10) + (lo - 0xDC00)
590                            } else {
591                                hi
592                            };
593                            s.push(char::from_u32(cp).unwrap_or('\u{fffd}'));
594                        }
595                        other => return Err(format!("bad escape `\\{}`", other as char)),
596                    }
597                }
598                Some(_) => {
599                    let start = self.i;
600                    while let Some(&c) = self.b.get(self.i) {
601                        match c {
602                            b'"' | b'\\' => break,
603                            0..=0x1f => return Err(UNESCAPED_CONTROL.into()),
604                            _ => self.i += 1,
605                        }
606                    }
607                    s.push_str(
608                        std::str::from_utf8(&self.b[start..self.i]).map_err(|e| e.to_string())?,
609                    );
610                }
611            }
612        }
613    }
614    fn hex4(&mut self) -> Result<u32, String> {
615        let s = self
616            .b
617            .get(self.i..self.i + 4)
618            .ok_or("truncated \\u escape")?;
619        self.i += 4;
620        // Exactly four hex digits: `from_str_radix` alone would also take `+04`.
621        crate::jvparse::unhex4(s).ok_or_else(|| "Invalid characters in \\uXXXX escape".into())
622    }
623    fn array(&mut self) -> Result<JqVal, String> {
624        self.i += 1;
625        let mut out = Vec::new();
626        self.ws();
627        if self.b.get(self.i) == Some(&b']') {
628            self.i += 1;
629            return Ok(JqVal::arr(out));
630        }
631        loop {
632            self.ws();
633            out.push(self.value()?);
634            self.ws();
635            match self.b.get(self.i) {
636                Some(b',') => self.i += 1,
637                Some(b']') => {
638                    self.i += 1;
639                    return Ok(JqVal::arr(out));
640                }
641                _ => return Err(format!("expected `,` or `]` at byte {}", self.i)),
642            }
643        }
644    }
645    fn object(&mut self) -> Result<JqVal, String> {
646        self.i += 1;
647        let mut out: Vec<(Rc<str>, JqVal)> = Vec::new();
648        self.ws();
649        if self.b.get(self.i) == Some(&b'}') {
650            self.i += 1;
651            return Ok(JqVal::obj(out));
652        }
653        loop {
654            self.ws();
655            if self.b.get(self.i) != Some(&b'"') {
656                return Err(format!("expected a key string at byte {}", self.i));
657            }
658            let k: Rc<str> = self.string_rc()?;
659            self.ws();
660            if self.b.get(self.i) != Some(&b':') {
661                return Err(format!("expected `:` at byte {}", self.i));
662            }
663            self.i += 1;
664            self.ws();
665            let v = self.value()?;
666            // A duplicate key keeps its FIRST position and takes the LAST value,
667            // which is what jq's object builder does.
668            match out.iter_mut().find(|(ek, _)| *ek == k) {
669                Some(slot) => slot.1 = v,
670                None => out.push((k, v)),
671            }
672            self.ws();
673            match self.b.get(self.i) {
674                Some(b',') => self.i += 1,
675                Some(b'}') => {
676                    self.i += 1;
677                    return Ok(JqVal::obj(out));
678                }
679                _ => return Err(format!("expected `,` or `}}` at byte {}", self.i)),
680            }
681        }
682    }
683}
684
685/// jq's rendering of a number LITERAL it has not computed on.
686///
687/// jq 1.7+ keeps the source literal, but not verbatim: it stores it as a
688/// decNumber and re-emits it through decNumber's "to-scientific-string", so
689/// `1e2` comes back as `1E+2` and `12e3` as `1.2E+4` while `1.50` and
690/// `100000000000000000000000` come back unchanged. Measured against jq 1.8.2
691/// across the plain/exponential boundary (`0.000001` stays plain, `0.0000001`
692/// becomes `1E-7`).
693///
694/// The rule, from decNumber's `decToString`: with a coefficient of `n` digits
695/// and an exponent `exp`, the ADJUSTED exponent is `exp + n - 1`; plain notation
696/// is used when `exp <= 0 && adjusted >= -6`, and exponential otherwise.
697///
698/// Returns `None` for text this cannot canonicalize, in which case the caller
699/// keeps the double's own formatting.
700fn canonical_num_literal(text: &str) -> Option<String> {
701    let b = text.as_bytes();
702    let mut i = 0;
703    let neg = match b.first() {
704        Some(b'-') => {
705            i = 1;
706            true
707        }
708        Some(b'+') => {
709            i = 1;
710            false
711        }
712        _ => false,
713    };
714    let int_start = i;
715    while b.get(i).is_some_and(u8::is_ascii_digit) {
716        i += 1;
717    }
718    let int_part = &text[int_start..i];
719    let mut frac = "";
720    if b.get(i) == Some(&b'.') {
721        i += 1;
722        let fs = i;
723        while b.get(i).is_some_and(u8::is_ascii_digit) {
724            i += 1;
725        }
726        frac = &text[fs..i];
727    }
728    let mut exp: i64 = 0;
729    if matches!(b.get(i), Some(b'e') | Some(b'E')) {
730        i += 1;
731        let es = i;
732        if matches!(b.get(i), Some(b'+') | Some(b'-')) {
733            i += 1;
734        }
735        while b.get(i).is_some_and(u8::is_ascii_digit) {
736            i += 1;
737        }
738        exp = text[es..i].parse().ok()?;
739    }
740    if i != text.len() || (int_part.is_empty() && frac.is_empty()) {
741        return None;
742    }
743    exp -= frac.len() as i64;
744    let joined = format!("{int_part}{frac}");
745    // decNumber holds a coefficient with no leading zeros (but never empty).
746    let digits = joined.trim_start_matches('0');
747    let digits = if digits.is_empty() { "0" } else { digits };
748    let n = digits.len() as i64;
749    let sign = if neg { "-" } else { "" };
750    // decNumber renders a zero coefficient with a zero exponent as plain `0`,
751    // which is what makes `0e0` print as `0`.
752    if digits == "0" && exp >= 0 {
753        return Some(format!("{sign}0"));
754    }
755    let adjusted = exp + n - 1;
756    if exp <= 0 && adjusted >= -6 {
757        return Some(if exp == 0 {
758            format!("{sign}{digits}")
759        } else if n > -exp {
760            let split = (n + exp) as usize;
761            format!("{sign}{}.{}", &digits[..split], &digits[split..])
762        } else {
763            format!("{sign}0.{}{digits}", "0".repeat((-exp - n) as usize))
764        });
765    }
766    let (head, rest) = digits.split_at(1);
767    let mantissa = if rest.is_empty() {
768        head.to_string()
769    } else {
770        format!("{head}.{rest}")
771    };
772    Some(format!(
773        "{sign}{mantissa}E{}{}",
774        if adjusted < 0 { "-" } else { "+" },
775        adjusted.abs()
776    ))
777}
778
779/// jq's unary minus. jq 1.8 negates a number that still carries its literal
780/// as a decNumber, so the literal survives: `-100000000000000000001` and
781/// `1.50 | -.` print exactly, and `-1E1000` is `-1E+1000` rather than the
782/// clamped double. A zero coefficient negates to itself (`-0.0` is `0.0`,
783/// `0 | -.` is `0` where the computed `(1-1) | -.` is `-0`), which is
784/// decNumber's `0 - x`. The double rides along with the decimal: a literal too
785/// small for a double (`1E-400`) is `+0.0` and negates to `-0.0`, so
786/// `-1e-400 * 0` is `-0` as it is in jq. Measured against jq 1.8.2.
787fn negate_num(n: f64, lit: &NumLit) -> JqVal {
788    let lit = match lit {
789        NumLit::Computed => return JqVal::num(-n),
790        // The shortest form of `-n` is the shortest form of `n` with the sign
791        // flipped, so the result is canonical too; a zero coefficient has
792        // nothing to flip.
793        NumLit::Canonical => return JqVal::Num(if n == 0.0 { 0.0 } else { -n }, NumLit::Canonical),
794        NumLit::Text(lit) => lit,
795    };
796    let zero_coefficient = lit
797        .trim_start_matches('-')
798        .split(['E', 'e'])
799        .next()
800        .unwrap_or("")
801        .bytes()
802        .all(|b| b == b'0' || b == b'.');
803    let neg = if let Some(rest) = lit.strip_prefix('-') {
804        rest.to_string()
805    } else if zero_coefficient {
806        lit.to_string()
807    } else {
808        format!("-{lit}")
809    };
810    let v = if zero_coefficient { 0.0 } else { -n };
811    if neg == fmt_num(v) {
812        JqVal::Num(v, NumLit::Canonical)
813    } else {
814        JqVal::Num(v, NumLit::Text(Rc::from(neg.as_str())))
815    }
816}
817
818/// Build a number value from its source text. The number is a LITERAL either
819/// way; its text is stored only when jq would print something other than the
820/// double's own shortest form, and a `Canonical` literal is otherwise its
821/// equal — `9007199254740992` and `9007199254740993` share a double and still
822/// compare apart, because the first one's shortest form IS its digits.
823pub(crate) fn num_from_literal(n: f64, text: &str) -> JqVal {
824    if is_plain_shortest(text) {
825        return JqVal::Num(n, NumLit::Canonical);
826    }
827    match canonical_num_literal(text) {
828        Some(c) if c != fmt_num(n) => JqVal::Num(n, NumLit::Text(Rc::from(c.as_str()))),
829        Some(_) => JqVal::Num(n, NumLit::Canonical),
830        // Not a decimal at all (`Infinity`, `nan` from jq's own reader): jq
831        // holds those as plain doubles, never as decNumber literals.
832        None => JqVal::num(n),
833    }
834}
835
836/// Is `text` already both decNumber's canonical form AND the shortest decimal
837/// that round-trips to its double? Then no literal need be kept and neither
838/// formatter need run — which matters because this is on the JSON reader's
839/// innermost path, once per number in the stream.
840///
841/// The test is deliberately conservative: no exponent, no leading zero (except a
842/// lone `0` before the point), no leading zero INSIDE the fraction, no trailing
843/// zero in the fraction, at most 15 significant digits, and at most 15 digits
844/// before the point. Under 15 digits two distinct decimals cannot share a double
845/// (an IEEE double carries ~15.95 decimal digits), so no SHORTER decimal can
846/// round-trip to the same value and `text` is itself the shortest form; the two
847/// magnitude bounds keep it inside the band where both formatters render plainly
848/// rather than in exponent form. Without the fraction rule `0.000001` slipped
849/// through and printed as `1e-06`.
850///
851/// Anything this rejects falls through to the exact path, so a false negative
852/// costs time and never correctness.
853fn is_plain_shortest(text: &str) -> bool {
854    let b = text.as_bytes();
855    let mut i = usize::from(b.first() == Some(&b'-'));
856    let int_start = i;
857    while b.get(i).is_some_and(u8::is_ascii_digit) {
858        i += 1;
859    }
860    let int_len = i - int_start;
861    if int_len == 0 || int_len > 15 || (int_len > 1 && b[int_start] == b'0') {
862        return false;
863    }
864    let mut sig = if int_len == 1 && b[int_start] == b'0' {
865        0
866    } else {
867        int_len
868    };
869    if b.get(i) == Some(&b'.') {
870        i += 1;
871        let frac_start = i;
872        while b.get(i).is_some_and(u8::is_ascii_digit) {
873            i += 1;
874        }
875        let frac_len = i - frac_start;
876        if frac_len == 0 || b[i - 1] == b'0' {
877            return false;
878        }
879        // A `0.0…` value is below the plain/exponent boundary the two formatters
880        // draw differently, so only `0.<nonzero>` takes the fast path.
881        if sig == 0 {
882            if b[frac_start] == b'0' {
883                return false;
884            }
885            sig += frac_len;
886        } else {
887            sig += frac_len;
888        }
889    }
890    i == b.len() && sig > 0 && sig <= 15
891}
892
893/// jq's number rendering. Delegates to the formatter `crate::query` already
894/// validated against `jq 1.8.2` over 200,000 doubles, so there is exactly one
895/// number formatter in the tree and the two can never drift.
896pub fn fmt_num(v: f64) -> String {
897    // jq prints a computed negative zero with its sign (`0 * -1` is `-0`).
898    if v == 0.0 && v.is_sign_negative() {
899        return "-0".to_string();
900    }
901    crate::query::fmt_num(v)
902}
903
904/// Render a value as jq's compact JSON (`jq -c`).
905pub fn render(v: &JqVal) -> String {
906    let mut s = String::new();
907    write_val(&mut s, v);
908    s
909}
910
911/// Render a value the way `jq -r` prints it: a top-level STRING goes out raw,
912/// everything else is compact JSON.
913pub fn render_raw(v: &JqVal) -> String {
914    match v.bare() {
915        JqVal::Str(s) => s.to_string(),
916        other => render(other),
917    }
918}
919
920/// JSON has no place for YAML node metadata, so the box is dropped here: a
921/// commented, anchored, single-quoted YAML scalar renders as exactly the JSON
922/// its value alone would. `crate::ynode::emit` is the writer that keeps it.
923fn write_val(out: &mut String, v: &JqVal) {
924    match v.bare() {
925        JqVal::Null => out.push_str("null"),
926        JqVal::Bool(true) => out.push_str("true"),
927        JqVal::Bool(false) => out.push_str("false"),
928        JqVal::Num(n, lit) => match lit {
929            NumLit::Text(t) => out.push_str(t),
930            _ => out.push_str(&fmt_num(*n)),
931        },
932        JqVal::Str(s) => write_json_str(out, s),
933        JqVal::Arr(a) => {
934            out.push('[');
935            for (i, e) in a.iter().enumerate() {
936                if i > 0 {
937                    out.push(',');
938                }
939                write_val(out, e);
940            }
941            out.push(']');
942        }
943        JqVal::Obj(m) => {
944            out.push('{');
945            for (i, (k, val)) in m.iter().enumerate() {
946                if i > 0 {
947                    out.push(',');
948                }
949                write_json_str(out, k);
950                out.push(':');
951                write_val(out, val);
952            }
953            out.push('}');
954        }
955        JqVal::Node(_) => unreachable!("bare() never returns a Node"),
956    }
957}
958
959/// JSON string escaping, matching jq's string writer: the seven short escapes,
960/// and `\u00XX` for every remaining C0 control plus DEL (0x7f), which jq escapes
961/// even though JSON does not require it.
962fn write_json_str(out: &mut String, s: &str) {
963    out.push('"');
964    for c in s.chars() {
965        match c {
966            '"' => out.push_str("\\\""),
967            '\\' => out.push_str("\\\\"),
968            '\n' => out.push_str("\\n"),
969            '\r' => out.push_str("\\r"),
970            '\t' => out.push_str("\\t"),
971            '\u{8}' => out.push_str("\\b"),
972            '\u{c}' => out.push_str("\\f"),
973            c if (c as u32) < 0x20 || c as u32 == 0x7f => {
974                let _ = write!(out, "\\u{:04x}", c as u32);
975            }
976            c => out.push(c),
977        }
978    }
979    out.push('"');
980}
981
982// ─────────────────────────────────────────────────────────────────────────────
983// Lexer
984// ─────────────────────────────────────────────────────────────────────────────
985
986/// One piece of a jq string literal. `"a\(.b)c"` is `Lit("a")`, `Interp(".b")`,
987/// `Lit("c")`; the interpolation carries its RAW source and is parsed on demand,
988/// which keeps the lexer non-recursive.
989#[derive(Debug, Clone)]
990pub(crate) enum StrPiece {
991    Lit(String),
992    Interp(String),
993}
994
995#[derive(Debug, Clone, PartialEq)]
996enum Tok {
997    Ident(String),
998    /// `$name`.
999    Var(String),
1000    /// `@name`.
1001    Format(String),
1002    Num(f64, String),
1003    Str(Vec<StrPieceTok>),
1004    /// `.name` lexed as ONE token. Splitting it into `.` + an identifier would
1005    /// make `if . then 1 else 2 end` read `else` as a field name, which is the
1006    /// same reason jq's own lexer emits a single `FIELD` token here.
1007    Field(String),
1008    Op(&'static str),
1009}
1010
1011/// `StrPiece` inside a token needs `PartialEq` for the token stream's own
1012/// comparisons; the payload is plain text so deriving it is exact.
1013#[derive(Debug, Clone, PartialEq)]
1014enum StrPieceTok {
1015    Lit(String),
1016    Interp(String),
1017}
1018
1019impl From<StrPieceTok> for StrPiece {
1020    fn from(t: StrPieceTok) -> Self {
1021        match t {
1022            StrPieceTok::Lit(s) => StrPiece::Lit(s),
1023            StrPieceTok::Interp(s) => StrPiece::Interp(s),
1024        }
1025    }
1026}
1027
1028/// The multi-character operators, longest first so `//=` never lexes as `//`
1029/// then `=`, and `?//` never as `?` then `//`.
1030const OPS: &[&str] = &[
1031    "?//", "//=", "|=", "+=", "-=", "*=", "/=", "%=", "==", "!=", "<=", ">=", "//", "..", "|", ",",
1032    "=", "<", ">", "+", "-", "*", "/", "%", "(", ")", "[", "]", "{", "}", ":", ";", "?", ".",
1033];
1034
1035fn lex(src: &str) -> Result<Vec<Tok>, String> {
1036    let cs: Vec<char> = src.chars().collect();
1037    let mut i = 0usize;
1038    let mut out = Vec::new();
1039    while i < cs.len() {
1040        let c = cs[i];
1041        if c.is_whitespace() {
1042            i += 1;
1043            continue;
1044        }
1045        if c == '#' {
1046            while i < cs.len() && cs[i] != '\n' {
1047                i += 1;
1048            }
1049            continue;
1050        }
1051        if c == '"' {
1052            let (pieces, next) = lex_string(&cs, i)?;
1053            out.push(Tok::Str(pieces));
1054            i = next;
1055            continue;
1056        }
1057        if c == '$' {
1058            let start = i + 1;
1059            let mut j = start;
1060            while j < cs.len() && (cs[j].is_alphanumeric() || cs[j] == '_') {
1061                j += 1;
1062            }
1063            if j == start {
1064                return Err("jq: `$` must be followed by a variable name".into());
1065            }
1066            let name: String = cs[start..j].iter().collect();
1067            // `$__loc__` is the line of THIS token, which only the lexer knows.
1068            let name = if name == "__loc__" {
1069                format!("__loc__:{}", 1 + newlines_before(&cs, i))
1070            } else {
1071                name
1072            };
1073            out.push(Tok::Var(name));
1074            i = j;
1075            continue;
1076        }
1077        if c == '@' {
1078            let start = i + 1;
1079            let mut j = start;
1080            while j < cs.len() && (cs[j].is_alphanumeric() || cs[j] == '_') {
1081                j += 1;
1082            }
1083            if j == start {
1084                return Err("jq: `@` must be followed by a format name".into());
1085            }
1086            out.push(Tok::Format(cs[start..j].iter().collect()));
1087            i = j;
1088            continue;
1089        }
1090        // `.name` -- but not `..`, and not a `.` that begins a number (`.5`).
1091        if c == '.'
1092            && cs
1093                .get(i + 1)
1094                .is_some_and(|n| n.is_alphabetic() || *n == '_')
1095        {
1096            let start = i + 1;
1097            let mut j = start;
1098            while j < cs.len() && (cs[j].is_alphanumeric() || cs[j] == '_') {
1099                j += 1;
1100            }
1101            out.push(Tok::Field(cs[start..j].iter().collect()));
1102            i = j;
1103            continue;
1104        }
1105        // A number, lexed as jq 1.8's scanner does: `([0-9]+(\.[0-9]*)?|\.[0-9]+)`
1106        // then an optional exponent, maximal munch. So `.5` is 0.5 and `1.` is
1107        // 1, and `1.foo` is the literal `1.` followed by `foo` -- the syntax
1108        // error jq reports -- rather than a field access on 1.
1109        let fraction_first = c == '.' && cs.get(i + 1).is_some_and(|d| d.is_ascii_digit());
1110        if c.is_ascii_digit() || fraction_first {
1111            let start = i;
1112            while i < cs.len() && cs[i].is_ascii_digit() {
1113                i += 1;
1114            }
1115            if cs.get(i) == Some(&'.') {
1116                i += 1;
1117                while i < cs.len() && cs[i].is_ascii_digit() {
1118                    i += 1;
1119                }
1120            }
1121            if matches!(cs.get(i), Some('e') | Some('E')) {
1122                let save = i;
1123                let mut j = i + 1;
1124                if matches!(cs.get(j), Some('+') | Some('-')) {
1125                    j += 1;
1126                }
1127                if matches!(cs.get(j), Some(d) if d.is_ascii_digit()) {
1128                    while matches!(cs.get(j), Some(d) if d.is_ascii_digit()) {
1129                        j += 1;
1130                    }
1131                    i = j;
1132                } else {
1133                    i = save;
1134                }
1135            }
1136            let text: String = cs[start..i].iter().collect();
1137            let n: f64 = text
1138                .parse()
1139                .map_err(|_| format!("jq: bad number literal `{text}`"))?;
1140            out.push(Tok::Num(n, text));
1141            continue;
1142        }
1143        if c.is_alphabetic() || c == '_' {
1144            let start = i;
1145            while i < cs.len() && (cs[i].is_alphanumeric() || cs[i] == '_') {
1146                i += 1;
1147            }
1148            // `a::b` is jq's module-qualified name; keep it as one identifier so
1149            // the parser sees the whole name rather than a stray `:`.
1150            while cs.get(i) == Some(&':') && cs.get(i + 1) == Some(&':') {
1151                i += 2;
1152                while i < cs.len() && (cs[i].is_alphanumeric() || cs[i] == '_') {
1153                    i += 1;
1154                }
1155            }
1156            out.push(Tok::Ident(cs[start..i].iter().collect()));
1157            continue;
1158        }
1159        let rest: String = cs[i..].iter().collect();
1160        match OPS.iter().find(|op| rest.starts_with(**op)) {
1161            Some(op) => {
1162                out.push(Tok::Op(op));
1163                i += op.chars().count();
1164            }
1165            None => return Err(format!("jq: unexpected character `{c}`")),
1166        }
1167    }
1168    Ok(out)
1169}
1170
1171/// Lex a `"…"` literal starting at `cs[i]`, splitting out `\(…)` interpolations.
1172/// How many newlines precede `cs[at]`.
1173/// The value of a lexer-tagged `$__loc__:LINE` variable token, `None` for any
1174/// other variable.
1175fn loc_literal(var: &str) -> Option<JqVal> {
1176    let line: f64 = var.strip_prefix("__loc__:")?.parse().unwrap_or(1.0);
1177    Some(JqVal::obj(vec![
1178        (Rc::from("file"), JqVal::str("<top-level>")),
1179        (Rc::from("line"), JqVal::num(line)),
1180    ]))
1181}
1182
1183fn newlines_before(cs: &[char], at: usize) -> usize {
1184    cs[..at].iter().filter(|c| **c == '\n').count()
1185}
1186
1187fn lex_string(cs: &[char], i: usize) -> Result<(Vec<StrPieceTok>, usize), String> {
1188    let mut i = i + 1;
1189    let mut pieces = Vec::new();
1190    let mut cur = String::new();
1191    while i < cs.len() {
1192        match cs[i] {
1193            '"' => {
1194                if !cur.is_empty() || pieces.is_empty() {
1195                    pieces.push(StrPieceTok::Lit(cur));
1196                }
1197                return Ok((pieces, i + 1));
1198            }
1199            '\\' => {
1200                let e = *cs.get(i + 1).ok_or("jq: unterminated string escape")?;
1201                if e == '(' {
1202                    // Interpolation: copy the balanced parenthesised source out
1203                    // verbatim, tracking nested strings so a `)` inside one does
1204                    // not close it early.
1205                    if !cur.is_empty() {
1206                        pieces.push(StrPieceTok::Lit(std::mem::take(&mut cur)));
1207                    }
1208                    let start = i + 2;
1209                    let j = crate::lexer::skip_jq_interpolation(cs, start)
1210                        .ok_or("jq: unterminated string interpolation")?
1211                        - 1;
1212                    let mut src: String = cs[start..j].iter().collect();
1213                    if src.contains("__loc__") {
1214                        // The piece is parsed on its own, so it carries the
1215                        // line it sits on as leading newlines.
1216                        src.insert_str(0, &"\n".repeat(newlines_before(cs, start)));
1217                    }
1218                    pieces.push(StrPieceTok::Interp(src));
1219                    i = j + 1;
1220                    continue;
1221                }
1222                cur.push(match e {
1223                    'n' => '\n',
1224                    't' => '\t',
1225                    'r' => '\r',
1226                    'b' => '\u{8}',
1227                    'f' => '\u{c}',
1228                    '/' => '/',
1229                    '\\' => '\\',
1230                    '"' => '"',
1231                    'u' => {
1232                        let hex: String = cs
1233                            .get(i + 2..i + 6)
1234                            .ok_or("jq: truncated \\u")?
1235                            .iter()
1236                            .collect();
1237                        let cp = u32::from_str_radix(&hex, 16).map_err(|_| "jq: bad \\u escape")?;
1238                        i += 4;
1239                        // Surrogate pair, same rule as the JSON reader.
1240                        if (0xD800..0xDC00).contains(&cp)
1241                            && cs.get(i + 2) == Some(&'\\')
1242                            && cs.get(i + 3) == Some(&'u')
1243                        {
1244                            let hex2: String = cs
1245                                .get(i + 4..i + 8)
1246                                .ok_or("jq: truncated \\u")?
1247                                .iter()
1248                                .collect();
1249                            if let Ok(lo) = u32::from_str_radix(&hex2, 16) {
1250                                if (0xDC00..0xE000).contains(&lo) {
1251                                    i += 6;
1252                                    cur.push(
1253                                        char::from_u32(
1254                                            0x1_0000 + ((cp - 0xD800) << 10) + (lo - 0xDC00),
1255                                        )
1256                                        .unwrap_or('\u{fffd}'),
1257                                    );
1258                                    i += 2;
1259                                    continue;
1260                                }
1261                            }
1262                        }
1263                        // A program literal REFUSES a high surrogate that does not pair
1264                        // (jq's lexer); a lone LOW one is U+FFFD.
1265                        if (0xD800..0xDC00).contains(&cp) {
1266                            return Err("jq: Invalid \\uXXXX\\uXXXX surrogate pair escape".into());
1267                        }
1268                        char::from_u32(cp).unwrap_or('\u{fffd}')
1269                    }
1270                    other => return Err(format!("jq: bad escape `\\{other}`")),
1271                });
1272                i += 2;
1273            }
1274            c => {
1275                cur.push(c);
1276                i += 1;
1277            }
1278        }
1279    }
1280    Err("jq: unterminated string".into())
1281}
1282
1283// ─────────────────────────────────────────────────────────────────────────────
1284// AST
1285// ─────────────────────────────────────────────────────────────────────────────
1286
1287#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1288pub(crate) enum BinOp {
1289    Add,
1290    Sub,
1291    Mul,
1292    Div,
1293    Mod,
1294    Eq,
1295    Ne,
1296    Lt,
1297    Le,
1298    Gt,
1299    Ge,
1300}
1301
1302/// The update-assignment family. `Set` is `=`, `Update` is `|=`, and the rest
1303/// are jq's arithmetic update forms, which are defined as `a op= b` ==
1304/// `a |= . op b` with `b` evaluated against the ORIGINAL input (`$__x`).
1305#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1306pub(crate) enum AssignOp {
1307    Set,
1308    Update,
1309    Add,
1310    Sub,
1311    Mul,
1312    Div,
1313    Mod,
1314    Alt,
1315}
1316
1317/// A destructuring pattern for `as`, `reduce`, `foreach`.
1318#[derive(Debug, Clone)]
1319pub(crate) enum Pattern {
1320    Var(Rc<str>),
1321    Arr(Vec<Pattern>),
1322    /// Each entry is (key filter, optional sub-pattern). `{$a}` is sugar for
1323    /// `{a: $a}` and produces `(Lit("a"), None)` with the variable named `a`.
1324    Obj(Vec<ObjPatEntry>),
1325}
1326
1327#[derive(Debug, Clone)]
1328pub(crate) struct FuncDef {
1329    name: Rc<str>,
1330    /// Filter parameters. A `$x` parameter is desugared at parse time into a
1331    /// filter parameter plus a `. as $x` binding around the body, which is what
1332    /// jq's own `parser.y` does.
1333    params: Vec<Rc<str>>,
1334    body: Rc<Filter>,
1335}
1336
1337#[derive(Debug, Clone)]
1338pub(crate) enum ObjEntry {
1339    /// `key: value`, where the key is any filter producing a string.
1340    KeyVal(Filter, Filter),
1341}
1342
1343#[derive(Debug, Clone)]
1344pub(crate) enum Filter {
1345    Identity,
1346    /// `..` — jq's `recurse`.
1347    RecurseDefault,
1348    Lit(JqVal),
1349    /// An interpolated string, optionally under a `@fmt "…"` prefix which
1350    /// applies that format to every INTERPOLATED piece (never to the literals).
1351    Str(Vec<StrPiece>, Option<Rc<str>>),
1352    /// `@base64` used as a filter in its own right.
1353    Format(Rc<str>),
1354    Field(Box<Filter>, Rc<str>),
1355    Index(Box<Filter>, Box<Filter>),
1356    Slice(Box<Filter>, Option<Box<Filter>>, Option<Box<Filter>>),
1357    Iterate(Box<Filter>),
1358    /// `f?` — swallow errors raised by `f`, emitting nothing instead.
1359    Optional(Box<Filter>),
1360    /// `.a?`, `.[e]?`, `.[a:b]?`, `.[]?` — parser.y's INDEX_OPT/EACH_OPT. The
1361    /// inner filter is a `Field`/`Index`/`Slice`/`Iterate`, and only that
1362    /// step's own indexing error is suppressed: an error from its base or its
1363    /// key still raises.
1364    IndexOpt(Box<Filter>),
1365    Pipe(Box<Filter>, Box<Filter>),
1366    Comma(Box<Filter>, Box<Filter>),
1367    Neg(Box<Filter>),
1368    Bin(BinOp, Box<Filter>, Box<Filter>),
1369    And(Box<Filter>, Box<Filter>),
1370    Or(Box<Filter>, Box<Filter>),
1371    Alt(Box<Filter>, Box<Filter>),
1372    Assign(AssignOp, Box<Filter>, Box<Filter>),
1373    /// `if a then b elif c then d else e end`; the `else` may be absent, in
1374    /// which case a false condition yields the INPUT unchanged (jq 1.7+).
1375    If(Vec<(Filter, Filter)>, Option<Box<Filter>>),
1376    Try(Box<Filter>, Option<Box<Filter>>),
1377    Reduce(Box<Filter>, Pattern, Box<Filter>, Box<Filter>),
1378    Foreach(
1379        Box<Filter>,
1380        Pattern,
1381        Box<Filter>,
1382        Box<Filter>,
1383        Option<Box<Filter>>,
1384    ),
1385    /// `SOURCE as PAT ?// PAT | BODY`.
1386    Bind(Box<Filter>, Vec<Pattern>, Box<Filter>),
1387    Label(Rc<str>, Box<Filter>),
1388    Break(Rc<str>),
1389    Var(Rc<str>),
1390    Call(Rc<str>, Vec<Rc<Filter>>),
1391    Def(Rc<FuncDef>, Box<Filter>),
1392    Object(Vec<ObjEntry>),
1393    /// `[f]`, or `[]` when the inner filter is absent.
1394    Array(Option<Box<Filter>>),
1395}
1396
1397// ─────────────────────────────────────────────────────────────────────────────
1398// Parser
1399// ─────────────────────────────────────────────────────────────────────────────
1400
1401struct Parser {
1402    t: Vec<Tok>,
1403    i: usize,
1404}
1405
1406/// Parse a complete jq program.
1407pub(crate) fn parse(src: &str) -> Result<Filter, String> {
1408    let toks = lex(src)?;
1409    let mut p = Parser { t: toks, i: 0 };
1410    let f = p.pipe()?;
1411    if p.i != p.t.len() {
1412        return Err(format!("jq: unexpected `{}` in `{src}`", p.describe(p.i)));
1413    }
1414    Ok(f)
1415}
1416
1417impl Parser {
1418    fn describe(&self, i: usize) -> String {
1419        match self.t.get(i) {
1420            None => "end of program".into(),
1421            Some(Tok::Ident(s)) => s.clone(),
1422            Some(Tok::Var(s)) => format!("${s}"),
1423            Some(Tok::Format(s)) => format!("@{s}"),
1424            Some(Tok::Num(_, s)) => s.clone(),
1425            Some(Tok::Field(f)) => format!(".{f}"),
1426            Some(Tok::Str(_)) => "a string".into(),
1427            Some(Tok::Op(o)) => (*o).to_string(),
1428        }
1429    }
1430    fn peek(&self) -> Option<&Tok> {
1431        self.t.get(self.i)
1432    }
1433    fn is_op(&self, op: &str) -> bool {
1434        matches!(self.peek(), Some(Tok::Op(o)) if *o == op)
1435    }
1436    fn is_kw(&self, kw: &str) -> bool {
1437        matches!(self.peek(), Some(Tok::Ident(s)) if s == kw)
1438    }
1439    fn eat_op(&mut self, op: &str) -> bool {
1440        if self.is_op(op) {
1441            self.i += 1;
1442            true
1443        } else {
1444            false
1445        }
1446    }
1447    fn eat_kw(&mut self, kw: &str) -> bool {
1448        if self.is_kw(kw) {
1449            self.i += 1;
1450            true
1451        } else {
1452            false
1453        }
1454    }
1455    fn want_op(&mut self, op: &str) -> Result<(), String> {
1456        if self.eat_op(op) {
1457            Ok(())
1458        } else {
1459            Err(format!(
1460                "jq: expected `{op}`, found `{}`",
1461                self.describe(self.i)
1462            ))
1463        }
1464    }
1465    fn want_kw(&mut self, kw: &str) -> Result<(), String> {
1466        if self.eat_kw(kw) {
1467            Ok(())
1468        } else {
1469            Err(format!(
1470                "jq: expected `{kw}`, found `{}`",
1471                self.describe(self.i)
1472            ))
1473        }
1474    }
1475    fn ident(&mut self) -> Result<Rc<str>, String> {
1476        match self.peek() {
1477            Some(Tok::Ident(s)) => {
1478                let s: Rc<str> = Rc::from(s.as_str());
1479                self.i += 1;
1480                Ok(s)
1481            }
1482            _ => Err(format!(
1483                "jq: expected a name, found `{}`",
1484                self.describe(self.i)
1485            )),
1486        }
1487    }
1488    fn var(&mut self) -> Result<Rc<str>, String> {
1489        match self.peek() {
1490            Some(Tok::Var(s)) => {
1491                let s: Rc<str> = Rc::from(s.as_str());
1492                self.i += 1;
1493                Ok(s)
1494            }
1495            _ => Err(format!(
1496                "jq: expected `$name`, found `{}`",
1497                self.describe(self.i)
1498            )),
1499        }
1500    }
1501
1502    /// `|` — the loosest binder, right-associative, and the level `def` and
1503    /// `as`-bindings extend over.
1504    fn pipe(&mut self) -> Result<Filter, String> {
1505        if self.is_kw("def") {
1506            let def = self.funcdef()?;
1507            let rest = self.pipe()?;
1508            return Ok(Filter::Def(Rc::new(def), Box::new(rest)));
1509        }
1510        if self.is_kw("label") {
1511            self.i += 1;
1512            let name = self.var()?;
1513            self.want_op("|")?;
1514            let body = self.pipe()?;
1515            return Ok(Filter::Label(name, Box::new(body)));
1516        }
1517        let lhs = self.comma()?;
1518        if self.eat_op("|") {
1519            let rhs = self.pipe()?;
1520            return Ok(Filter::Pipe(Box::new(lhs), Box::new(rhs)));
1521        }
1522        Ok(lhs)
1523    }
1524
1525    fn funcdef(&mut self) -> Result<FuncDef, String> {
1526        self.want_kw("def")?;
1527        let name = self.ident()?;
1528        let mut params = Vec::new();
1529        let mut value_params = Vec::new();
1530        if self.eat_op("(") {
1531            loop {
1532                match self.peek() {
1533                    Some(Tok::Var(v)) => {
1534                        // `def f($a)` is jq's sugar for a filter parameter plus
1535                        // `. as $a` at the top of the body, evaluated once.
1536                        let v: Rc<str> = Rc::from(v.as_str());
1537                        self.i += 1;
1538                        params.push(v.clone());
1539                        value_params.push(v);
1540                    }
1541                    _ => params.push(self.ident()?),
1542                }
1543                if self.eat_op(";") {
1544                    continue;
1545                }
1546                self.want_op(")")?;
1547                break;
1548            }
1549        }
1550        self.want_op(":")?;
1551        let mut body = self.pipe()?;
1552        self.want_op(";")?;
1553        for v in value_params.into_iter().rev() {
1554            body = Filter::Bind(
1555                Box::new(Filter::Call(v.clone(), vec![])),
1556                vec![Pattern::Var(v)],
1557                Box::new(body),
1558            );
1559        }
1560        Ok(FuncDef {
1561            name,
1562            params,
1563            body: Rc::new(body),
1564        })
1565    }
1566
1567    fn pattern(&mut self) -> Result<Pattern, String> {
1568        match self.peek() {
1569            Some(Tok::Var(_)) => Ok(Pattern::Var(self.var()?)),
1570            Some(Tok::Op("[")) => {
1571                self.i += 1;
1572                // parser.y's `ArrayPats` holds at least one `Pattern`: `[]` is
1573                // a syntax error.
1574                let mut out = Vec::new();
1575                loop {
1576                    out.push(self.pattern()?);
1577                    if self.eat_op(",") {
1578                        continue;
1579                    }
1580                    self.want_op("]")?;
1581                    break;
1582                }
1583                Ok(Pattern::Arr(out))
1584            }
1585            Some(Tok::Op("{")) => {
1586                self.i += 1;
1587                let mut out = Vec::new();
1588                loop {
1589                    match self.peek().cloned() {
1590                        // `{$a}` — bind `.a` to `$a`. `{$a: P}` binds `$a` to `.a` as
1591                        // well and destructures the same value with `P`: the
1592                        // key is the variable's NAME, never its value.
1593                        Some(Tok::Var(v)) => {
1594                            self.i += 1;
1595                            let name: Rc<str> = Rc::from(v.as_str());
1596                            let sub = if self.eat_op(":") {
1597                                Some(self.pattern()?)
1598                            } else {
1599                                None
1600                            };
1601                            out.push((Filter::Lit(JqVal::str(v.clone())), sub, Some(name)));
1602                        }
1603                        Some(Tok::Ident(k)) => {
1604                            self.i += 1;
1605                            self.want_op(":")?;
1606                            let sub = self.pattern()?;
1607                            out.push((Filter::Lit(JqVal::str(k)), Some(sub), None));
1608                        }
1609                        Some(Tok::Str(pieces)) => {
1610                            self.i += 1;
1611                            self.want_op(":")?;
1612                            let sub = self.pattern()?;
1613                            out.push((
1614                                Filter::Str(pieces.into_iter().map(Into::into).collect(), None),
1615                                Some(sub),
1616                                None,
1617                            ));
1618                        }
1619                        Some(Tok::Op("(")) => {
1620                            self.i += 1;
1621                            let k = self.pipe()?;
1622                            self.want_op(")")?;
1623                            self.want_op(":")?;
1624                            let sub = self.pattern()?;
1625                            out.push((k, Some(sub), None));
1626                        }
1627                        _ => {
1628                            return Err(format!(
1629                                "jq: bad object pattern near `{}`",
1630                                self.describe(self.i)
1631                            ))
1632                        }
1633                    }
1634                    if self.eat_op(",") {
1635                        continue;
1636                    }
1637                    self.want_op("}")?;
1638                    break;
1639                }
1640                Ok(Pattern::Obj(out))
1641            }
1642            _ => Err(format!(
1643                "jq: expected a destructuring pattern, found `{}`",
1644                self.describe(self.i)
1645            )),
1646        }
1647    }
1648
1649    /// `,` — left-associative, binds tighter than `|`.
1650    fn comma(&mut self) -> Result<Filter, String> {
1651        let mut lhs = self.bind()?;
1652        while self.eat_op(",") {
1653            let rhs = self.bind()?;
1654            lhs = Filter::Comma(Box::new(lhs), Box::new(rhs));
1655        }
1656        Ok(lhs)
1657    }
1658
1659    /// `Expr "as" Patterns '|' Query` — jq 1.8's production. The SOURCE is a
1660    /// whole operator expression (everything that binds tighter than `,`), and
1661    /// the BODY is a full query running to the end of the pipeline. Measured
1662    /// against jq 1.8.2: `1 + 2 as $x | $x * 10` is `30`, `-1 as $x | 5` is
1663    /// `5`, and `[1, 2 as $x | $x]` is `[1,2]` — the `,` stays outside.
1664    fn bind(&mut self) -> Result<Filter, String> {
1665        let src = self.alt()?;
1666        if !self.is_kw("as") {
1667            return Ok(src);
1668        }
1669        self.i += 1;
1670        let mut pats = vec![self.pattern()?];
1671        while self.eat_op("?//") {
1672            pats.push(self.pattern()?);
1673        }
1674        // yq's POSTFIX REDUCE: `.[] as $item ireduce (0; . + $item)`, where
1675        // jq writes `reduce .[] as $item (0; . + $item)`. Same three parts in
1676        // a different order, and `as … ireduce` is not valid jq either — jq
1677        // requires a `|` here — so this is another shape with no owner.
1678        if matches!(self.peek(), Some(Tok::Ident(n)) if n == "ireduce") {
1679            self.i += 1;
1680            self.want_op("(")?;
1681            let init = self.pipe()?;
1682            self.want_op(";")?;
1683            let update = self.pipe()?;
1684            self.want_op(")")?;
1685            return Ok(Filter::Reduce(
1686                Box::new(src),
1687                pats.remove(0),
1688                Box::new(init),
1689                Box::new(update),
1690            ));
1691        }
1692        self.want_op("|")?;
1693        let body = self.pipe()?;
1694        Ok(Filter::Bind(Box::new(src), pats, Box::new(body)))
1695    }
1696
1697    /// `//` — right-associative (jq's `%right "//"`).
1698    fn alt(&mut self) -> Result<Filter, String> {
1699        let lhs = self.assign()?;
1700        if self.eat_op("//") {
1701            let rhs = self.alt()?;
1702            return Ok(Filter::Alt(Box::new(lhs), Box::new(rhs)));
1703        }
1704        Ok(lhs)
1705    }
1706
1707    /// The assignment family — non-associative in jq's grammar, so exactly one
1708    /// operator is accepted at this level.
1709    fn assign(&mut self) -> Result<Filter, String> {
1710        let lhs = self.or()?;
1711        let op = match self.peek() {
1712            Some(Tok::Op("=")) => AssignOp::Set,
1713            Some(Tok::Op("|=")) => AssignOp::Update,
1714            Some(Tok::Op("+=")) => AssignOp::Add,
1715            Some(Tok::Op("-=")) => AssignOp::Sub,
1716            Some(Tok::Op("*=")) => AssignOp::Mul,
1717            Some(Tok::Op("/=")) => AssignOp::Div,
1718            Some(Tok::Op("%=")) => AssignOp::Mod,
1719            Some(Tok::Op("//=")) => AssignOp::Alt,
1720            _ => return Ok(lhs),
1721        };
1722        self.i += 1;
1723        let rhs = self.or()?;
1724        Ok(Filter::Assign(op, Box::new(lhs), Box::new(rhs)))
1725    }
1726
1727    fn or(&mut self) -> Result<Filter, String> {
1728        let mut lhs = self.and()?;
1729        while self.is_kw("or") {
1730            self.i += 1;
1731            let rhs = self.and()?;
1732            lhs = Filter::Or(Box::new(lhs), Box::new(rhs));
1733        }
1734        Ok(lhs)
1735    }
1736
1737    fn and(&mut self) -> Result<Filter, String> {
1738        let mut lhs = self.compare()?;
1739        while self.is_kw("and") {
1740            self.i += 1;
1741            let rhs = self.compare()?;
1742            lhs = Filter::And(Box::new(lhs), Box::new(rhs));
1743        }
1744        Ok(lhs)
1745    }
1746
1747    /// The comparisons are `%nonassoc` in jq, so at most one appears here.
1748    fn compare(&mut self) -> Result<Filter, String> {
1749        let lhs = self.additive()?;
1750        let op = match self.peek() {
1751            Some(Tok::Op("==")) => BinOp::Eq,
1752            Some(Tok::Op("!=")) => BinOp::Ne,
1753            Some(Tok::Op("<")) => BinOp::Lt,
1754            Some(Tok::Op("<=")) => BinOp::Le,
1755            Some(Tok::Op(">")) => BinOp::Gt,
1756            Some(Tok::Op(">=")) => BinOp::Ge,
1757            _ => return Ok(lhs),
1758        };
1759        self.i += 1;
1760        let rhs = self.additive()?;
1761        Ok(Filter::Bin(op, Box::new(lhs), Box::new(rhs)))
1762    }
1763
1764    fn additive(&mut self) -> Result<Filter, String> {
1765        let mut lhs = self.multiplicative()?;
1766        loop {
1767            let op = if self.is_op("+") {
1768                BinOp::Add
1769            } else if self.is_op("-") {
1770                BinOp::Sub
1771            } else {
1772                return Ok(lhs);
1773            };
1774            self.i += 1;
1775            let rhs = self.multiplicative()?;
1776            lhs = Filter::Bin(op, Box::new(lhs), Box::new(rhs));
1777        }
1778    }
1779
1780    fn multiplicative(&mut self) -> Result<Filter, String> {
1781        let mut lhs = self.unary()?;
1782        loop {
1783            let op = if self.is_op("*") {
1784                BinOp::Mul
1785            } else if self.is_op("/") {
1786                BinOp::Div
1787            } else if self.is_op("%") {
1788                BinOp::Mod
1789            } else {
1790                return Ok(lhs);
1791            };
1792            self.i += 1;
1793            let rhs = self.unary()?;
1794            lhs = Filter::Bin(op, Box::new(lhs), Box::new(rhs));
1795        }
1796    }
1797
1798    fn unary(&mut self) -> Result<Filter, String> {
1799        if self.eat_op("-") {
1800            let inner = self.unary()?;
1801            return Ok(Filter::Neg(Box::new(inner)));
1802        }
1803        self.postfix()
1804    }
1805}
1806
1807impl Parser {
1808    /// A term plus its postfix chain (`.k`, `[e]`, `[]`, `[a:b]`, `?`). An
1809    /// `as`-binding is not part of it: its source is a whole expression (see
1810    /// `bind`).
1811    fn postfix(&mut self) -> Result<Filter, String> {
1812        // parser.y gives `?` two meanings. Directly after an index step
1813        // (`Term FIELD '?'`, `Term '[' Query ']' '?'`, `Term '[' ']' '?'`, the
1814        // slices) it is INDEX_OPT/EACH_OPT, which suppresses only that step's
1815        // own error; anywhere else (`Term '?'`) it is `try`. `index_step` says
1816        // whether the term so far ends in such a step.
1817        let mut index_step = matches!(
1818            (self.peek(), self.t.get(self.i + 1)),
1819            (Some(Tok::Field(_)), _) | (Some(Tok::Op(".")), Some(Tok::Str(_) | Tok::Op("[")))
1820        );
1821        let mut f = self.term()?;
1822        loop {
1823            if self.eat_op("?") {
1824                f = if index_step {
1825                    Filter::IndexOpt(Box::new(f))
1826                } else {
1827                    Filter::Optional(Box::new(f))
1828                };
1829                index_step = false;
1830                continue;
1831            }
1832            // Every continuation below but the metadata postfix is an index step.
1833            index_step = true;
1834            if let Some(Tok::Field(name)) = self.peek() {
1835                let name: Rc<str> = Rc::from(name.as_str());
1836                self.i += 1;
1837                f = Filter::Field(Box::new(f), name);
1838                continue;
1839            }
1840            if self.is_op(".") {
1841                // `."foo"` continuing a term. A bare `.` followed by `[` is the
1842                // `.[…]` form, also a continuation.
1843                match self.t.get(self.i + 1) {
1844                    Some(Tok::Str(pieces)) => {
1845                        let pieces: Vec<StrPiece> =
1846                            pieces.clone().into_iter().map(Into::into).collect();
1847                        self.i += 2;
1848                        f = Filter::Index(Box::new(f), Box::new(Filter::Str(pieces, None)));
1849                        continue;
1850                    }
1851                    Some(Tok::Op("[")) => {
1852                        self.i += 1;
1853                        continue;
1854                    }
1855                    _ => {}
1856                }
1857            }
1858            if self.is_op("[") {
1859                self.i += 1;
1860                f = self.bracket_suffix(f)?;
1861                continue;
1862            }
1863            // yq's METADATA POSTFIX: `.a anchor`, and with it `.a anchor = "x"`.
1864            //
1865            // jq never allows a bare identifier to follow a complete expression —
1866            // juxtaposition is a syntax error in every jq grammar position — so
1867            // claiming this shape takes nothing away from the jq leg. It desugars
1868            // to the pipe arb already spelled it with, which is what makes the
1869            // ASSIGNMENT form work for free: `.a anchor = "x"` is
1870            // `Assign(Set, Pipe(.a, anchor), "x")`, and `eval_assign` already
1871            // recognises that left-hand side and edits the whole document.
1872            if let Some(Tok::Ident(name)) = self.peek() {
1873                if is_meta_setter(name) || matches!(&**name, "alias" | "kind") {
1874                    let name: Rc<str> = Rc::from(name.as_str());
1875                    self.i += 1;
1876                    f = Filter::Pipe(Box::new(f), Box::new(Filter::Call(name, Vec::new())));
1877                    index_step = false;
1878                    continue;
1879                }
1880            }
1881            break;
1882        }
1883        Ok(f)
1884    }
1885
1886    /// The `[…]` suffix, already past the `[`: `[]` iterate, `[e]` index,
1887    /// `[a:b]` / `[a:]` / `[:b]` slice.
1888    fn bracket_suffix(&mut self, base: Filter) -> Result<Filter, String> {
1889        if self.eat_op("]") {
1890            return Ok(Filter::Iterate(Box::new(base)));
1891        }
1892        if self.eat_op(":") {
1893            let hi = self.pipe()?;
1894            self.want_op("]")?;
1895            return Ok(Filter::Slice(Box::new(base), None, Some(Box::new(hi))));
1896        }
1897        let first = self.pipe()?;
1898        if self.eat_op(":") {
1899            if self.eat_op("]") {
1900                return Ok(Filter::Slice(Box::new(base), Some(Box::new(first)), None));
1901            }
1902            let hi = self.pipe()?;
1903            self.want_op("]")?;
1904            return Ok(Filter::Slice(
1905                Box::new(base),
1906                Some(Box::new(first)),
1907                Some(Box::new(hi)),
1908            ));
1909        }
1910        self.want_op("]")?;
1911        Ok(Filter::Index(Box::new(base), Box::new(first)))
1912    }
1913
1914    fn term(&mut self) -> Result<Filter, String> {
1915        match self.peek().cloned() {
1916            None => Err("jq: unexpected end of program".into()),
1917            Some(Tok::Op("..")) => {
1918                self.i += 1;
1919                Ok(Filter::RecurseDefault)
1920            }
1921            Some(Tok::Field(name)) => {
1922                self.i += 1;
1923                Ok(Filter::Field(
1924                    Box::new(Filter::Identity),
1925                    Rc::from(name.as_str()),
1926                ))
1927            }
1928            Some(Tok::Op(".")) => {
1929                self.i += 1;
1930                match self.peek().cloned() {
1931                    Some(Tok::Str(pieces)) => {
1932                        self.i += 1;
1933                        Ok(Filter::Index(
1934                            Box::new(Filter::Identity),
1935                            Box::new(Filter::Str(
1936                                pieces.into_iter().map(Into::into).collect(),
1937                                None,
1938                            )),
1939                        ))
1940                    }
1941                    Some(Tok::Op("[")) => {
1942                        self.i += 1;
1943                        self.bracket_suffix(Filter::Identity)
1944                    }
1945                    _ => Ok(Filter::Identity),
1946                }
1947            }
1948            Some(Tok::Num(n, text)) => {
1949                self.i += 1;
1950                Ok(Filter::Lit(num_from_literal(n, &text)))
1951            }
1952            Some(Tok::Str(pieces)) => {
1953                self.i += 1;
1954                Ok(Filter::Str(
1955                    pieces.into_iter().map(Into::into).collect(),
1956                    None,
1957                ))
1958            }
1959            Some(Tok::Format(name)) => {
1960                self.i += 1;
1961                // `@fmt "…"` applies the format to the string's interpolations;
1962                // `@fmt` alone is the format applied to `.`.
1963                if let Some(Tok::Str(pieces)) = self.peek().cloned() {
1964                    self.i += 1;
1965                    return Ok(Filter::Str(
1966                        pieces.into_iter().map(Into::into).collect(),
1967                        Some(Rc::from(name.as_str())),
1968                    ));
1969                }
1970                Ok(Filter::Format(Rc::from(name.as_str())))
1971            }
1972            Some(Tok::Var(name)) => {
1973                self.i += 1;
1974                if let Some(loc) = loc_literal(&name) {
1975                    return Ok(Filter::Lit(loc));
1976                }
1977                Ok(Filter::Var(Rc::from(name.as_str())))
1978            }
1979            Some(Tok::Op("(")) => {
1980                self.i += 1;
1981                let inner = self.pipe()?;
1982                self.want_op(")")?;
1983                Ok(inner)
1984            }
1985            Some(Tok::Op("[")) => {
1986                self.i += 1;
1987                if self.eat_op("]") {
1988                    return Ok(Filter::Array(None));
1989                }
1990                let inner = self.pipe()?;
1991                self.want_op("]")?;
1992                Ok(Filter::Array(Some(Box::new(inner))))
1993            }
1994            Some(Tok::Op("{")) => {
1995                self.i += 1;
1996                self.object_cons()
1997            }
1998            Some(Tok::Ident(name)) => self.ident_term(&name),
1999            Some(t) => Err(format!(
2000                "jq: unexpected `{}`",
2001                match t {
2002                    Tok::Op(o) => o.to_string(),
2003                    other => format!("{other:?}"),
2004                }
2005            )),
2006        }
2007    }
2008
2009    fn ident_term(&mut self, name: &str) -> Result<Filter, String> {
2010        match name {
2011            "if" => {
2012                self.i += 1;
2013                let mut arms = Vec::new();
2014                loop {
2015                    let cond = self.pipe()?;
2016                    self.want_kw("then")?;
2017                    let then = self.pipe()?;
2018                    arms.push((cond, then));
2019                    if self.eat_kw("elif") {
2020                        continue;
2021                    }
2022                    break;
2023                }
2024                let els = if self.eat_kw("else") {
2025                    let e = self.pipe()?;
2026                    Some(Box::new(e))
2027                } else {
2028                    None
2029                };
2030                self.want_kw("end")?;
2031                Ok(Filter::If(arms, els))
2032            }
2033            "try" => {
2034                self.i += 1;
2035                // parser.y: `"try" Expr "catch" Expr`, with `"try"`/`"catch"`
2036                // binding tighter than every binary operator, so each side
2037                // reduces to one Term — and `'-' Term` is a Term, so
2038                // `try -. catch .` negates inside the try.
2039                let body = self.unary()?;
2040                let handler = if self.eat_kw("catch") {
2041                    Some(Box::new(self.unary()?))
2042                } else {
2043                    None
2044                };
2045                Ok(Filter::Try(Box::new(body), handler))
2046            }
2047            "reduce" | "foreach" => {
2048                let is_reduce = name == "reduce";
2049                self.i += 1;
2050                // `"reduce" Expr "as" Patterns …`: the source runs up to `as`.
2051                let src = self.alt()?;
2052                self.want_kw("as")?;
2053                let pat = self.pattern()?;
2054                self.want_op("(")?;
2055                let init = self.pipe()?;
2056                self.want_op(";")?;
2057                let update = self.pipe()?;
2058                let extract = if self.eat_op(";") {
2059                    Some(Box::new(self.pipe()?))
2060                } else {
2061                    None
2062                };
2063                self.want_op(")")?;
2064                if is_reduce {
2065                    Ok(Filter::Reduce(
2066                        Box::new(src),
2067                        pat,
2068                        Box::new(init),
2069                        Box::new(update),
2070                    ))
2071                } else {
2072                    Ok(Filter::Foreach(
2073                        Box::new(src),
2074                        pat,
2075                        Box::new(init),
2076                        Box::new(update),
2077                        extract,
2078                    ))
2079                }
2080            }
2081            "label" => {
2082                self.i += 1;
2083                let lbl = self.var()?;
2084                self.want_op("|")?;
2085                let body = self.pipe()?;
2086                Ok(Filter::Label(lbl, Box::new(body)))
2087            }
2088            "break" => {
2089                self.i += 1;
2090                let lbl = self.var()?;
2091                Ok(Filter::Break(lbl))
2092            }
2093            "def" => {
2094                let def = self.funcdef()?;
2095                let rest = self.pipe()?;
2096                Ok(Filter::Def(Rc::new(def), Box::new(rest)))
2097            }
2098            "true" => {
2099                self.i += 1;
2100                Ok(Filter::Lit(JqVal::Bool(true)))
2101            }
2102            "false" => {
2103                self.i += 1;
2104                Ok(Filter::Lit(JqVal::Bool(false)))
2105            }
2106            "null" => {
2107                self.i += 1;
2108                Ok(Filter::Lit(JqVal::Null))
2109            }
2110            _ => {
2111                self.i += 1;
2112                let mut args = Vec::new();
2113                if self.eat_op("(") {
2114                    loop {
2115                        args.push(Rc::new(self.pipe()?));
2116                        if self.eat_op(";") {
2117                            continue;
2118                        }
2119                        self.want_op(")")?;
2120                        break;
2121                    }
2122                }
2123                Ok(Filter::Call(Rc::from(name), args))
2124            }
2125        }
2126    }
2127
2128    /// `{ … }` construction. Entries are `k: v`, `"k": v`, `(e): v`, `$v`,
2129    /// `k` (shorthand for `k: .k`), `@fmt "…"`, and `$__loc__`.
2130    fn object_cons(&mut self) -> Result<Filter, String> {
2131        let mut entries = Vec::new();
2132        if self.eat_op("}") {
2133            return Ok(Filter::Object(entries));
2134        }
2135        loop {
2136            let (key, default): (Filter, Option<Filter>) = match self.peek().cloned() {
2137                Some(Tok::Ident(k)) => {
2138                    self.i += 1;
2139                    (
2140                        Filter::Lit(JqVal::str(k.clone())),
2141                        Some(Filter::Field(
2142                            Box::new(Filter::Identity),
2143                            Rc::from(k.as_str()),
2144                        )),
2145                    )
2146                }
2147                // parser.y: `BINDING ':' DictExpr` keys by the variable's
2148                // VALUE (LOADV); a bare `BINDING` keys by its name.
2149                Some(Tok::Var(v)) => {
2150                    self.i += 1;
2151                    // `{$__loc__}` is `{"__loc__": $__loc__}`. The lexer tagged
2152                    // the token with its line (`__loc__:N`), so the key is the
2153                    // bare name and the value is the located literal.
2154                    let var = match loc_literal(&v) {
2155                        Some(loc) => Filter::Lit(loc),
2156                        None => Filter::Var(Rc::from(v.as_str())),
2157                    };
2158                    let v = if v.starts_with("__loc__:") {
2159                        "__loc__".to_string()
2160                    } else {
2161                        v
2162                    };
2163                    if self.is_op(":") {
2164                        (var, None)
2165                    } else {
2166                        (Filter::Lit(JqVal::str(v.clone())), Some(var))
2167                    }
2168                }
2169                Some(Tok::Str(pieces)) => {
2170                    self.i += 1;
2171                    let key = Filter::Str(pieces.into_iter().map(Into::into).collect(), None);
2172                    (
2173                        key.clone(),
2174                        Some(Filter::Index(Box::new(Filter::Identity), Box::new(key))),
2175                    )
2176                }
2177                Some(Tok::Format(name)) => {
2178                    self.i += 1;
2179                    match self.peek().cloned() {
2180                        Some(Tok::Str(pieces)) => {
2181                            self.i += 1;
2182                            let key = Filter::Str(
2183                                pieces.into_iter().map(Into::into).collect(),
2184                                Some(Rc::from(name.as_str())),
2185                            );
2186                            (key.clone(), None)
2187                        }
2188                        _ => return Err("jq: `@fmt` in an object key needs a string".into()),
2189                    }
2190                }
2191                Some(Tok::Op("(")) => {
2192                    self.i += 1;
2193                    let k = self.pipe()?;
2194                    self.want_op(")")?;
2195                    (k, None)
2196                }
2197                _ => return Err(format!("jq: bad object key `{}`", self.describe(self.i))),
2198            };
2199            let val = if self.eat_op(":") {
2200                // An object VALUE binds tighter than `,` (which separates
2201                // entries) but may still be a `|` pipeline via parens. jq uses
2202                // `ExpD`, an alternation of `|`-joined non-comma terms.
2203                self.obj_val()?
2204            } else {
2205                default.ok_or_else(|| "jq: object entry needs a `: value`".to_string())?
2206            };
2207            entries.push(ObjEntry::KeyVal(key, val));
2208            // `DictPair ',' DictPairs`, where DictPairs may be empty: a trailing
2209            // comma is legal (`{a: 1,}`), a leading or doubled one is not.
2210            if self.eat_op(",") {
2211                if self.eat_op("}") {
2212                    return Ok(Filter::Object(entries));
2213                }
2214                continue;
2215            }
2216            self.want_op("}")?;
2217            return Ok(Filter::Object(entries));
2218        }
2219    }
2220
2221    /// An object entry's value: `|`-joined, but never `,`-joined — the comma at
2222    /// this level separates entries.
2223    fn obj_val(&mut self) -> Result<Filter, String> {
2224        let mut lhs = self.alt()?;
2225        while self.eat_op("|") {
2226            let rhs = self.alt()?;
2227            lhs = Filter::Pipe(Box::new(lhs), Box::new(rhs));
2228        }
2229        Ok(lhs)
2230    }
2231}
2232
2233// ─────────────────────────────────────────────────────────────────────────────
2234// Environment
2235// ─────────────────────────────────────────────────────────────────────────────
2236
2237struct VarNode {
2238    name: Rc<str>,
2239    val: JqVal,
2240    next: Option<Rc<VarNode>>,
2241}
2242
2243/// A function binding. The node also carries the environment it was DEFINED in,
2244/// which is what makes closures work; a user function's body additionally sees
2245/// the node itself, so recursion needs no fixed point.
2246struct FuncNode {
2247    name: Rc<str>,
2248    arity: usize,
2249    kind: FnKind,
2250    next: Option<Rc<FuncNode>>,
2251    vars: Option<Rc<VarNode>>,
2252}
2253
2254enum FnKind {
2255    User(Rc<FuncDef>),
2256    /// A closure passed as a function argument: the caller's filter, evaluated
2257    /// in the caller's environment.
2258    Arg(Rc<Filter>, Env),
2259}
2260
2261#[derive(Clone, Default)]
2262struct Env {
2263    vars: Option<Rc<VarNode>>,
2264    funcs: Option<Rc<FuncNode>>,
2265}
2266
2267impl Env {
2268    fn bind(&self, name: Rc<str>, val: JqVal) -> Env {
2269        Env {
2270            vars: Some(Rc::new(VarNode {
2271                name,
2272                val,
2273                next: self.vars.clone(),
2274            })),
2275            funcs: self.funcs.clone(),
2276        }
2277    }
2278    fn lookup(&self, name: &str) -> Option<&JqVal> {
2279        let mut cur = self.vars.as_ref();
2280        while let Some(n) = cur {
2281            if &*n.name == name {
2282                return Some(&n.val);
2283            }
2284            cur = n.next.as_ref();
2285        }
2286        None
2287    }
2288    fn define(&self, def: Rc<FuncDef>) -> Env {
2289        Env {
2290            vars: self.vars.clone(),
2291            funcs: Some(Rc::new(FuncNode {
2292                name: def.name.clone(),
2293                arity: def.params.len(),
2294                kind: FnKind::User(def),
2295                next: self.funcs.clone(),
2296                vars: self.vars.clone(),
2297            })),
2298        }
2299    }
2300    fn find_fn(&self, name: &str, arity: usize) -> Option<Rc<FuncNode>> {
2301        let mut cur = self.funcs.clone();
2302        while let Some(n) = cur {
2303            if &*n.name == name && n.arity == arity {
2304                return Some(n);
2305            }
2306            cur = n.next.clone();
2307        }
2308        None
2309    }
2310}
2311
2312// ─────────────────────────────────────────────────────────────────────────────
2313// Interpreter
2314// ─────────────────────────────────────────────────────────────────────────────
2315
2316/// A jq program compiled once and runnable over many inputs.
2317pub struct Program {
2318    filter: Filter,
2319    base: Env,
2320}
2321
2322/// Per-run state: the `input`/`inputs` queue and the label counter.
2323pub struct Interp {
2324    labels: std::cell::Cell<u64>,
2325    /// The documents `.`, `input` and `inputs` all draw from, held as RAW TEXT
2326    /// and parsed on the way out. jq's model is one shared cursor over the input
2327    /// stream: the next document is `.`, and `input` takes the one after it, so
2328    /// a document consumed by `input` is not seen again by the outer loop.
2329    ///
2330    /// Raw rather than pre-parsed because most programs never call `input`, and
2331    /// parsing a whole stream up front to serve a builtin nobody used is the same
2332    /// cost as running the query twice.
2333    inputs: RefCell<std::collections::VecDeque<String>>,
2334    env_obj: RefCell<Option<JqVal>>,
2335    /// The document currently being evaluated, which is what `parent` walks. Set
2336    /// per input by the pipeline; `None` when nothing set it, and `parent` then
2337    /// answers `null` rather than guessing.
2338    doc: RefCell<Option<JqVal>>,
2339    /// What `input_line_number` reports: how many input lines have been taken,
2340    /// which is what jq reports while reading a line-per-document stream.
2341    line: std::cell::Cell<f64>,
2342}
2343
2344impl Default for Interp {
2345    fn default() -> Self {
2346        Interp {
2347            labels: std::cell::Cell::new(0),
2348            inputs: RefCell::new(std::collections::VecDeque::new()),
2349            env_obj: RefCell::new(None),
2350            doc: RefCell::new(None),
2351            line: std::cell::Cell::new(0.0),
2352        }
2353    }
2354}
2355
2356impl Interp {
2357    /// Enter a label: GENLABEL's `jq->next_label++`, first label `0`.
2358    fn next_label(&self) -> u64 {
2359        let id = self.labels.get();
2360        self.labels.set(id + 1);
2361        id
2362    }
2363
2364    /// Seed the document queue from the raw input lines.
2365    pub fn set_input_lines(&self, lines: Vec<String>) {
2366        *self.inputs.borrow_mut() = lines.into();
2367    }
2368
2369    /// Take the next document, or `None` at end of stream. A line that is not
2370    /// JSON is jq's STRING — the reading SPEC §8 gives a text line.
2371    ///
2372    /// Taking a line advances `input_line_number`, whoever takes it: jq's count
2373    /// is the parser's position, so `input` moves it too (`[., input,
2374    /// input_line_number]` over `1`, `2` is `[1,2,2]`).
2375    pub fn next_input(&self) -> Option<JqVal> {
2376        let line = self.inputs.borrow_mut().pop_front()?;
2377        self.line.set(self.line.get() + 1.0);
2378        Some(parse_json(&line).unwrap_or_else(|_| JqVal::str(line.as_str())))
2379    }
2380    /// Set what `input_line_number` reports for the value about to be run, or
2381    /// (before the first `next_input`) how many lines precede this batch.
2382    pub fn set_line(&self, n: usize) {
2383        self.line.set(n as f64);
2384    }
2385    /// Record the document about to be evaluated, so `parent` can walk it.
2386    pub fn set_doc(&self, v: &JqVal) {
2387        *self.doc.borrow_mut() = Some(v.clone());
2388    }
2389    fn current_doc(&self) -> Option<JqVal> {
2390        self.doc.borrow().clone()
2391    }
2392    fn env_object(&self) -> JqVal {
2393        if let Some(v) = self.env_obj.borrow().as_ref() {
2394            return v.clone();
2395        }
2396        let v = JqVal::obj(
2397            std::env::vars()
2398                .map(|(k, val)| (Rc::from(k.as_str()), JqVal::str(val)))
2399                .collect(),
2400        );
2401        *self.env_obj.borrow_mut() = Some(v.clone());
2402        v
2403    }
2404}
2405
2406/// An error raised by the DOWNSTREAM sink rather than by the filter being
2407/// evaluated. `try`/`?`/`//` must not swallow it — `[.[] | try error] ` catches
2408/// its own error, but a failure while writing the result is not the filter's.
2409/// Wrapping happens exactly at the boundaries that catch, so it never escapes.
2410fn wrap_downstream(e: JqErr) -> JqErr {
2411    match e {
2412        JqErr::Err(v) => JqErr::Err(JqVal::arr(vec![JqVal::str(DOWNSTREAM_TAG), v])),
2413        // A `break` raised downstream is an error raised downstream (TRY_END
2414        // wraps it like any other), so it is wrapped as the error it is.
2415        JqErr::Break(id) => JqErr::Err(JqVal::arr(vec![
2416            JqVal::str(DOWNSTREAM_TAG),
2417            label_value(id),
2418        ])),
2419        other => other,
2420    }
2421}
2422
2423/// The value jq's GENLABEL pushes for a label: `{"__jq": n}`, `n` counting the
2424/// labels entered so far in this run (`jq->next_label++`, reset only by
2425/// `jq_init`, so it keeps counting across input documents).
2426fn label_value(id: u64) -> JqVal {
2427    JqVal::obj(vec![(Rc::from("__jq"), JqVal::num(id as f64))])
2428}
2429
2430/// Whether `e` ends the label numbered `id`. jq's `label $l | body` is
2431/// `try body catch if . == $l then empty else error end` (`gen_label`), so it
2432/// stops on the `break` itself and equally on any error whose payload equals
2433/// the label value — a `try … catch error` that caught the break and re-raised.
2434fn breaks_to(e: &JqErr, id: u64) -> bool {
2435    match e {
2436        JqErr::Break(b) => *b == id,
2437        JqErr::Err(v) => eq_vals(v, &label_value(id)),
2438        JqErr::Halt(..) => false,
2439    }
2440}
2441
2442/// What a `try`/`?` catches from its body: an error's payload, or a `break`'s
2443/// label value (the error `break` raises in jq). `halt` is not catchable.
2444fn caught_payload(e: JqErr) -> Result<JqVal, JqErr> {
2445    match e {
2446        JqErr::Err(v) => Ok(v),
2447        JqErr::Break(id) => Ok(label_value(id)),
2448        halt @ JqErr::Halt(..) => Err(halt),
2449    }
2450}
2451
2452const DOWNSTREAM_TAG: &str = "\u{1}jqlang-downstream";
2453
2454/// Undo [`wrap_downstream`], or `None` when the error was raised by the filter.
2455fn unwrap_downstream(e: JqErr) -> Result<JqErr, JqErr> {
2456    if let JqErr::Err(JqVal::Arr(a)) = &e {
2457        if a.len() == 2 {
2458            if let JqVal::Str(tag) = &a[0] {
2459                if &**tag == DOWNSTREAM_TAG {
2460                    return Ok(JqErr::Err(a[1].clone()));
2461                }
2462            }
2463        }
2464    }
2465    Err(e)
2466}
2467
2468impl Program {
2469    /// Compile a jq program. The prelude (jq's own `builtin.jq` definitions) is
2470    /// parsed once per process and shared.
2471    pub fn compile(src: &str) -> Result<Program, String> {
2472        let filter = parse(src)?;
2473        let base = prelude_env();
2474        // jq resolves names at COMPILE time — `jq 'bogus'` is a compile error
2475        // (exit 3), not a runtime one. Checking here keeps that, and it is what
2476        // lets arb still report `unknown verb` for a typo'd arb verb instead of
2477        // silently accepting it as a jq program that fails later.
2478        let mut funcs: std::collections::HashSet<String> = builtin_names().into_iter().collect();
2479        funcs.extend(NATIVE_ONLY.iter().map(|s| (*s).to_string()));
2480        let vars: std::collections::HashSet<String> = ["ENV", "__loc__"]
2481            .iter()
2482            .map(|s| (*s).to_string())
2483            .collect();
2484        check_names(&filter, &funcs, &vars)?;
2485        Ok(Program { filter, base })
2486    }
2487
2488    /// Does this program read from the input STREAM (`input` / `inputs`)?
2489    ///
2490    /// A program that does not is per-line, and arb's pipeline can stream it —
2491    /// emitting as lines arrive instead of buffering to EOF. One that does needs
2492    /// the whole stream in hand by construction. Conservative in the safe
2493    /// direction: a user `def input:` that shadows the builtin still reports
2494    /// `true`, which costs streaming and never correctness.
2495    pub fn reads_input_stream(&self) -> bool {
2496        fn walk(f: &Filter) -> bool {
2497            let mut hit = false;
2498            for_each_child(f, &mut |c| hit |= walk(c));
2499            if let Filter::Call(name, args) = f {
2500                if args.is_empty() && matches!(&**name, "input" | "inputs") {
2501                    return true;
2502                }
2503            }
2504            hit
2505        }
2506        walk(&self.filter)
2507    }
2508
2509    /// Run the program over one input, collecting every output value.
2510    pub fn run(&self, interp: &Interp, input: &JqVal) -> R<Vec<JqVal>> {
2511        let mut out = Vec::new();
2512        self.run_with(interp, input, &mut |v| {
2513            out.push(v);
2514            Ok(())
2515        })?;
2516        Ok(out)
2517    }
2518
2519    /// Run the program over one input, streaming each output to `sink`.
2520    pub fn run_with(&self, interp: &Interp, input: &JqVal, sink: Sink) -> R<()> {
2521        eval(interp, &self.filter, input, &self.base, sink)
2522    }
2523}
2524
2525/// Evaluate `f` against `input`, sending every output value to `out`.
2526fn eval(it: &Interp, f: &Filter, input: &JqVal, env: &Env, out: Sink) -> R<()> {
2527    match f {
2528        Filter::Identity => out(input.clone()),
2529        Filter::RecurseDefault => recurse_all(input, out),
2530        Filter::Lit(v) => out(v.clone()),
2531        Filter::Str(pieces, fmt) => eval_string(it, pieces, fmt.as_deref(), input, env, out),
2532        Filter::Format(name) if &**name == "text" => out(to_string_val(input)),
2533        Filter::Format(name) => out(JqVal::str(apply_format(name, input)?)),
2534        Filter::Field(..) | Filter::Index(..) | Filter::Slice(..) | Filter::Iterate(..) => {
2535            eval_index(it, f, false, input, env, out)
2536        }
2537        Filter::IndexOpt(inner) => eval_index(it, inner, true, input, env, out),
2538        Filter::Optional(inner) => {
2539            match eval(it, inner, input, env, &mut |v| {
2540                out(v).map_err(wrap_downstream)
2541            }) {
2542                Ok(()) => Ok(()),
2543                Err(e) => match unwrap_downstream(e) {
2544                    Ok(real) => Err(real),
2545                    Err(caught) => caught_payload(caught).map(drop),
2546                },
2547            }
2548        }
2549        Filter::Pipe(a, b) => eval(it, a, input, env, &mut |v| eval(it, b, &v, env, out)),
2550        Filter::Comma(a, b) => {
2551            eval(it, a, input, env, out)?;
2552            eval(it, b, input, env, out)
2553        }
2554        Filter::Neg(inner) => eval(it, inner, input, env, &mut |v| match v.bare() {
2555            JqVal::Num(n, lit) => out(negate_num(*n, lit)),
2556            other => Err(JqErr::msg(format!(
2557                "{}{} cannot be negated",
2558                other.type_name(),
2559                paren_of(other)
2560            ))),
2561        }),
2562        // jq evaluates a binary operator's RIGHT side in the outer loop: for
2563        // `(1,2) as the left and (10,20) as the right`, the emitted order is
2564        // 11,12,21,22 — the right value varies slowest.
2565        Filter::Bin(op, a, b) => eval(it, b, input, env, &mut |rv| {
2566            eval(it, a, input, env, &mut |lv| out(binop(*op, &lv, &rv)?))
2567        }),
2568        Filter::And(a, b) => eval(it, a, input, env, &mut |lv| {
2569            if !lv.truthy() {
2570                return out(JqVal::Bool(false));
2571            }
2572            eval(it, b, input, env, &mut |rv| out(JqVal::Bool(rv.truthy())))
2573        }),
2574        Filter::Or(a, b) => eval(it, a, input, env, &mut |lv| {
2575            if lv.truthy() {
2576                return out(JqVal::Bool(true));
2577            }
2578            eval(it, b, input, env, &mut |rv| out(JqVal::Bool(rv.truthy())))
2579        }),
2580        // `a // b`: every TRUTHY output of `a`; only if there were none does
2581        // `b` run. An error raised by `a` PROPAGATES — jq 1.8 does not suppress
2582        // it (`1 | .a // 3` is "Cannot index number", not `3`); `(a)? // b` is
2583        // how a program asks for suppression.
2584        Filter::Alt(a, b) => {
2585            let mut any = false;
2586            eval(it, a, input, env, &mut |v| {
2587                if v.truthy() {
2588                    any = true;
2589                    out(v)
2590                } else {
2591                    Ok(())
2592                }
2593            })?;
2594            if any {
2595                Ok(())
2596            } else {
2597                eval(it, b, input, env, out)
2598            }
2599        }
2600        Filter::If(arms, els) => eval_if(it, arms, els.as_deref(), 0, input, env, out),
2601        Filter::Try(body, handler) => {
2602            match eval(it, body, input, env, &mut |v| {
2603                out(v).map_err(wrap_downstream)
2604            }) {
2605                Ok(()) => Ok(()),
2606                Err(e) => match unwrap_downstream(e) {
2607                    Ok(real) => Err(real),
2608                    Err(caught) => {
2609                        let payload = caught_payload(caught)?;
2610                        match handler {
2611                            Some(h) => eval(it, h, &payload, env, out),
2612                            None => Ok(()),
2613                        }
2614                    }
2615                },
2616            }
2617        }
2618        Filter::Reduce(src, pat, init, update) => {
2619            // jq 1.8's `reduce` moves `.` into its loop (`DUPN`), leaving `null`
2620            // behind, so a SECOND pass — a later output of `init`, or the next
2621            // alternative of a `?//` in it — runs its source over `null`:
2622            // `[3] | [reduce .[] as $x ((1, 2); . + $x)]` refuses to iterate
2623            // `null`.
2624            let mut pass = 0usize;
2625            eval(it, init, input, env, &mut |init_v| {
2626                let dot = if pass == 0 { input } else { &JqVal::Null };
2627                pass += 1;
2628                let mut acc = init_v;
2629                eval(it, src, dot, env, &mut |item| {
2630                    bind_pattern(it, pat, &item, env, None, &mut |benv, _| {
2631                        let mut last = None;
2632                        eval(it, update, &acc, &benv, &mut |v| {
2633                            last = Some(v);
2634                            Ok(())
2635                        })?;
2636                        // An update that yields nothing collapses the accumulator to
2637                        // null, which is what jq 1.7+ does (`reduce (1) as $x (0;
2638                        // empty)` is `null`).
2639                        acc = last.unwrap_or(JqVal::Null);
2640                        Ok(())
2641                    })
2642                })?;
2643                out(acc.clone())
2644            })
2645        }
2646        Filter::Foreach(src, pat, init, update, extract) => {
2647            eval(it, init, input, env, &mut |init_v| {
2648                let mut acc = init_v;
2649                eval(it, src, input, env, &mut |item| {
2650                    bind_pattern(it, pat, &item, env, None, &mut |benv, _| {
2651                        let mut states = Vec::new();
2652                        eval(it, update, &acc, &benv, &mut |v| {
2653                            states.push(v);
2654                            Ok(())
2655                        })?;
2656                        // As in `reduce`, an update that yields nothing leaves `null`
2657                        // behind as the state (jq 1.8: `[foreach (1,2,3) as $x (0;
2658                        // if $x == 2 then empty else . + $x end)]` is `[1,3]`).
2659                        if states.is_empty() {
2660                            acc = JqVal::Null;
2661                        }
2662                        for st in states {
2663                            acc = st.clone();
2664                            match extract {
2665                                Some(e) => eval(it, e, &st, &benv, out)?,
2666                                None => out(st)?,
2667                            }
2668                        }
2669                        Ok(())
2670                    })
2671                })
2672            })
2673        }
2674        Filter::Bind(src, pats, body) => eval(it, src, input, env, &mut |v| {
2675            bind_alternatives(it, pats, &v, env, None, &mut |benv, _| {
2676                eval(it, body, input, &benv, out)
2677            })
2678        }),
2679        Filter::Label(name, body) => {
2680            let id = it.next_label();
2681            let benv = env.bind(label_key(name), JqVal::num(id as f64));
2682            match eval(it, body, input, &benv, &mut |v| {
2683                out(v).map_err(wrap_downstream)
2684            }) {
2685                Err(e) if breaks_to(&e, id) => Ok(()),
2686                Err(e) => match unwrap_downstream(e) {
2687                    Ok(real) => Err(real),
2688                    Err(other) => Err(other),
2689                },
2690                Ok(()) => Ok(()),
2691            }
2692        }
2693        Filter::Break(name) => match env.lookup(&label_key(name)) {
2694            Some(JqVal::Num(id, _)) => Err(JqErr::Break(*id as u64)),
2695            _ => Err(JqErr::msg(format!("$*label-{name} is not defined"))),
2696        },
2697        Filter::Var(name) => match &**name {
2698            "ENV" => out(it.env_object()),
2699            "__loc__" => out(JqVal::obj(vec![
2700                (Rc::from("file"), JqVal::str("<top-level>")),
2701                (Rc::from("line"), JqVal::num(1.0)),
2702            ])),
2703            _ => match env.lookup(name) {
2704                Some(v) => out(v.clone()),
2705                None => Err(JqErr::msg(format!("${name} is not defined"))),
2706            },
2707        },
2708        Filter::Def(def, rest) => {
2709            let inner = env.define(def.clone());
2710            eval(it, rest, input, &inner, out)
2711        }
2712        Filter::Call(name, args) => eval_call(it, name, args, input, env, out),
2713        Filter::Object(entries) => build_object(it, entries, 0, Vec::new(), input, env, out),
2714        Filter::Array(inner) => {
2715            let mut items = Vec::new();
2716            if let Some(f) = inner {
2717                eval(it, f, input, env, &mut |v| {
2718                    items.push(v);
2719                    Ok(())
2720                })?;
2721            }
2722            out(JqVal::arr(items))
2723        }
2724        Filter::Assign(op, lhs, rhs) => eval_assign(it, *op, lhs, rhs, input, env, out),
2725    }
2726}
2727
2728/// One index step — `.k`, `.[e]`, `.[a:b]` or `.[]` — over every output of its
2729/// base. Under `opt` (parser.y's INDEX_OPT/EACH_OPT, the `?` written right
2730/// after the step) the step's OWN error yields nothing; an error from the
2731/// base, from the key, or from downstream still propagates.
2732fn eval_index(it: &Interp, f: &Filter, opt: bool, input: &JqVal, env: &Env, out: Sink) -> R<()> {
2733    let step = |r: R<JqVal>, out: Sink| match r {
2734        Ok(v) => out(v),
2735        Err(_) if opt => Ok(()),
2736        Err(e) => Err(e),
2737    };
2738    match f {
2739        Filter::Field(base, name) => eval(it, base, input, env, &mut |v| {
2740            step(index_value(&v, &JqVal::Str(name.clone())), out)
2741        }),
2742        // jq compiles `T[E]` as the index/bounds first and the term LAST (gen_index,
2743        // gen_slice_index), so a generator in the index is the OUTER loop and the
2744        // term varies fastest: `[[1,2],[3,4]] | [.[][0,1]]` is `[1,3,2,4]`.
2745        Filter::Index(base, idx) => eval(it, idx, input, env, &mut |i| {
2746            eval(it, base, input, env, &mut |v| {
2747                step(index_value(&v, &i), out)
2748            })
2749        }),
2750        Filter::Slice(base, lo, hi) => eval_opt(it, lo.as_deref(), input, env, &mut |lo_v| {
2751            eval_opt(it, hi.as_deref(), input, env, &mut |hi_v| {
2752                eval(it, base, input, env, &mut |v| {
2753                    step(slice_value(&v, &lo_v, &hi_v), out)
2754                })
2755            })
2756        }),
2757        Filter::Iterate(base) => eval(it, base, input, env, &mut |v| match v.bare() {
2758            JqVal::Arr(a) => {
2759                for e in a.iter() {
2760                    out(e.clone())?;
2761                }
2762                Ok(())
2763            }
2764            JqVal::Obj(m) => {
2765                for (_, val) in m.iter() {
2766                    out(val.clone())?;
2767                }
2768                Ok(())
2769            }
2770            _ if opt => Ok(()),
2771            other => Err(JqErr::msg(format!(
2772                "Cannot iterate over {}{}",
2773                other.type_name(),
2774                paren_of(other)
2775            ))),
2776        }),
2777        other => unreachable!("not an index step: {other:?}"),
2778    }
2779}
2780
2781/// The `(value)` suffix jq appends to a type in an error message.
2782pub(crate) fn paren_of(v: &JqVal) -> String {
2783    format!(" ({})", dump_trunc(v))
2784}
2785
2786/// A port of `jv_dump_string_trunc` (src/jv_print.c) with the 30-byte buffer
2787/// every error message uses. A dump of 30 BYTES or more keeps its first 25
2788/// (26 when it does not open with `"`, `[` or `{`), backed up to the start of
2789/// the UTF-8 character that byte falls in, then `...` and the closing delimiter.
2790pub(crate) fn dump_trunc(v: &JqVal) -> String {
2791    const BUFSIZE: usize = 30;
2792    let s = render(v.bare());
2793    if s.len() < BUFSIZE {
2794        return s;
2795    }
2796    let delim = match s.as_bytes()[0] {
2797        b'"' => Some('"'),
2798        b'[' => Some(']'),
2799        b'{' => Some('}'),
2800        _ => None,
2801    };
2802    let mut l = BUFSIZE - if delim.is_some() { 5 } else { 4 };
2803    while !s.is_char_boundary(l) {
2804        l -= 1;
2805    }
2806    let mut out = format!("{}...", &s[..l]);
2807    out.extend(delim);
2808    out
2809}
2810
2811fn label_key(name: &str) -> Rc<str> {
2812    Rc::from(format!("*label*{name}").as_str())
2813}
2814
2815fn eval_opt(it: &Interp, f: Option<&Filter>, input: &JqVal, env: &Env, out: Sink) -> R<()> {
2816    match f {
2817        Some(f) => eval(it, f, input, env, out),
2818        None => out(JqVal::Null),
2819    }
2820}
2821
2822fn eval_if(
2823    it: &Interp,
2824    arms: &[(Filter, Filter)],
2825    els: Option<&Filter>,
2826    i: usize,
2827    input: &JqVal,
2828    env: &Env,
2829    out: Sink,
2830) -> R<()> {
2831    let Some((cond, then)) = arms.get(i) else {
2832        // No arm matched: an absent `else` is the identity in jq 1.7+.
2833        return match els {
2834            Some(e) => eval(it, e, input, env, out),
2835            None => out(input.clone()),
2836        };
2837    };
2838    eval(it, cond, input, env, &mut |c| {
2839        if c.truthy() {
2840            eval(it, then, input, env, out)
2841        } else {
2842            eval_if(it, arms, els, i + 1, input, env, out)
2843        }
2844    })
2845}
2846
2847/// jq's `..`: the value itself, then every descendant, depth first.
2848fn recurse_all(v: &JqVal, out: Sink) -> R<()> {
2849    // The NODE is what comes out — `.. | anchor` has to see the box — while the
2850    // traversal walks the value inside it.
2851    out(v.clone())?;
2852    match v.bare() {
2853        JqVal::Arr(a) => {
2854            for e in a.iter() {
2855                recurse_all(e, out)?;
2856            }
2857            Ok(())
2858        }
2859        JqVal::Obj(m) => {
2860            for (_, val) in m.iter() {
2861                recurse_all(val, out)?;
2862            }
2863            Ok(())
2864        }
2865        _ => Ok(()),
2866    }
2867}
2868
2869// ─────────────────────────────────────────────────────────────────────────────
2870// Value operations
2871// ─────────────────────────────────────────────────────────────────────────────
2872
2873/// `v[idx]`. jq's rules: `null` indexes to `null` for both a key and an index, a
2874/// missing key or an out-of-range index is `null`, a negative array index counts
2875/// from the end, and every other type pairing is an error.
2876fn index_value(v: &JqVal, idx: &JqVal) -> R<JqVal> {
2877    // The CHILD keeps its box (that is how `.a | line_comment` reaches the
2878    // comment on `a`'s value); the container and the index are read unboxed.
2879    let (v, idx) = (v.bare(), idx.bare());
2880    match (v, idx) {
2881        // `jv_get`: `null` reads as `null` under a string, number or slice key
2882        // only; a null, boolean or array key refuses like any other.
2883        (JqVal::Null, JqVal::Str(_) | JqVal::Num(..)) => Ok(JqVal::Null),
2884        (JqVal::Obj(_), JqVal::Str(k)) => Ok(v.obj_get(k).cloned().unwrap_or(JqVal::Null)),
2885        (JqVal::Arr(a), JqVal::Num(n, _)) => {
2886            if !n.is_finite() {
2887                return Ok(JqVal::Null);
2888            }
2889            let i = n.trunc();
2890            let i = if i < 0.0 { i + a.len() as f64 } else { i };
2891            if i < 0.0 || i >= a.len() as f64 {
2892                Ok(JqVal::Null)
2893            } else {
2894                Ok(a[i as usize].clone())
2895            }
2896        }
2897        // `.[ {"start":s,"end":e} ]` is how jq spells a slice internally, and it
2898        // reaches `index` when the object form is written out. `jv_get` hands
2899        // ANY object key on an array or string to `parse_slice`, which reads only
2900        // `start` and `end` (extra keys are ignored, a missing one refuses), and
2901        // indexes `null` with an object to `null`.
2902        (JqVal::Null, JqVal::Obj(_)) => Ok(JqVal::Null),
2903        (JqVal::Arr(_) | JqVal::Str(_), JqVal::Obj(_)) => {
2904            let (s, e) = (idx.obj_get("start"), idx.obj_get("end"));
2905            match v {
2906                JqVal::Arr(a) => {
2907                    let (s, e) = slice_bounds(s, e, a.len())?;
2908                    Ok(JqVal::arr(a[s..e].to_vec()))
2909                }
2910                JqVal::Str(st) => {
2911                    let cs: Vec<char> = st.chars().collect();
2912                    let (s, e) = slice_bounds(s, e, cs.len())?;
2913                    Ok(JqVal::str(cs[s..e].iter().collect::<String>()))
2914                }
2915                _ => unreachable!("matched an array or a string above"),
2916            }
2917        }
2918        // `[a] | .[ [x] ]` is jq's "indices of the subarray" form.
2919        (JqVal::Arr(_), JqVal::Arr(sub)) => Ok(JqVal::arr(array_indices(v, sub))),
2920        _ => Err(index_err(v, idx)),
2921    }
2922}
2923
2924fn index_err(v: &JqVal, idx: &JqVal) -> JqErr {
2925    let key = idx.bare();
2926    JqErr::msg(format!(
2927        "Cannot index {} with {}{}",
2928        v.type_name(),
2929        key.type_name(),
2930        paren_of(key)
2931    ))
2932}
2933
2934/// Every start offset at which `sub` occurs inside array `hay`.
2935fn array_indices(hay: &JqVal, sub: &[JqVal]) -> Vec<JqVal> {
2936    let JqVal::Arr(a) = hay.bare() else {
2937        return Vec::new();
2938    };
2939    if sub.is_empty() || sub.len() > a.len() {
2940        return Vec::new();
2941    }
2942    (0..=a.len() - sub.len())
2943        .filter(|&i| {
2944            a[i..i + sub.len()]
2945                .iter()
2946                .zip(sub)
2947                .all(|(x, y)| eq_vals(x, y))
2948        })
2949        .map(|i| JqVal::num(i as f64))
2950        .collect()
2951}
2952
2953/// The `[start, end)` a slice `.[lo:hi]` of `len` items covers, as jq 1.8's
2954/// `parse_slice` computes it: a negative bound counts from the end, both are
2955/// clamped to `0..=len`, a fractional start is truncated and a fractional end
2956/// rounded UP (`[1,2,3,4,5] | .[1.2:3.5]` is `[2,3,4]`), and an end before the
2957/// start is the start. A `null` bound is open;
2958/// any other non-number is jq's "slice indices must be integers" error. Reading, assigning
2959/// and deleting a slice all go through here.
2960fn slice_bounds(lo: Option<&JqVal>, hi: Option<&JqVal>, len: usize) -> R<(usize, usize)> {
2961    // A port of `parse_slice` (src/jv_aux.c). A null bound is open; a MISSING
2962    // one (jq's INVALID) and any non-number refuse.
2963    let bound = |b: Option<&JqVal>, open: f64| match b.map(JqVal::bare) {
2964        Some(JqVal::Num(n, _)) => Ok(*n),
2965        Some(JqVal::Null) => Ok(open),
2966        _ => Err(JqErr::msg("Array/string slice indices must be integers")),
2967    };
2968    let lenf = len as f64;
2969    let (mut ds, mut de) = (bound(lo, 0.0)?, bound(hi, lenf)?);
2970    // The start rounds DOWN and a NaN start is 0.
2971    if ds.is_nan() {
2972        ds = 0.0;
2973    }
2974    if ds < 0.0 {
2975        ds += lenf;
2976    }
2977    let start = ds.clamp(0.0, lenf) as usize;
2978    // The end rounds UP and a NaN end is the length.
2979    if de.is_nan() {
2980        de = lenf;
2981    }
2982    if de < 0.0 {
2983        de += lenf;
2984    }
2985    if de < 0.0 {
2986        de = start as f64;
2987    }
2988    let mut end = (de.min(lenf)) as usize;
2989    if end < len && (end as f64) < de {
2990        end += 1;
2991    }
2992    Ok((start, end.max(start)))
2993}
2994
2995/// jq's slice: clamped, negative-from-the-end, over arrays and strings, with
2996/// `null` slicing to `null`.
2997fn slice_value(v: &JqVal, lo: &JqVal, hi: &JqVal) -> R<JqVal> {
2998    let bounds = |len: usize| slice_bounds(Some(lo), Some(hi), len);
2999    match v.bare() {
3000        JqVal::Null => Ok(JqVal::Null),
3001        JqVal::Arr(a) => {
3002            let (s, e) = bounds(a.len())?;
3003            Ok(JqVal::arr(a[s..e].to_vec()))
3004        }
3005        JqVal::Str(s) => {
3006            // jq slices a string by CODE POINT, not by byte.
3007            let cs: Vec<char> = s.chars().collect();
3008            let (a, b) = bounds(cs.len())?;
3009            Ok(JqVal::str(cs[a..b].iter().collect::<String>()))
3010        }
3011        other => {
3012            let key = JqVal::obj(vec![
3013                (Rc::from("start"), lo.clone()),
3014                (Rc::from("end"), hi.clone()),
3015            ]);
3016            Err(JqErr::msg(format!(
3017                "Cannot index {} with object{}",
3018                other.type_name(),
3019                paren_of(&key)
3020            )))
3021        }
3022    }
3023}
3024
3025fn binop(op: BinOp, a: &JqVal, b: &JqVal) -> R<JqVal> {
3026    // Arithmetic and comparison are about VALUES. `1 # a` + `2 # b` is 3, and
3027    // the result carries no comment because it is a new value, not either node —
3028    // which is also what yq answers.
3029    let (a, b) = (a.bare(), b.bare());
3030    match op {
3031        BinOp::Eq => return Ok(JqVal::Bool(eq_vals(a, b))),
3032        BinOp::Ne => return Ok(JqVal::Bool(!eq_vals(a, b))),
3033        BinOp::Lt => return Ok(JqVal::Bool(cmp_vals(a, b) == Ordering::Less)),
3034        BinOp::Le => return Ok(JqVal::Bool(cmp_vals(a, b) != Ordering::Greater)),
3035        BinOp::Gt => return Ok(JqVal::Bool(cmp_vals(a, b) == Ordering::Greater)),
3036        BinOp::Ge => return Ok(JqVal::Bool(cmp_vals(a, b) != Ordering::Less)),
3037        _ => {}
3038    }
3039    let bad = |verb: &str| {
3040        JqErr::msg(format!(
3041            "{}{} and {}{} cannot be {verb}",
3042            a.type_name(),
3043            paren_of(a),
3044            b.type_name(),
3045            paren_of(b)
3046        ))
3047    };
3048    match op {
3049        BinOp::Add => match (a, b) {
3050            // `null` is the identity of `+` on either side, which is what makes
3051            // `add` == `reduce .[] as $x (null; . + $x)` work on any element type.
3052            (JqVal::Null, x) | (x, JqVal::Null) => Ok(x.clone()),
3053            (JqVal::Num(x, _), JqVal::Num(y, _)) => Ok(JqVal::num(x + y)),
3054            (JqVal::Str(x), JqVal::Str(y)) => Ok(JqVal::str(format!("{x}{y}"))),
3055            (JqVal::Arr(x), JqVal::Arr(y)) => {
3056                let mut v = x.as_ref().clone();
3057                v.extend(y.iter().cloned());
3058                Ok(JqVal::arr(v))
3059            }
3060            (JqVal::Obj(x), JqVal::Obj(y)) => {
3061                let mut v = x.as_ref().clone();
3062                for (k, val) in y.iter() {
3063                    match v.iter_mut().find(|(ek, _)| ek == k) {
3064                        Some(slot) => slot.1 = val.clone(),
3065                        None => v.push((k.clone(), val.clone())),
3066                    }
3067                }
3068                Ok(JqVal::Obj(Rc::new(v)))
3069            }
3070            _ => Err(bad("added")),
3071        },
3072        BinOp::Sub => match (a, b) {
3073            (JqVal::Num(x, _), JqVal::Num(y, _)) => Ok(JqVal::num(x - y)),
3074            (JqVal::Arr(x), JqVal::Arr(y)) => Ok(JqVal::arr(
3075                x.iter()
3076                    .filter(|e| !y.iter().any(|d| eq_vals(e, d)))
3077                    .cloned()
3078                    .collect(),
3079            )),
3080            _ => Err(bad("subtracted")),
3081        },
3082        BinOp::Mul => match (a, b) {
3083            (JqVal::Num(x, _), JqVal::Num(y, _)) => Ok(JqVal::num(x * y)),
3084            (JqVal::Str(s), JqVal::Num(n, _)) | (JqVal::Num(n, _), JqVal::Str(s)) => {
3085                // jq 1.8.2: a negative or NaN count is `null`, otherwise the
3086                // count is truncated (`"ab" * 0.5` is `""`), and a result past
3087                // `INT_MAX` bytes is refused rather than allocated.
3088                if n.is_nan() || *n < 0.0 {
3089                    return Ok(JqVal::Null);
3090                }
3091                let times = *n as usize;
3092                if s.len().saturating_mul(times) > i32::MAX as usize {
3093                    return Err(JqErr::msg("Repeat string result too long"));
3094                }
3095                Ok(JqVal::str(s.repeat(times)))
3096            }
3097            (JqVal::Obj(_), JqVal::Obj(_)) => Ok(deep_merge(a, b)),
3098            _ => Err(bad("multiplied")),
3099        },
3100        BinOp::Div => match (a, b) {
3101            (JqVal::Num(_, _), JqVal::Num(y, _)) if *y == 0.0 => Err(JqErr::msg(format!(
3102                "{}{} and {}{} cannot be divided because the divisor is zero",
3103                a.type_name(),
3104                paren_of(a),
3105                b.type_name(),
3106                paren_of(b)
3107            ))),
3108            (JqVal::Num(x, _), JqVal::Num(y, _)) => Ok(JqVal::num(x / y)),
3109            (JqVal::Str(x), JqVal::Str(y)) => Ok(JqVal::arr(split_str(x, y))),
3110            _ => Err(bad("divided")),
3111        },
3112        BinOp::Mod => match (a, b) {
3113            // `binop_mod` (src/builtin.c) answers NaN when either side is NaN,
3114            // before the zero-divisor check that a NaN would otherwise trip.
3115            (JqVal::Num(x, _), JqVal::Num(y, _)) if x.is_nan() || y.is_nan() => {
3116                Ok(JqVal::num(f64::NAN))
3117            }
3118            (JqVal::Num(x, _), JqVal::Num(y, _)) => {
3119                // jq truncates BOTH operands to integers first, so `5.9 % 3` is
3120                // `2` and not the f64 remainder.
3121                let (xi, yi) = (trunc_i64(*x), trunc_i64(*y));
3122                if yi == 0 {
3123                    return Err(JqErr::msg(format!(
3124                        "{}{} and {}{} cannot be divided (remainder) because the divisor is zero",
3125                        a.type_name(),
3126                        paren_of(a),
3127                        b.type_name(),
3128                        paren_of(b)
3129                    )));
3130                }
3131                // jq special-cases a `-1` divisor to 0 so `INTMAX_MIN % -1` cannot
3132                // overflow; Rust's `%` panics there.
3133                Ok(JqVal::num(if yi == -1 { 0.0 } else { (xi % yi) as f64 }))
3134            }
3135            _ => Err(bad("divided (remainder)")),
3136        },
3137        _ => unreachable!("comparisons returned above"),
3138    }
3139}
3140
3141/// jq casts through `intmax_t` for `%`; a non-finite double has no such cast, so
3142/// it saturates rather than being undefined.
3143fn trunc_i64(v: f64) -> i64 {
3144    if v.is_nan() {
3145        0
3146    } else {
3147        v.trunc().clamp(i64::MIN as f64, i64::MAX as f64) as i64
3148    }
3149}
3150
3151/// `*` on two objects: recursive merge, with the RIGHT side winning at leaves.
3152fn deep_merge(a: &JqVal, b: &JqVal) -> JqVal {
3153    match (a.bare(), b.bare()) {
3154        (JqVal::Obj(x), JqVal::Obj(y)) => {
3155            let mut v = x.as_ref().clone();
3156            for (k, bv) in y.iter() {
3157                match v.iter_mut().find(|(ek, _)| ek == k) {
3158                    Some(slot) => slot.1 = deep_merge(&slot.1.clone(), bv),
3159                    None => v.push((k.clone(), bv.clone())),
3160                }
3161            }
3162            JqVal::Obj(Rc::new(v))
3163        }
3164        _ => b.clone(),
3165    }
3166}
3167
3168/// `"a,b" / ","`. An EMPTY separator splits nothing (jq returns the whole
3169/// string as one element), matching `jv_string_split`.
3170fn split_str(s: &str, sep: &str) -> Vec<JqVal> {
3171    if s.is_empty() {
3172        return Vec::new();
3173    }
3174    // An empty separator splits between every character, as jq 1.8 does
3175    // (`"ab" | split("")` is `["a","b"]`, and so is `"ab" / ""`).
3176    if sep.is_empty() {
3177        return s.chars().map(|c| JqVal::str(c.to_string())).collect();
3178    }
3179    s.split(sep).map(JqVal::str).collect()
3180}
3181
3182// ─────────────────────────────────────────────────────────────────────────────
3183// Strings, formats and object construction
3184// ─────────────────────────────────────────────────────────────────────────────
3185
3186/// Build an interpolated string. Each `\(…)` is a GENERATOR, so `"\(1,2)"`
3187/// yields two strings. jq compiles the pieces as a chain of `+` whose RIGHT
3188/// operand is evaluated outermost, so the RIGHTMOST interpolation varies
3189/// slowest: `"\(1,2)-\(3,4)"` is `1-3`, `2-3`, `1-4`, `2-4`. The pieces are
3190/// therefore walked right to left, each prepended to the suffix built so far.
3191/// Everything a string build carries unchanged from piece to piece.
3192struct StrBuild<'a> {
3193    it: &'a Interp,
3194    pieces: &'a [StrPiece],
3195    fmt: Option<&'a str>,
3196    input: &'a JqVal,
3197    env: &'a Env,
3198}
3199
3200fn eval_string(
3201    it: &Interp,
3202    pieces: &[StrPiece],
3203    fmt: Option<&str>,
3204    input: &JqVal,
3205    env: &Env,
3206    out: Sink,
3207) -> R<()> {
3208    fn go(b: &StrBuild, i: usize, acc: &str, out: Sink) -> R<()> {
3209        let Some(i) = i.checked_sub(1) else {
3210            return out(JqVal::str(acc));
3211        };
3212        match &b.pieces[i] {
3213            StrPiece::Lit(s) => {
3214                let next = format!("{s}{acc}");
3215                go(b, i, &next, out)
3216            }
3217            StrPiece::Interp(src) => {
3218                // The interpolation's source is parsed here rather than at lex
3219                // time so the lexer stays flat; the result is cached per program
3220                // run by the `Filter` the caller already holds.
3221                let f = parse(src).map_err(JqErr::msg)?;
3222                eval(b.it, &f, b.input, b.env, &mut |v| {
3223                    let piece = match b.fmt {
3224                        Some(name) => apply_format(name, &v)?,
3225                        None => render_raw(&v),
3226                    };
3227                    let next = format!("{piece}{acc}");
3228                    go(b, i, &next, out)
3229                })
3230            }
3231        }
3232    }
3233    go(
3234        &StrBuild {
3235            it,
3236            pieces,
3237            fmt,
3238            input,
3239            env,
3240        },
3241        pieces.len(),
3242        "",
3243        out,
3244    )
3245}
3246
3247/// Every jq `@format` name. A leading `@` is otherwise an XPATH attribute
3248/// step, so only these names are claimed for jq — `@href` still selects an
3249/// attribute. The lexer, the body dispatcher and the xpath front-end all read
3250/// this one list, so a format added here is claimed everywhere at once.
3251pub const FORMAT_NAMES: &[&str] = &[
3252    "base64", "base64d", "csv", "tsv", "json", "text", "html", "uri", "urid", "sh",
3253];
3254
3255/// `tostring` (and `@text`): a string comes back AS ITSELF — the same value, so
3256/// a path through it stays intact — anything else is its JSON text.
3257fn to_string_val(v: &JqVal) -> JqVal {
3258    match v.bare() {
3259        s @ JqVal::Str(_) => s.clone(),
3260        other => JqVal::str(render(other)),
3261    }
3262}
3263
3264/// jq's `@name` format strings.
3265fn apply_format(name: &str, v: &JqVal) -> R<String> {
3266    let v = v.bare();
3267    match name {
3268        "text" => Ok(render_raw(v)),
3269        "json" => Ok(render(v)),
3270        "base64" => Ok(b64_encode(render_raw(v).as_bytes())),
3271        "base64d" => {
3272            let text = render_raw(v);
3273            let raw = b64_decode(&text).map_err(|why| {
3274                let s = JqVal::str(text.as_str());
3275                JqErr::msg(format!("{}{} {why}", s.type_name(), paren_of(&s)))
3276            })?;
3277            Ok(jq_utf8_lossy(&raw))
3278        }
3279        "uri" => {
3280            let s = render_raw(v);
3281            let mut out = String::with_capacity(s.len());
3282            for b in s.bytes() {
3283                if b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.' | b'~') {
3284                    out.push(b as char);
3285                } else {
3286                    let _ = write!(out, "%{b:02X}");
3287                }
3288            }
3289            Ok(out)
3290        }
3291        // The inverse of `@uri`: `%XX` escapes decode to bytes, every other
3292        // byte passes through (`+` is NOT a space), and the decoded bytes must
3293        // be UTF-8. A stray `%`, a non-hex escape or a bad byte sequence is an
3294        // error, as jq 1.8 has it.
3295        "urid" => {
3296            let s = render_raw(v);
3297            let bad = || {
3298                JqErr::msg(format!(
3299                    "string ({}) is not a valid uri encoding",
3300                    render(&JqVal::str(s.as_str()))
3301                ))
3302            };
3303            let src = s.as_bytes();
3304            let mut raw = Vec::with_capacity(src.len());
3305            let mut i = 0;
3306            while i < src.len() {
3307                if src[i] == b'%' {
3308                    let hex = src.get(i + 1..i + 3).ok_or_else(bad)?;
3309                    // Exactly two hex DIGITS: `from_str_radix` alone also takes
3310                    // a sign, so `%+1` decoded to byte 1 where jq refuses.
3311                    if !hex.iter().all(u8::is_ascii_hexdigit) {
3312                        return Err(bad());
3313                    }
3314                    let hex = std::str::from_utf8(hex).map_err(|_| bad())?;
3315                    raw.push(u8::from_str_radix(hex, 16).map_err(|_| bad())?);
3316                    i += 3;
3317                } else {
3318                    raw.push(src[i]);
3319                    i += 1;
3320                }
3321            }
3322            String::from_utf8(raw).map_err(|_| bad())
3323        }
3324        "csv" | "tsv" => {
3325            let JqVal::Arr(a) = v else {
3326                return Err(JqErr::msg(format!(
3327                    "{}{} cannot be {}-formatted, only array",
3328                    v.type_name(),
3329                    paren_of(v),
3330                    name
3331                )));
3332            };
3333            let mut cells = Vec::with_capacity(a.len());
3334            for e in a.iter() {
3335                cells.push(match e {
3336                    JqVal::Null => String::new(),
3337                    JqVal::Bool(b) => b.to_string(),
3338                    // NaN renders as an empty cell, as null does.
3339                    JqVal::Num(n, _) if n.is_nan() => String::new(),
3340                    JqVal::Num(..) => render(e),
3341                    JqVal::Str(s) if name == "csv" => {
3342                        format!("\"{}\"", escape_string(s, &[('"', "\"\"")]))
3343                    }
3344                    JqVal::Str(s) => escape_string(
3345                        s,
3346                        &[('\t', "\\t"), ('\r', "\\r"), ('\n', "\\n"), ('\\', "\\\\")],
3347                    ),
3348                    other => {
3349                        return Err(JqErr::msg(format!(
3350                            // jq 1.8.2 words this "csv row" for `@tsv` too.
3351                            "{}{} is not valid in a csv row",
3352                            other.type_name(),
3353                            paren_of(other)
3354                        )));
3355                    }
3356                });
3357            }
3358            Ok(cells.join(if name == "csv" { "," } else { "\t" }))
3359        }
3360        "html" => {
3361            let table = [
3362                ('&', "&amp;"),
3363                ('<', "&lt;"),
3364                ('>', "&gt;"),
3365                ('\'', "&apos;"),
3366                ('"', "&quot;"),
3367            ];
3368            Ok(escape_string(&render_raw(v), &table))
3369        }
3370        "sh" => {
3371            let one = |x: &JqVal| -> R<String> {
3372                match x {
3373                    JqVal::Str(s) => Ok(format!("'{}'", escape_string(s, &[('\'', r"'\''")]))),
3374                    JqVal::Null | JqVal::Bool(_) | JqVal::Num(..) => Ok(render(x)),
3375                    other => Err(JqErr::msg(format!(
3376                        "{}{} can not be escaped for shell",
3377                        other.type_name(),
3378                        paren_of(other)
3379                    ))),
3380                }
3381            };
3382            match v.bare() {
3383                JqVal::Arr(a) => Ok(a.iter().map(one).collect::<R<Vec<_>>>()?.join(" ")),
3384                other => one(other),
3385            }
3386        }
3387        other => Err(JqErr::msg(format!("{other} is not a valid format"))),
3388    }
3389}
3390
3391/// jq's `escape_string` (src/builtin.c), shared by `@csv`, `@tsv`, `@html` and
3392/// `@sh`: each listed char is replaced by its escape, and a NUL is ALWAYS
3393/// written as the two characters `\0`, whatever the table says.
3394fn escape_string(s: &str, table: &[(char, &str)]) -> String {
3395    let mut out = String::with_capacity(s.len());
3396    for c in s.chars() {
3397        match table.iter().find(|(k, _)| *k == c) {
3398            _ if c == '\0' => out.push_str("\\0"),
3399            Some((_, esc)) => out.push_str(esc),
3400            None => out.push(c),
3401        }
3402    }
3403    out
3404}
3405
3406const B64: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
3407
3408fn b64_encode(data: &[u8]) -> String {
3409    let mut out = String::with_capacity(data.len().div_ceil(3) * 4);
3410    for chunk in data.chunks(3) {
3411        let b = [
3412            chunk[0],
3413            *chunk.get(1).unwrap_or(&0),
3414            *chunk.get(2).unwrap_or(&0),
3415        ];
3416        let n = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]);
3417        out.push(B64[(n >> 18) as usize & 63] as char);
3418        out.push(B64[(n >> 12) as usize & 63] as char);
3419        out.push(if chunk.len() > 1 {
3420            B64[(n >> 6) as usize & 63] as char
3421        } else {
3422            '='
3423        });
3424        out.push(if chunk.len() > 2 {
3425            B64[n as usize & 63] as char
3426        } else {
3427            '='
3428        });
3429    }
3430    out
3431}
3432
3433/// `@base64d`'s decoder, ported from jq 1.8.2 `src/builtin.c:f_format`.
3434///
3435/// Decoding stops at the first `=`, whatever follows it (`"YW=Jj"` is `a`);
3436/// any byte outside the alphabet -- a newline included -- is `is not valid
3437/// base64 data`; and one character left over after the last whole group is
3438/// `trailing base64 byte found`, while two or three decode with their spare
3439/// bits dropped. The error is the reason, for the caller to name the input.
3440fn b64_decode(s: &str) -> Result<Vec<u8>, &'static str> {
3441    let mut out = Vec::with_capacity(s.len() / 4 * 3 + 2);
3442    let (mut code, mut held) = (0u32, 0u32);
3443    for c in s.bytes().take_while(|&c| c != b'=') {
3444        let v = B64
3445            .iter()
3446            .position(|&x| x == c)
3447            .ok_or("is not valid base64 data")? as u32;
3448        code = (code << 6) | v;
3449        held += 1;
3450        if held == 4 {
3451            out.extend_from_slice(&[(code >> 16) as u8, (code >> 8) as u8, code as u8]);
3452            (code, held) = (0, 0);
3453        }
3454    }
3455    match held {
3456        3 => out.extend_from_slice(&[(code >> 10) as u8, (code >> 2) as u8]),
3457        2 => out.push((code >> 4) as u8),
3458        1 => return Err("trailing base64 byte found"),
3459        _ => {}
3460    }
3461    Ok(out)
3462}
3463
3464/// Bytes to a string the way jq 1.8's `jv_string_sized` repairs them, which is
3465/// not `String::from_utf8_lossy`: jq's `jvp_utf8_next` writes one U+FFFD per
3466/// bad sequence, and a lead byte whose sequence runs past the END takes every
3467/// remaining byte with it -- `9E E9 65` is two replacement characters in jq,
3468/// where the Rust repair keeps the `e`.
3469fn jq_utf8_lossy(b: &[u8]) -> String {
3470    let mut out = String::with_capacity(b.len());
3471    let mut i = 0;
3472    while i < b.len() {
3473        let first = b[i];
3474        let length = match first {
3475            0x00..=0x7F => {
3476                out.push(first as char);
3477                i += 1;
3478                continue;
3479            }
3480            0xC2..=0xDF => 2,
3481            0xE0..=0xEF => 3,
3482            0xF0..=0xF4 => 4,
3483            // A continuation byte, or a lead byte no sequence starts with.
3484            _ => {
3485                out.push('\u{FFFD}');
3486                i += 1;
3487                continue;
3488            }
3489        };
3490        if i + length > b.len() {
3491            out.push('\u{FFFD}');
3492            break;
3493        }
3494        match std::str::from_utf8(&b[i..i + length]) {
3495            Ok(s) => {
3496                out.push_str(s);
3497                i += length;
3498            }
3499            Err(_) => {
3500                out.push('\u{FFFD}');
3501                // Consume up to the first byte that is not a continuation; an
3502                // overlong or surrogate sequence of whole length goes entirely.
3503                let bad = (1..length)
3504                    .find(|&k| b[i + k] & 0xC0 != 0x80)
3505                    .unwrap_or(length);
3506                i += bad;
3507            }
3508        }
3509    }
3510    out
3511}
3512
3513/// `{k: v, …}`. Both the key and the value are generators, and the FIRST entry
3514/// varies slowest — measured: `{a:(1,2), b:(3,4)}` emits `a=1,b=3`, `a=1,b=4`,
3515/// `a=2,b=3`, `a=2,b=4`.
3516fn build_object(
3517    it: &Interp,
3518    entries: &[ObjEntry],
3519    i: usize,
3520    acc: Vec<(Rc<str>, JqVal)>,
3521    input: &JqVal,
3522    env: &Env,
3523    out: Sink,
3524) -> R<()> {
3525    let Some(ObjEntry::KeyVal(kf, vf)) = entries.get(i) else {
3526        return out(JqVal::obj(acc));
3527    };
3528    eval(it, kf, input, env, &mut |k| {
3529        let JqVal::Str(key) = k.bare().clone() else {
3530            return Err(JqErr::msg(format!(
3531                "Cannot use {}{} as object key",
3532                k.type_name(),
3533                paren_of(&k)
3534            )));
3535        };
3536        eval(it, vf, input, env, &mut |v| {
3537            let mut next = acc.clone();
3538            match next.iter_mut().find(|(ek, _)| *ek == key) {
3539                Some(slot) => slot.1 = v,
3540                None => next.push((key.clone(), v)),
3541            }
3542            build_object(it, entries, i + 1, next, input, env, out)
3543        })
3544    })
3545}
3546
3547// ─────────────────────────────────────────────────────────────────────────────
3548// Destructuring
3549// ─────────────────────────────────────────────────────────────────────────────
3550
3551/// Bind `pat` against `v` and call `k` with the extended environment. A pattern
3552/// whose key is a generator produces several binding sets, so `k` may run more
3553/// than once.
3554/// What a pattern match hands its continuation: the environment with the
3555/// pattern's variables bound and, in a path expression, the path state the
3556/// matcher's index steps left behind.
3557type Matched<'a> = &'a mut dyn FnMut(Env, Option<Tracked>) -> R<()>;
3558
3559/// One INDEX of a destructuring matcher. Inside a path expression it is a
3560/// tracked step like any other: the value being indexed must still be the one
3561/// at the path (jq's `INDEX`, src/execute.c), and the element becomes it —
3562/// which is why `path(. as [$a] | $a)` is `[0]`, and why a second element of a
3563/// pattern refuses after the first moved the path.
3564fn pattern_index(v: &JqVal, key: &JqVal, tr: &Option<Tracked>) -> R<(JqVal, Option<Tracked>)> {
3565    if let Some(t) = tr {
3566        if !t.intact(v) {
3567            return Err(JqErr::msg(format!(
3568                "Invalid path expression near attempt to access element {} of {}",
3569                dump_trunc(key),
3570                dump_trunc(v)
3571            )));
3572        }
3573    }
3574    let elem = index_value(v, key)?;
3575    let next = tr.as_ref().map(|t| t.push(key.clone(), &elem));
3576    Ok((elem, next))
3577}
3578
3579fn bind_pattern(
3580    it: &Interp,
3581    pat: &Pattern,
3582    v: &JqVal,
3583    env: &Env,
3584    tr: Option<Tracked>,
3585    k: Matched,
3586) -> R<()> {
3587    match pat {
3588        Pattern::Var(name) => k(env.bind(name.clone(), v.clone()), tr),
3589        Pattern::Arr(subs) => bind_arr(it, subs, subs.len(), v, env.clone(), tr, k),
3590        Pattern::Obj(subs) => bind_obj(it, subs, 0, v, env.clone(), tr, k),
3591    }
3592}
3593
3594/// Bind the first `n` elements of an array pattern, LAST element first: jq's
3595/// array matcher indexes and binds from the end, so on a non-indexable value
3596/// `1 as [$a, $b]` refuses at index 1, and a generator in a later element is the
3597/// outer loop of one in an earlier element.
3598fn bind_arr(
3599    it: &Interp,
3600    subs: &[Pattern],
3601    n: usize,
3602    v: &JqVal,
3603    env: Env,
3604    tr: Option<Tracked>,
3605    k: Matched,
3606) -> R<()> {
3607    let Some(i) = n.checked_sub(1) else {
3608        return k(env, tr);
3609    };
3610    let (elem, after) = pattern_index(v, &JqVal::num(i as f64), &tr)?;
3611    bind_pattern(it, &subs[i], &elem, &env, after, &mut |e, t| {
3612        bind_arr(it, subs, i, v, e, t, k)
3613    })
3614}
3615
3616/// One entry of an object destructuring pattern: the KEY filter, an optional
3617/// sub-pattern for the value, and the variable a `{$a}` shorthand binds.
3618type ObjPatEntry = (Filter, Option<Pattern>, Option<Rc<str>>);
3619
3620fn bind_obj(
3621    it: &Interp,
3622    subs: &[ObjPatEntry],
3623    i: usize,
3624    v: &JqVal,
3625    env: Env,
3626    tr: Option<Tracked>,
3627    k: Matched,
3628) -> R<()> {
3629    let Some((kf, sub, shorthand)) = subs.get(i) else {
3630        return k(env, tr);
3631    };
3632    eval(it, kf, v, &env, &mut |key| {
3633        let (field, after) = pattern_index(v, &key, &tr)?;
3634        let base = match shorthand {
3635            // `{$a}` binds `$a` to `.a` AND may still carry a sub-pattern.
3636            Some(name) => env.bind(name.clone(), field.clone()),
3637            None => env.clone(),
3638        };
3639        match sub {
3640            Some(p) => bind_pattern(it, p, &field, &base, after, &mut |e, t| {
3641                bind_obj(it, subs, i + 1, v, e, t, k)
3642            }),
3643            None => bind_obj(it, subs, i + 1, v, base, after, k),
3644        }
3645    })
3646}
3647
3648/// `SRC as P1 ?// P2 | BODY`. Each alternative is tried in turn; the first that
3649/// binds without error wins, and every variable named anywhere in the group is
3650/// bound (to `null` where the winning pattern does not mention it), which is
3651/// jq's rule for the destructuring-alternative operator. `body` runs once per
3652/// binding, with the path state the matcher left (`tr` is `None` outside a
3653/// path expression).
3654fn bind_alternatives(
3655    it: &Interp,
3656    pats: &[Pattern],
3657    v: &JqVal,
3658    env: &Env,
3659    tr: Option<&Tracked>,
3660    body: Matched,
3661) -> R<()> {
3662    let mut all_names = Vec::new();
3663    for p in pats {
3664        collect_pattern_vars(p, &mut all_names);
3665    }
3666    for (i, p) in pats.iter().enumerate() {
3667        let last = i + 1 == pats.len();
3668        let base = all_names
3669            .iter()
3670            .fold(env.clone(), |e, n| e.bind(n.clone(), JqVal::Null));
3671        // The BODY sees the original `.`, not the bound value: `jq -n '1 as $x
3672        // | .'` is `null`. Only the pattern reads `v`.
3673        // jq's DESTRUCTURE_ALT handler takes ANY error raised after the fork
3674        // point — the body's, but also everything DOWNSTREAM of it, and a
3675        // `break` (an error under the hood) — and moves on to the next
3676        // alternative. `first(. as [$a] ?// $a | $a)` therefore yields twice.
3677        match bind_pattern(it, p, v, &base, tr.cloned(), body) {
3678            Ok(()) => return Ok(()),
3679            Err(e @ (JqErr::Err(_) | JqErr::Break(_))) if !last => drop(e),
3680            Err(e) => return Err(e),
3681        }
3682    }
3683    Ok(())
3684}
3685
3686fn collect_pattern_vars(p: &Pattern, out: &mut Vec<Rc<str>>) {
3687    match p {
3688        Pattern::Var(n) => out.push(n.clone()),
3689        Pattern::Arr(subs) => subs.iter().for_each(|s| collect_pattern_vars(s, out)),
3690        Pattern::Obj(subs) => {
3691            for (_, sub, shorthand) in subs {
3692                if let Some(n) = shorthand {
3693                    out.push(n.clone());
3694                }
3695                if let Some(s) = sub {
3696                    collect_pattern_vars(s, out);
3697                }
3698            }
3699        }
3700    }
3701}
3702
3703// ─────────────────────────────────────────────────────────────────────────────
3704// Path expressions
3705// ─────────────────────────────────────────────────────────────────────────────
3706
3707/// The path state jq keeps while it evaluates a path expression
3708/// (src/execute.c): the keys followed so far, and `value_at_path`, the value
3709/// they lead to. The value TRAVELLING with the state may differ — a filter
3710/// that is not a path expression replaces it — and the path is INTACT only
3711/// while the two are [`identical`]. jq checks that where it next needs the
3712/// path (an index step, an iteration, the end of `path(…)`), so a value that
3713/// is never used as a path is no error, and one identical to the value at the
3714/// path (`path(.a | tostring)` on a string) keeps the path intact.
3715#[derive(Clone)]
3716struct Tracked {
3717    keys: Vec<JqVal>,
3718    at: JqVal,
3719    /// The travelling value is a number a builtin or operator COMPUTED from the
3720    /// one at the path. A parsed number is a decNumber literal in jq and a
3721    /// computed one a double, so the two are never `jv_identical` even when
3722    /// their values agree (`path(length)` over `5` refuses). A [`NumLit`] says
3723    /// how a number was MADE, not whether this builtin made it — `length` hands
3724    /// a positive literal straight back — so the distinction rides on the
3725    /// state instead.
3726    computed: bool,
3727}
3728
3729impl Tracked {
3730    /// `PATH_BEGIN`: an empty path at `v`.
3731    fn root(v: &JqVal) -> Tracked {
3732        Tracked {
3733            keys: Vec::new(),
3734            at: v.clone(),
3735            computed: false,
3736        }
3737    }
3738
3739    /// `path_append`: one more key, reaching `next`.
3740    fn push(&self, key: JqVal, next: &JqVal) -> Tracked {
3741        let mut keys = self.keys.clone();
3742        keys.push(key);
3743        Tracked {
3744            keys,
3745            at: next.clone(),
3746            computed: false,
3747        }
3748    }
3749
3750    fn intact(&self, v: &JqVal) -> bool {
3751        !(self.computed && matches!(v, JqVal::Num(..))) && identical(v, &self.at)
3752    }
3753}
3754
3755/// Where a path expression's results go: the path state and the value
3756/// travelling with it.
3757type PathSink<'a> = &'a mut dyn FnMut(Tracked, JqVal) -> R<()>;
3758
3759/// `PATH_END`: the keys of a path expression's result, or jq's refusal
3760/// naming the value when the path is no longer intact.
3761fn intact_path(p: Tracked, v: &JqVal) -> R<Vec<JqVal>> {
3762    if p.intact(v) {
3763        Ok(p.keys)
3764    } else {
3765        Err(JqErr::msg(format!(
3766            "Invalid path expression with result {}",
3767            dump_trunc(v)
3768        )))
3769    }
3770}
3771
3772/// jq's `jv_identical`, as far as arb's values can tell: equal null/booleans,
3773/// a computed number with the same bits, or the same shared literal, string,
3774/// array or object allocation.
3775fn identical(a: &JqVal, b: &JqVal) -> bool {
3776    match (a, b) {
3777        (JqVal::Null, JqVal::Null) => true,
3778        (JqVal::Bool(x), JqVal::Bool(y)) => x == y,
3779        (JqVal::Num(_, NumLit::Text(x)), JqVal::Num(_, NumLit::Text(y))) => Rc::ptr_eq(x, y),
3780        (JqVal::Num(_, NumLit::Text(_)), JqVal::Num(..))
3781        | (JqVal::Num(..), JqVal::Num(_, NumLit::Text(_))) => false,
3782        // A computed number and a canonical literal both are their bits; whether
3783        // the travelling one was COMPUTED is `Tracked::computed`'s to say.
3784        (JqVal::Num(x, _), JqVal::Num(y, _)) => x.to_bits() == y.to_bits(),
3785        (JqVal::Str(x), JqVal::Str(y)) => Rc::ptr_eq(x, y),
3786        (JqVal::Arr(x), JqVal::Arr(y)) => Rc::ptr_eq(x, y),
3787        (JqVal::Obj(x), JqVal::Obj(y)) => Rc::ptr_eq(x, y),
3788        (JqVal::Node(x), JqVal::Node(y)) => Rc::ptr_eq(x, y),
3789        _ => false,
3790    }
3791}
3792
3793/// Evaluate `f` as a PATH expression — jq with path tracking on. This is what
3794/// `path`, `del`, `paths`, `pick` and every assignment operator are built on.
3795///
3796/// `input` is the `.` that index/condition sub-filters see; `val` is the value
3797/// travelling with the path state `pre`.
3798fn eval_paths(
3799    it: &Interp,
3800    f: &Filter,
3801    input: &JqVal,
3802    pre: &Tracked,
3803    val: &JqVal,
3804    env: &Env,
3805    out: PathSink,
3806) -> R<()> {
3807    match f {
3808        Filter::Identity => out(pre.clone(), val.clone()),
3809        Filter::RecurseDefault => recurse_paths(pre, val, out),
3810        Filter::Field(..) | Filter::Index(..) | Filter::Slice(..) | Filter::Iterate(..) => {
3811            eval_index_paths(it, f, false, input, pre, val, env, out)
3812        }
3813        Filter::IndexOpt(inner) => eval_index_paths(it, inner, true, input, pre, val, env, out),
3814        Filter::Pipe(a, b) => eval_paths(it, a, input, pre, val, env, &mut |p, v| {
3815            eval_paths(it, b, &v, &p, &v, env, out)
3816        }),
3817        Filter::Comma(a, b) => {
3818            eval_paths(it, a, input, pre, val, env, out)?;
3819            eval_paths(it, b, input, pre, val, env, out)
3820        }
3821        Filter::Optional(inner) => eval_try_paths(it, inner, None, input, pre, val, env, out),
3822        // `gen_try`: the body is tracked; the handler runs on the error from
3823        // the state the `try` began in.
3824        Filter::Try(body, handler) => {
3825            eval_try_paths(it, body, handler.as_deref(), input, pre, val, env, out)
3826        }
3827        Filter::If(arms, els) => eval_if_paths(
3828            it,
3829            IfNode {
3830                arms,
3831                els: els.as_deref(),
3832            },
3833            input,
3834            pre,
3835            val,
3836            env,
3837            out,
3838        ),
3839        // `gen_and` / `gen_or` run both operands with tracking ON and answer a
3840        // boolean CONSTANT from the state they left, so `path(.a and .b)` over
3841        // `{"a": false}` is `["a"]` (`false` is `jv_identical` to `.a`), while a
3842        // second operand refuses once the first has moved the path.
3843        Filter::And(a, b) | Filter::Or(a, b) => {
3844            let is_and = matches!(f, Filter::And(..));
3845            eval_paths(it, a, input, pre, val, env, &mut |pa, va| {
3846                if va.truthy() == is_and {
3847                    eval_paths(it, b, input, &pa, val, env, &mut |pb, vb| {
3848                        out(pb, JqVal::Bool(vb.truthy()))
3849                    })
3850                } else {
3851                    out(pa, JqVal::Bool(!is_and))
3852                }
3853            })
3854        }
3855        // The path form of `a // b`: errors in `a` propagate here too.
3856        Filter::Alt(a, b) => {
3857            let mut any = false;
3858            eval_paths(it, a, input, pre, val, env, &mut |p, v| {
3859                if v.truthy() {
3860                    any = true;
3861                    out(p, v)
3862                } else {
3863                    Ok(())
3864                }
3865            })?;
3866            if any {
3867                Ok(())
3868            } else {
3869                eval_paths(it, b, input, pre, val, env, out)
3870            }
3871        }
3872        Filter::Def(def, rest) => {
3873            let inner = env.define(def.clone());
3874            eval_paths(it, rest, input, pre, val, &inner, out)
3875        }
3876        Filter::Bind(src, pats, body) => eval(it, src, input, env, &mut |sv| {
3877            bind_alternatives(it, pats, &sv, env, Some(pre), &mut |benv, tp| {
3878                let tp = tp.unwrap_or_else(|| pre.clone());
3879                eval_paths(it, body, input, &tp, val, &benv, out)
3880            })
3881        }),
3882        Filter::Label(name, body) => {
3883            let id = it.next_label();
3884            let benv = env.bind(label_key(name), JqVal::num(id as f64));
3885            match eval_paths(it, body, input, pre, val, &benv, &mut |p, v| {
3886                out(p, v).map_err(wrap_downstream)
3887            }) {
3888                Err(e) if breaks_to(&e, id) => Ok(()),
3889                Err(e) => match unwrap_downstream(e) {
3890                    Ok(real) => Err(real),
3891                    Err(other) => Err(other),
3892                },
3893                Ok(()) => Ok(()),
3894            }
3895        }
3896        // `gen_reduce`: the init is tracked, then each source item is tracked
3897        // from there and the update tracked from the item's state — but every
3898        // iteration BACKTRACKS, so the result travels with the state the init
3899        // left.
3900        Filter::Reduce(src, pat, init, update) => {
3901            // The first pass takes `.`; later ones see `null` (see the value form).
3902            let mut pass = 0usize;
3903            eval_paths(it, init, input, pre, val, env, &mut |ti, init_v| {
3904                let (dot, at) = if pass == 0 {
3905                    (input, val)
3906                } else {
3907                    (&JqVal::Null, &JqVal::Null)
3908                };
3909                pass += 1;
3910                let mut acc = init_v;
3911                eval_paths(it, src, dot, &ti, at, env, &mut |ts, item| {
3912                    bind_pattern(it, pat, &item, env, Some(ts.clone()), &mut |benv, tp| {
3913                        let tp = tp.unwrap_or_else(|| ts.clone());
3914                        let mut last = None;
3915                        eval_paths(it, update, &acc, &tp, &acc, &benv, &mut |_, v| {
3916                            last = Some(v);
3917                            Ok(())
3918                        })?;
3919                        acc = last.unwrap_or(JqVal::Null);
3920                        Ok(())
3921                    })
3922                })?;
3923                out(ti, acc.clone())
3924            })
3925        }
3926        // `gen_foreach`: as `reduce`, except each update output is extracted
3927        // from the state the source item and the update left.
3928        Filter::Foreach(src, pat, init, update, extract) => {
3929            eval_paths(it, init, input, pre, val, env, &mut |ti, init_v| {
3930                let mut acc = init_v;
3931                eval_paths(it, src, input, &ti, val, env, &mut |ts, item| {
3932                    bind_pattern(it, pat, &item, env, Some(ts.clone()), &mut |benv, tp| {
3933                        let tp = tp.unwrap_or_else(|| ts.clone());
3934                        let mut states = Vec::new();
3935                        eval_paths(it, update, &acc, &tp, &acc, &benv, &mut |tu, v| {
3936                            states.push((tu, v));
3937                            Ok(())
3938                        })?;
3939                        if states.is_empty() {
3940                            acc = JqVal::Null;
3941                        }
3942                        for (tu, st) in states {
3943                            acc = st.clone();
3944                            match extract {
3945                                Some(e) => eval_paths(it, e, &st, &tu, &st, &benv, out)?,
3946                                None => out(tu, st)?,
3947                            }
3948                        }
3949                        Ok(())
3950                    })
3951                })
3952            })
3953        }
3954        // An assignment is a path expression only through the jq definitions it
3955        // expands to (`_modify`, `_assign`), so those run — their `[., []]`
3956        // state and `delpaths` result are what the refusals name.
3957        Filter::Assign(op, lhs, rhs) => {
3958            let (operand, call) = assignment_call(*op, lhs, rhs);
3959            match operand {
3960                None => eval_paths(it, &call, input, pre, val, env, out),
3961                Some(operand) => eval_paths(it, operand, input, pre, val, env, &mut |p, v| {
3962                    let bound = env.bind(Rc::from(ASSIGN_OPERAND), v);
3963                    eval_paths(it, &call, input, &p, val, &bound, out)
3964                }),
3965            }
3966        }
3967        Filter::Call(name, args) => eval_call_paths(it, (name, args), input, pre, val, env, out),
3968        // `[E]`: the body runs with tracking on (so `.[]` over a value that is
3969        // no longer at the path refuses), then the collected array travels on
3970        // from the state the collection began in.
3971        Filter::Array(Some(inner)) => {
3972            let mut items = Vec::new();
3973            eval_paths(it, inner, input, pre, val, env, &mut |_, v| {
3974                items.push(v);
3975                Ok(())
3976            })?;
3977            out(pre.clone(), JqVal::arr(items))
3978        }
3979        other => non_path(it, other, pre, val, env, out),
3980    }
3981}
3982
3983/// `try`/`?` as a path expression. The body is tracked; downstream errors
3984/// pass through; a body error runs the handler (if any) from `pre`.
3985#[allow(clippy::too_many_arguments)]
3986fn eval_try_paths(
3987    it: &Interp,
3988    body: &Filter,
3989    handler: Option<&Filter>,
3990    input: &JqVal,
3991    pre: &Tracked,
3992    val: &JqVal,
3993    env: &Env,
3994    out: PathSink,
3995) -> R<()> {
3996    match eval_paths(it, body, input, pre, val, env, &mut |p, v| {
3997        out(p, v).map_err(wrap_downstream)
3998    }) {
3999        Ok(()) => Ok(()),
4000        Err(e) => match unwrap_downstream(e) {
4001            Ok(real) => Err(real),
4002            Err(caught) => {
4003                let payload = caught_payload(caught)?;
4004                match handler {
4005                    Some(h) => eval_paths(it, h, &payload, pre, &payload, env, out),
4006                    None => Ok(()),
4007                }
4008            }
4009        },
4010    }
4011}
4012
4013/// [`eval_index`] as a path expression: each step extends the path by its key
4014/// (a slice by its `{"start","end"}` object). Under `opt` the step's own error
4015/// yields no path — but a path that is no longer intact refuses either way,
4016/// as INDEX_OPT/EACH_OPT do.
4017#[allow(clippy::too_many_arguments)]
4018fn eval_index_paths(
4019    it: &Interp,
4020    f: &Filter,
4021    opt: bool,
4022    input: &JqVal,
4023    pre: &Tracked,
4024    val: &JqVal,
4025    env: &Env,
4026    out: PathSink,
4027) -> R<()> {
4028    let step = |p: &Tracked, v: &JqVal, key: JqVal, r: R<JqVal>, out: PathSink| {
4029        if !p.intact(v) {
4030            return Err(JqErr::msg(format!(
4031                "Invalid path expression near attempt to access element {} of {}",
4032                dump_trunc(&key),
4033                dump_trunc(v)
4034            )));
4035        }
4036        match r {
4037            Ok(next) => out(p.push(key, &next), next),
4038            Err(_) if opt => Ok(()),
4039            Err(e) => Err(e),
4040        }
4041    };
4042    match f {
4043        Filter::Field(base, name) => eval_paths(it, base, input, pre, val, env, &mut |p, v| {
4044            let key = JqVal::Str(name.clone());
4045            let r = index_value(&v, &key);
4046            step(&p, &v, key, r, out)
4047        }),
4048        // Index/bounds outermost, term innermost: see `eval_index`.
4049        Filter::Index(base, idx) => eval(it, idx, input, env, &mut |i| {
4050            eval_paths(it, base, input, pre, val, env, &mut |p, v| {
4051                let r = index_value(&v, &i);
4052                step(&p, &v, i.clone(), r, out)
4053            })
4054        }),
4055        Filter::Slice(base, lo, hi) => eval_opt(it, lo.as_deref(), input, env, &mut |l| {
4056            eval_opt(it, hi.as_deref(), input, env, &mut |h| {
4057                eval_paths(it, base, input, pre, val, env, &mut |p, v| {
4058                    let r = slice_value(&v, &l, &h);
4059                    let key = JqVal::obj(vec![
4060                        (Rc::from("start"), l.clone()),
4061                        (Rc::from("end"), h.clone()),
4062                    ]);
4063                    step(&p, &v, key, r, out)
4064                })
4065            })
4066        }),
4067        Filter::Iterate(base) => eval_paths(it, base, input, pre, val, env, &mut |p, v| {
4068            if !p.intact(&v) {
4069                return Err(not_intact_iterate(&v));
4070            }
4071            match v.bare() {
4072                JqVal::Arr(a) => {
4073                    for (i, e) in a.iter().enumerate() {
4074                        out(p.push(JqVal::num(i as f64), e), e.clone())?;
4075                    }
4076                    Ok(())
4077                }
4078                JqVal::Obj(m) => {
4079                    for (k, e) in m.iter() {
4080                        out(p.push(JqVal::Str(k.clone()), e), e.clone())?;
4081                    }
4082                    Ok(())
4083                }
4084                _ if opt => Ok(()),
4085                other => Err(JqErr::msg(format!(
4086                    "Cannot iterate over {}{}",
4087                    other.type_name(),
4088                    paren_of(other)
4089                ))),
4090            }
4091        }),
4092        other => unreachable!("not an index step: {other:?}"),
4093    }
4094}
4095
4096/// EACH/EACH_OPT over a path that is no longer intact.
4097fn not_intact_iterate(v: &JqVal) -> JqErr {
4098    JqErr::msg(format!(
4099        "Invalid path expression near attempt to iterate through {}",
4100        dump_trunc(v)
4101    ))
4102}
4103
4104/// A filter that is not a path expression, met where a path is required. jq
4105/// RUNS it with tracking left as it was: each output travels on with the same
4106/// path state, to be judged where the path is next needed. A filter that
4107/// yields nothing is no error (`path(empty | tostring)` is empty), and one
4108/// that raises reports its own error (`null | path(abs)` is `null (null)
4109/// cannot be negated`).
4110fn non_path(
4111    it: &Interp,
4112    f: &Filter,
4113    pre: &Tracked,
4114    val: &JqVal,
4115    env: &Env,
4116    out: PathSink,
4117) -> R<()> {
4118    eval(it, f, val, env, &mut |v| {
4119        let mut state = pre.clone();
4120        state.computed = is_computed_number(f, val, pre, &v);
4121        out(state, v)
4122    })
4123}
4124
4125/// Did `f`, run on `val`, answer a number that is NOT the value at the path
4126/// even though it compares equal to it? A variable holds a value taken from
4127/// somewhere, `tonumber` over a number and the `debug`/`stderr` taps hand that
4128/// number back; anything else builds a new one.
4129fn is_computed_number(f: &Filter, val: &JqVal, pre: &Tracked, v: &JqVal) -> bool {
4130    // `nan` is never a decNumber literal: jq reads it as a plain double, so a
4131    // computed NaN is as identical to it as any double is to itself.
4132    if matches!(v, JqVal::Num(x, _) if x.is_nan()) {
4133        return false;
4134    }
4135    if !(matches!(v, JqVal::Num(..)) && matches!(pre.at, JqVal::Num(..)) && identical(v, &pre.at)) {
4136        return false;
4137    }
4138    match f {
4139        Filter::Var(_) => false,
4140        // These hand the value they were given straight back.
4141        Filter::Call(name, args)
4142            if matches!((&**name, args.len()), ("debug", 0 | 1) | ("stderr", 0)) =>
4143        {
4144            false
4145        }
4146        Filter::Call(name, args) if &**name == "tonumber" && args.is_empty() => {
4147            !matches!(val, JqVal::Num(..))
4148        }
4149        _ => true,
4150    }
4151}
4152
4153/// The remaining arms of an `if` plus its `else`, walked one arm at a time.
4154#[derive(Clone, Copy)]
4155struct IfNode<'a> {
4156    arms: &'a [(Filter, Filter)],
4157    els: Option<&'a Filter>,
4158}
4159
4160fn eval_if_paths(
4161    it: &Interp,
4162    node: IfNode,
4163    input: &JqVal,
4164    pre: &Tracked,
4165    val: &JqVal,
4166    env: &Env,
4167    out: PathSink,
4168) -> R<()> {
4169    let Some(((cond, then), rest)) = node.arms.split_first() else {
4170        return match node.els {
4171            Some(e) => eval_paths(it, e, input, pre, val, env, out),
4172            None => out(pre.clone(), val.clone()),
4173        };
4174    };
4175    eval(it, cond, val, env, &mut |c| {
4176        if c.truthy() {
4177            eval_paths(it, then, input, pre, val, env, out)
4178        } else {
4179            eval_if_paths(
4180                it,
4181                IfNode {
4182                    arms: rest,
4183                    els: node.els,
4184                },
4185                input,
4186                pre,
4187                val,
4188                env,
4189                out,
4190            )
4191        }
4192    })
4193}
4194
4195/// Builtins jq writes in jq whose path-mode behaviour comes from that
4196/// definition (the `_pm_*` prelude entries); arb answers them natively when
4197/// evaluated as values.
4198const PATH_DEFINED: &[(&str, usize)] = &[
4199    ("sub", 2),
4200    ("sub", 3),
4201    ("gsub", 2),
4202    ("gsub", 3),
4203    ("splits", 1),
4204    ("splits", 2),
4205    ("split", 2),
4206    ("reverse", 0),
4207    ("sort_by", 1),
4208    ("group_by", 1),
4209    ("unique_by", 1),
4210    ("min_by", 1),
4211    ("max_by", 1),
4212    ("debug", 1),
4213];
4214
4215/// Does `name/arity` still mean the builtin — the prelude's definition or a
4216/// native one — and not a function the program wrote over it?
4217fn is_builtin_binding(env: &Env, name: &str, arity: usize) -> bool {
4218    match env.find_fn(name, arity) {
4219        None => true,
4220        Some(mine) => prelude_env()
4221            .find_fn(name, arity)
4222            .is_some_and(|own| Rc::ptr_eq(&mine, &own)),
4223    }
4224}
4225
4226/// The builtins that are legal inside a path expression.
4227fn eval_call_paths(
4228    it: &Interp,
4229    call: (&str, &[Rc<Filter>]),
4230    input: &JqVal,
4231    pre: &Tracked,
4232    val: &JqVal,
4233    env: &Env,
4234    out: PathSink,
4235) -> R<()> {
4236    let (name, args) = call;
4237    match (name, args.len()) {
4238        ("empty", 0) => Ok(()),
4239        ("error", 0) => Err(JqErr::Err(val.clone())),
4240        ("error", 1) => eval(it, &args[0], val, env, &mut |m| Err(JqErr::Err(m))),
4241        ("select", 1) => eval(it, &args[0], val, env, &mut |c| {
4242            if c.truthy() {
4243                out(pre.clone(), val.clone())
4244            } else {
4245                Ok(())
4246            }
4247        }),
4248        // `_jq_path_append`: an intact path grows by the whole array; one that
4249        // is not intact is left as it was, with the value found.
4250        ("getpath", 1) => eval(it, &args[0], val, env, &mut |p| {
4251            let JqVal::Arr(segs) = &p else {
4252                return Err(JqErr::msg("Path must be specified as an array"));
4253            };
4254            let found = get_path(val, segs)?;
4255            if !pre.intact(val) {
4256                return out(pre.clone(), found);
4257            }
4258            let mut keys = pre.keys.clone();
4259            keys.extend(segs.iter().cloned());
4260            out(
4261                Tracked {
4262                    keys,
4263                    at: found.clone(),
4264                    computed: false,
4265                },
4266                found,
4267            )
4268        }),
4269        // jq defines both as `explode | map(…) | implode`: the codepoint array
4270        // is no value at the path, so `map`'s `.[]` refuses to iterate it.
4271        ("ascii_downcase", 0) | ("ascii_upcase", 0) => {
4272            let s = str_or(val, "explode input must be a string")?;
4273            Err(not_intact_iterate(&JqVal::arr(
4274                s.chars()
4275                    .map(|c| JqVal::num(f64::from(u32::from(c))))
4276                    .collect(),
4277            )))
4278        }
4279        ("recurse", 0) => recurse_paths(pre, val, out),
4280        ("recurse", 1) => recurse_paths_f(it, &args[0], input, pre, val, env, out),
4281        ("first", 1) => {
4282            // `def first(f): label $out | f | ., break $out` — one label entered.
4283            let id = it.next_label();
4284            let r = eval_paths(it, &args[0], input, pre, val, env, &mut |p, v| {
4285                out(p, v).map_err(wrap_downstream)?;
4286                Err(JqErr::Break(id))
4287            });
4288            match r {
4289                Err(e) if breaks_to(&e, id) => Ok(()),
4290                Err(e) => match unwrap_downstream(e) {
4291                    Ok(real) => Err(real),
4292                    Err(other) => Err(other),
4293                },
4294                Ok(()) => Ok(()),
4295            }
4296        }
4297        // `gen_last_1`: the argument is tracked, but every output BACKTRACKS,
4298        // so the last value travels with the state `last` began in.
4299        // C in jq 1.8, so an ordinary value computation to a path expression.
4300        ("bsearch", 1) if is_builtin_binding(env, name, 1) => non_path(
4301            it,
4302            &Filter::Call(Rc::from(name), args.to_vec()),
4303            pre,
4304            val,
4305            env,
4306            out,
4307        ),
4308        ("last", 1) => {
4309            let mut last = None;
4310            eval_paths(it, &args[0], input, pre, val, env, &mut |_, v| {
4311                last = Some(v);
4312                Ok(())
4313            })?;
4314            match last {
4315                Some(v) => out(pre.clone(), v),
4316                None => Ok(()),
4317            }
4318        }
4319        // jq writes these in jq, over `match`; a path expression sees that
4320        // definition (the refusals name its intermediate values), where value
4321        // evaluation takes the native shortcut.
4322        (n, a) if PATH_DEFINED.contains(&(n, a)) && is_builtin_binding(env, n, a) => {
4323            let target = Filter::Call(Rc::from(format!("_pm_{name}")), args.to_vec());
4324            eval_paths(it, &target, input, pre, val, env, out)
4325        }
4326        // A user-defined function may still be a path expression — inline its
4327        // body and keep walking.
4328        _ => match env.find_fn(name, args.len()) {
4329            Some(node) => {
4330                let (body, benv) = bind_call(it, &node, args, env)?;
4331                eval_paths(it, &body, input, pre, val, &benv, out)
4332            }
4333            None => non_path(
4334                it,
4335                &Filter::Call(Rc::from(name), args.to_vec()),
4336                pre,
4337                val,
4338                env,
4339                out,
4340            ),
4341        },
4342    }
4343}
4344
4345/// The variable an arithmetic or `//=` assignment binds its right-hand side to.
4346const ASSIGN_OPERAND: &str = "__assign_rhs";
4347
4348/// parser.y's expansion of an assignment operator: `a = b` is `_assign(a; b)`,
4349/// `a |= b` is `_modify(a; b)`, and `a op= b` / `a //= b` bind `b` once and
4350/// run `_modify(a; . op $b)` / `_modify(a; . // $b)`.
4351///
4352/// Answers the right-hand side to bind first (`None` when the operator does
4353/// not bind one) and the call to run after it. The binding is NOT a `subexp`:
4354/// `b` runs with path tracking on, from the same state the whole assignment
4355/// started in.
4356fn assignment_call<'a>(
4357    op: AssignOp,
4358    lhs: &Filter,
4359    rhs: &'a Filter,
4360) -> (Option<&'a Filter>, Filter) {
4361    let lhs = Rc::new(lhs.clone());
4362    let call = |name: &str, args: Vec<Rc<Filter>>| Filter::Call(Rc::from(name), args);
4363    let operand = Box::new(Filter::Var(Rc::from(ASSIGN_OPERAND)));
4364    let dot = Box::new(Filter::Identity);
4365    let update = match op {
4366        AssignOp::Set => return (None, call("_assign", vec![lhs, Rc::new(rhs.clone())])),
4367        AssignOp::Update => return (None, call("_modify", vec![lhs, Rc::new(rhs.clone())])),
4368        AssignOp::Alt => Filter::Alt(dot, operand),
4369        AssignOp::Add => Filter::Bin(BinOp::Add, dot, operand),
4370        AssignOp::Sub => Filter::Bin(BinOp::Sub, dot, operand),
4371        AssignOp::Mul => Filter::Bin(BinOp::Mul, dot, operand),
4372        AssignOp::Div => Filter::Bin(BinOp::Div, dot, operand),
4373        AssignOp::Mod => Filter::Bin(BinOp::Mod, dot, operand),
4374    };
4375    (Some(rhs), call("_modify", vec![lhs, Rc::new(update)]))
4376}
4377
4378/// `..` as a path expression: `recurse(.[]?)`. The node itself comes out
4379/// first; descending through a path that is no longer intact refuses, as
4380/// EACH_OPT does.
4381fn recurse_paths(pre: &Tracked, val: &JqVal, out: PathSink) -> R<()> {
4382    // The NODE is what comes out, so `.. | anchor` sees the box; the traversal
4383    // walks the value inside it, so `paths` does not stop at the first commented
4384    // container.
4385    out(pre.clone(), val.clone())?;
4386    if !pre.intact(val) {
4387        return Err(not_intact_iterate(val));
4388    }
4389    match val.bare() {
4390        JqVal::Arr(a) => {
4391            for (i, e) in a.iter().enumerate() {
4392                recurse_paths(&pre.push(JqVal::num(i as f64), e), e, out)?;
4393            }
4394            Ok(())
4395        }
4396        JqVal::Obj(m) => {
4397            for (k, e) in m.iter() {
4398                recurse_paths(&pre.push(JqVal::Str(k.clone()), e), e, out)?;
4399            }
4400            Ok(())
4401        }
4402        _ => Ok(()),
4403    }
4404}
4405
4406fn recurse_paths_f(
4407    it: &Interp,
4408    f: &Filter,
4409    input: &JqVal,
4410    pre: &Tracked,
4411    val: &JqVal,
4412    env: &Env,
4413    out: PathSink,
4414) -> R<()> {
4415    out(pre.clone(), val.clone())?;
4416    eval_paths(it, f, input, pre, val, env, &mut |p, v| {
4417        recurse_paths_f(it, f, input, &p, &v, env, out)
4418    })
4419}
4420
4421/// Follow a `crate::jqval::Seg` path — the shape `crate::jq`'s translated
4422/// `Field` op carries — through a jq value.
4423///
4424/// The point is the RETURN: an object that comes back through this keeps its
4425/// document key order, where routing the same lookup through `serde_json` gives
4426/// it back alphabetised. Measured against `yq -o=json`, `.nested` over a YAML
4427/// mapping came back re-sorted before this existed.
4428pub fn get_seg_path(v: &JqVal, segs: &[crate::jqval::Seg]) -> Result<JqVal, String> {
4429    let mut cur = v.clone();
4430    for seg in segs {
4431        if matches!(cur, JqVal::Null) {
4432            return Ok(JqVal::Null);
4433        }
4434        let idx = match seg {
4435            crate::jqval::Seg::Key(k) => JqVal::str(k.as_str()),
4436            crate::jqval::Seg::Index(i) => JqVal::num(*i as f64),
4437        };
4438        cur = index_value(&cur, &idx).map_err(|e| e.to_message())?;
4439    }
4440    Ok(cur)
4441}
4442
4443/// `getpath`, as a value operation: `jv_getpath`, one `jv_get` per key. Through
4444/// `null` a string, number or slice key reads `null`; any other key refuses.
4445fn get_path(v: &JqVal, segs: &[JqVal]) -> R<JqVal> {
4446    let mut cur = v.clone();
4447    for s in segs {
4448        cur = index_value(&cur, s)?;
4449    }
4450    Ok(cur)
4451}
4452
4453/// `setpath`. Missing containers are created — an object for a string segment,
4454/// an array (null-padded) for a numeric one — which is what makes
4455/// `null | setpath(["a",1];9)` produce `{"a":[null,9]}`.
4456fn set_path(v: &JqVal, segs: &[JqVal], newv: JqVal) -> R<JqVal> {
4457    let Some((seg, rest)) = segs.split_first() else {
4458        return Ok(newv);
4459    };
4460    let original = v;
4461    // A YAML container being written INTO keeps its own metadata: `.a.b = 5`
4462    // over a commented document must not strip the document's comments. The
4463    // rebuilt container is re-boxed with the metadata the old one carried.
4464    let rebox = |built: JqVal| match v.meta() {
4465        Some(m) => JqVal::wrap(built, m.clone()),
4466        None => built,
4467    };
4468    let v = v.bare();
4469    match seg.bare() {
4470        JqVal::Str(k) => {
4471            let mut m = match v {
4472                JqVal::Obj(m) => m.as_ref().clone(),
4473                JqVal::Null => Vec::new(),
4474                other => {
4475                    return Err(JqErr::msg(format!(
4476                        "Cannot index {} with string{}",
4477                        other.type_name(),
4478                        paren_of(seg)
4479                    )))
4480                }
4481            };
4482            let old = m
4483                .iter()
4484                .find(|(ek, _)| ek == k)
4485                .map_or(JqVal::Null, |(_, x)| x.clone());
4486            let sub = set_path(&old, rest, newv)?;
4487            match m.iter_mut().find(|(ek, _)| ek == k) {
4488                Some(slot) => slot.1 = sub,
4489                None => m.push((k.clone(), sub)),
4490            }
4491            Ok(rebox(JqVal::obj(m)))
4492        }
4493        JqVal::Num(n, _) => {
4494            let mut a = match v {
4495                JqVal::Arr(a) => a.as_ref().clone(),
4496                JqVal::Null => Vec::new(),
4497                other => {
4498                    return Err(JqErr::msg(format!(
4499                        "Cannot index {} with number{}",
4500                        other.type_name(),
4501                        paren_of(seg)
4502                    )))
4503                }
4504            };
4505            // `jv_set` + `jv_array_set` (src/jv_aux.c, src/jv.c): NaN refuses, the
4506            // index is clamped to C `int` and truncated, a negative one counts
4507            // from the end, and one past `INT_MAX >> 2` refuses rather than
4508            // allocating the gap.
4509            if n.is_nan() {
4510                return Err(JqErr::msg("Cannot set array element at NaN index"));
4511            }
4512            let mut i = n.clamp(f64::from(i32::MIN), f64::from(i32::MAX)).trunc();
4513            if i < 0.0 {
4514                i += a.len() as f64;
4515                if i < 0.0 {
4516                    return Err(JqErr::msg("Out of bounds negative array index"));
4517                }
4518            }
4519            if i > f64::from(i32::MAX >> 2) {
4520                return Err(JqErr::msg("Array index too large"));
4521            }
4522            let i = i as usize;
4523            while a.len() <= i {
4524                a.push(JqVal::Null);
4525            }
4526            a[i] = set_path(&a[i].clone(), rest, newv)?;
4527            Ok(rebox(JqVal::arr(a)))
4528        }
4529        JqVal::Obj(_) => {
4530            // A `{"start":…,"end":…}` segment replaces an array SLICE.
4531            let a = match v {
4532                JqVal::Arr(a) => a.as_ref().clone(),
4533                JqVal::Null => Vec::new(),
4534                JqVal::Str(_) => return Err(JqErr::msg("Cannot update string slices")),
4535                other => {
4536                    return Err(JqErr::msg(format!(
4537                        "Cannot index {} with object{}",
4538                        other.type_name(),
4539                        paren_of(seg)
4540                    )))
4541                }
4542            };
4543            let (s, e) = slice_bounds(seg.obj_get("start"), seg.obj_get("end"), a.len())?;
4544            let cur = JqVal::arr(a[s..e].to_vec());
4545            let sub = set_path(&cur, rest, newv)?;
4546            let JqVal::Arr(repl) = sub else {
4547                return Err(JqErr::msg(
4548                    "A slice of an array can only be assigned another array",
4549                ));
4550            };
4551            // jq writes nothing when the slice is empty and so is the insertion, so
4552            // the array it answers is the very one it was given.
4553            if s == e && repl.is_empty() {
4554                return Ok(match original.bare() {
4555                    JqVal::Arr(_) => original.clone(),
4556                    _ => rebox(JqVal::arr(a)),
4557                });
4558            }
4559            let mut out = a[..s].to_vec();
4560            out.extend(repl.iter().cloned());
4561            out.extend(a[e..].iter().cloned());
4562            Ok(rebox(JqVal::arr(out)))
4563        }
4564        // `jv_setpath`: `jv_get` reads the child first (its refusal wins),
4565        // then `jv_set` refuses a key kind it cannot store — before the rest
4566        // of the path is ever set.
4567        other => {
4568            index_value(v, seg)?;
4569            Err(JqErr::msg(format!(
4570                "Cannot update field at {} index of {}",
4571                other.type_name(),
4572                v.type_name()
4573            )))
4574        }
4575    }
4576}
4577
4578/// `delpaths(paths)` over a jq VALUE: it must be an array of arrays.
4579fn delpaths_value(v: &JqVal, paths: &JqVal) -> R<JqVal> {
4580    let JqVal::Arr(list) = paths else {
4581        return Err(JqErr::msg("Paths must be specified as an array"));
4582    };
4583    // `jv_delpaths` sorts the paths BEFORE it checks that each is an array, so
4584    // the offender it names is the first one in sort order.
4585    let mut sorted: Vec<&JqVal> = list.iter().collect();
4586    sorted.sort_by(|a, b| cmp_sort(a, b));
4587    let mut out = Vec::with_capacity(sorted.len());
4588    for e in sorted {
4589        match e {
4590            JqVal::Arr(segs) => out.push(segs.as_ref().clone()),
4591            other => {
4592                return Err(JqErr::msg(format!(
4593                    "Path must be specified as array, not {}",
4594                    other.type_name()
4595                )))
4596            }
4597        }
4598    }
4599    del_paths(v, out)
4600}
4601
4602/// `delpaths` — a port of `jv_delpaths` (src/jv_aux.c). The paths are sorted,
4603/// an empty path deletes everything, and `delpaths_sorted` walks them grouped
4604/// by their leading key so that every key of one container is removed in a
4605/// single `jv_dels` call, against the ORIGINAL indices.
4606fn del_paths(v: &JqVal, mut paths: Vec<Vec<JqVal>>) -> R<JqVal> {
4607    paths.sort_by(|a, b| cmp_sort(&JqVal::arr(a.clone()), &JqVal::arr(b.clone())));
4608    match paths.first() {
4609        None => Ok(v.clone()),
4610        Some(p) if p.is_empty() => Ok(JqVal::Null),
4611        Some(_) => delpaths_sorted(v, &paths, 0),
4612    }
4613}
4614
4615/// `delpaths_sorted`: `paths` share their first `start` keys and are sorted,
4616/// so the paths through one key are adjacent. A path that ENDS at a key deletes
4617/// it whole; the others recurse into the value under it.
4618fn delpaths_sorted(object: &JqVal, paths: &[Vec<JqVal>], start: usize) -> R<JqVal> {
4619    let mut object = object.clone();
4620    let mut delkeys = Vec::new();
4621    let mut i = 0;
4622    while i < paths.len() {
4623        let key = &paths[i][start];
4624        let delkey = paths[i].len() == start + 1;
4625        let mut j = i + 1;
4626        while j < paths.len() && cmp_vals(key, &paths[j][start]) == Ordering::Equal {
4627            j += 1;
4628        }
4629        if delkey {
4630            delkeys.push(key.clone());
4631        } else {
4632            let sub = index_value(&object, key)?;
4633            if !matches!(sub.bare(), JqVal::Null) {
4634                let newsub = delpaths_sorted(&sub, &paths[i..j], start + 1)?;
4635                object = set_path(&object, std::slice::from_ref(key), newsub)?;
4636            }
4637        }
4638        i = j;
4639    }
4640    jv_dels(&object, &delkeys)
4641}
4642
4643/// `jv_dels`: remove every key in `keys` from one container at once. On an
4644/// array the indices all refer to the original positions — a NaN index
4645/// deletes nothing, a negative one counts from the end, and a slice object
4646/// removes its `parse_slice` range. The container keeps its comments and
4647/// anchor, as in `set_path`.
4648fn jv_dels(t: &JqVal, keys: &[JqVal]) -> R<JqVal> {
4649    let rebox = |built: JqVal| match t.meta() {
4650        Some(m) => JqVal::wrap(built, m.clone()),
4651        None => built,
4652    };
4653    match t.bare() {
4654        _ if keys.is_empty() => Ok(t.clone()),
4655        JqVal::Null => Ok(t.clone()),
4656        JqVal::Arr(a) => {
4657            let len = a.len();
4658            let mut neg = Vec::new();
4659            let mut nonneg = Vec::new();
4660            let mut slices = Vec::new();
4661            for key in keys {
4662                match key.bare() {
4663                    JqVal::Num(n, _) if n.is_nan() => {}
4664                    JqVal::Num(n, _) if *n < 0.0 => neg.push(*n),
4665                    JqVal::Num(n, _) => nonneg.push(*n),
4666                    k @ JqVal::Obj(_) => {
4667                        slices.push(slice_bounds(k.obj_get("start"), k.obj_get("end"), len)?)
4668                    }
4669                    k => {
4670                        return Err(JqErr::msg(format!(
4671                            "Cannot delete {} element of array",
4672                            k.type_name()
4673                        )))
4674                    }
4675                }
4676            }
4677            // The C walks both sorted key lists alongside the array; `(int)`
4678            // truncates each index toward zero.
4679            let (mut ni, mut pi) = (0, 0);
4680            let mut out = Vec::with_capacity(len);
4681            for (i, e) in a.iter().enumerate() {
4682                let i = i as i64;
4683                let mut del = false;
4684                while ni < neg.len() {
4685                    let delidx = len as i64 + neg[ni] as i64;
4686                    del |= i == delidx;
4687                    if i < delidx {
4688                        break;
4689                    }
4690                    ni += 1;
4691                }
4692                while pi < nonneg.len() {
4693                    let delidx = nonneg[pi] as i64;
4694                    del |= i == delidx;
4695                    if i < delidx {
4696                        break;
4697                    }
4698                    pi += 1;
4699                }
4700                del |= slices.iter().any(|&(s, e)| s as i64 <= i && i < e as i64);
4701                if !del {
4702                    out.push(e.clone());
4703                }
4704            }
4705            Ok(rebox(JqVal::arr(out)))
4706        }
4707        JqVal::Obj(m) => {
4708            let mut dead: Vec<&str> = Vec::with_capacity(keys.len());
4709            for k in keys {
4710                match k.bare() {
4711                    JqVal::Str(s) => dead.push(s),
4712                    k => {
4713                        return Err(JqErr::msg(format!(
4714                            "Cannot delete {} field of object",
4715                            k.type_name()
4716                        )))
4717                    }
4718                }
4719            }
4720            Ok(rebox(JqVal::obj(
4721                m.iter()
4722                    .filter(|(ek, _)| !dead.contains(&&**ek))
4723                    .cloned()
4724                    .collect(),
4725            )))
4726        }
4727        other => Err(JqErr::msg(format!(
4728            "Cannot delete fields from {}",
4729            other.type_name()
4730        ))),
4731    }
4732}
4733
4734// ─────────────────────────────────────────────────────────────────────────────
4735// Assignment
4736// ─────────────────────────────────────────────────────────────────────────────
4737
4738/// The assignment family. Every form is defined in terms of `path`/`setpath`,
4739/// which is how jq defines them: `a = b` sets every path `a` names to each value
4740/// `b` produces, `a |= f` maps `f` over the value at each such path, and
4741/// `a op= b` is `a |= . op ($input | b)` with `b` seeing the ORIGINAL input.
4742/// One output of an update, in jq's `_modify` state `[value, deletions]`:
4743/// `$dot | setpath([0] + $p; $v)`. The first output of a path reads the state
4744/// (`literal`, or `None` while arb still keeps the value and the deletions
4745/// apart); `$$$$dot` is MOVED out when read, so every later output of the same
4746/// update starts from `null`.
4747fn modify_literal(literal: Option<&JqVal>, output: usize, path: &[JqVal], v: JqVal) -> R<JqVal> {
4748    let base = match (literal, output) {
4749        (Some(st), 1) => st.clone(),
4750        _ => JqVal::Null,
4751    };
4752    let mut at = vec![JqVal::num(0.0)];
4753    at.extend(path.iter().cloned());
4754    set_path(&base, &at, v)
4755}
4756
4757fn eval_assign(
4758    it: &Interp,
4759    op: AssignOp,
4760    lhs: &Filter,
4761    rhs: &Filter,
4762    input: &JqVal,
4763    env: &Env,
4764    out: Sink,
4765) -> R<()> {
4766    // yq's metadata assignment, recognised here because `anchor` and friends are
4767    // VALUE filters rather than paths — `eval_paths` would refuse them as a
4768    // left-hand side outright. `anchor = "x"` sets it on `.`; the whole-document
4769    // edit yq spells `.a anchor = "x"` is `.a |= (anchor = "x")`, which reaches
4770    // this with `.` bound to the node at the path.
4771    if op == AssignOp::Set {
4772        if let Some((path, name)) = meta_assign_target(lhs) {
4773            return eval(it, rhs, input, env, &mut |rv| match path {
4774                None => out(set_meta(input, name, &rv)),
4775                Some(p) => {
4776                    let mut cur = input.clone();
4777                    let mut paths = Vec::new();
4778                    eval_paths(
4779                        it,
4780                        p,
4781                        input,
4782                        &Tracked::root(input),
4783                        input,
4784                        env,
4785                        &mut |pp, v| {
4786                            let pp = intact_path(pp, &v)?;
4787                            paths.push(pp);
4788                            Ok(())
4789                        },
4790                    )?;
4791                    for pp in paths {
4792                        let at = get_path(&cur, &pp)?;
4793                        let set = set_meta(&at, name, &rv);
4794                        cur = if pp.is_empty() {
4795                            set
4796                        } else {
4797                            set_path(&cur, &pp, set)?
4798                        };
4799                    }
4800                    out(cur)
4801                }
4802            });
4803        }
4804    }
4805    if op == AssignOp::Update {
4806        let mut cur = input.clone();
4807        let mut paths = Vec::new();
4808        eval_paths(
4809            it,
4810            lhs,
4811            input,
4812            &Tracked::root(input),
4813            input,
4814            env,
4815            &mut |p, v| {
4816                let p = intact_path(p, &v)?;
4817                paths.push(p);
4818                Ok(())
4819            },
4820        )?;
4821        // jq's `_modify` DELETES a path whose update produced nothing — but it
4822        // collects those paths and deletes them all at the END. Deleting as it
4823        // went shifted every later array index down by one, so
4824        // `[1,2,3] | .[] |= empty` answered `[2]` instead of `[]`.
4825        //
4826        // The update runs as `(., break $out) as $v | setpath(…)`: each output is
4827        // stored and then a `break` ends the generator — the REST of it never
4828        // runs (`.[] |= (2, error("x"))` is fine). A `?//` inside the update
4829        // catches that break like any downstream error and offers its next
4830        // alternative; jq's `_modify` has already moved its `[value, deletions]`
4831        // state out by then, which `modify_literal` follows.
4832        let mut dead = Vec::new();
4833        let mut literal: Option<JqVal> = None;
4834        for p in paths {
4835            let old = match &literal {
4836                None => get_path(&cur, &p)?,
4837                Some(st) => get_path(&index_value(st, &JqVal::num(0.0))?, &p)?,
4838            };
4839            // `_modify`'s `label $out`, entered once per path.
4840            let id = it.next_label();
4841            let mut outputs = 0usize;
4842            let mut stored = None;
4843            let mut state = None;
4844            match eval(it, rhs, &old, env, &mut |v| {
4845                outputs += 1;
4846                if literal.is_none() && outputs == 1 {
4847                    stored = Some(set_path(&cur, &p, v)?);
4848                } else {
4849                    state = Some(modify_literal(literal.as_ref(), outputs, &p, v)?);
4850                }
4851                Err(JqErr::Break(id))
4852            }) {
4853                Ok(()) => {}
4854                Err(e) if breaks_to(&e, id) => {}
4855                Err(e) => return Err(e),
4856            }
4857            match (state, stored, &literal) {
4858                (Some(st), _, _) => literal = Some(st),
4859                (None, Some(next), _) => cur = next,
4860                (None, None, None) => dead.push(p),
4861                (None, None, Some(st)) => {
4862                    // The deletion mark: `setpath([1, (.[1] | length)]; $p)`.
4863                    let marks = index_value(st, &JqVal::num(1.0))?;
4864                    let n = match marks.bare() {
4865                        JqVal::Arr(a) => a.len(),
4866                        _ => 0,
4867                    };
4868                    let at = [JqVal::num(1.0), JqVal::num(n as f64)];
4869                    literal = Some(set_path(st, &at, JqVal::arr(p))?);
4870                }
4871            }
4872        }
4873        if let Some(st) = literal {
4874            // `$dot[0] | delpaths($dot[1])`
4875            let value = index_value(&st, &JqVal::num(0.0))?;
4876            let marks = index_value(&st, &JqVal::num(1.0))?;
4877            return out(delpaths_value(&value, &marks)?);
4878        }
4879        if !dead.is_empty() {
4880            cur = del_paths(&cur, dead)?;
4881        }
4882        return out(cur);
4883    }
4884    // The remaining forms evaluate the right-hand side against the ORIGINAL
4885    // input, once per output value, and each output value gives one result.
4886    eval(it, rhs, input, env, &mut |rv| {
4887        let mut cur = input.clone();
4888        let mut paths = Vec::new();
4889        eval_paths(
4890            it,
4891            lhs,
4892            input,
4893            &Tracked::root(input),
4894            input,
4895            env,
4896            &mut |p, v| {
4897                let p = intact_path(p, &v)?;
4898                paths.push(p);
4899                Ok(())
4900            },
4901        )?;
4902        for p in paths {
4903            // Every form but `=` is `_modify(lhs; . op $tmp)` in jq
4904            // (`gen_update`), whose `label $out` is entered once per path.
4905            if op != AssignOp::Set {
4906                it.next_label();
4907            }
4908            let newv = match op {
4909                AssignOp::Set => rv.clone(),
4910                AssignOp::Alt => {
4911                    let old = get_path(&cur, &p)?;
4912                    if old.truthy() {
4913                        old
4914                    } else {
4915                        rv.clone()
4916                    }
4917                }
4918                _ => {
4919                    let old = get_path(&cur, &p)?;
4920                    let bop = match op {
4921                        AssignOp::Add => BinOp::Add,
4922                        AssignOp::Sub => BinOp::Sub,
4923                        AssignOp::Mul => BinOp::Mul,
4924                        AssignOp::Div => BinOp::Div,
4925                        AssignOp::Mod => BinOp::Mod,
4926                        _ => unreachable!("Set/Alt/Update handled above"),
4927                    };
4928                    binop(bop, &old, &rv)?
4929                }
4930            };
4931            cur = set_path(&cur, &p, newv)?;
4932        }
4933        out(cur)
4934    })
4935}
4936
4937// ─────────────────────────────────────────────────────────────────────────────
4938// Calls
4939// ─────────────────────────────────────────────────────────────────────────────
4940
4941/// Resolve a call to a user function or closure argument: its body plus the
4942/// environment that body must run in.
4943fn bind_call(
4944    _it: &Interp,
4945    node: &Rc<FuncNode>,
4946    args: &[Rc<Filter>],
4947    caller: &Env,
4948) -> R<(Rc<Filter>, Env)> {
4949    match &node.kind {
4950        FnKind::Arg(f, aenv) => Ok((f.clone(), aenv.clone())),
4951        FnKind::User(def) => {
4952            // The body sees the definition's environment PLUS the function node
4953            // itself, which is what makes a recursive `def` need no fixed point.
4954            let mut env = Env {
4955                vars: node.vars.clone(),
4956                funcs: Some(node.clone()),
4957            };
4958            for (p, a) in def.params.iter().zip(args) {
4959                env = Env {
4960                    vars: env.vars.clone(),
4961                    funcs: Some(Rc::new(FuncNode {
4962                        name: p.clone(),
4963                        arity: 0,
4964                        kind: FnKind::Arg(a.clone(), caller.clone()),
4965                        next: env.funcs.clone(),
4966                        vars: env.vars.clone(),
4967                    })),
4968                };
4969            }
4970            Ok((def.body.clone(), env))
4971        }
4972    }
4973}
4974
4975fn eval_call(
4976    it: &Interp,
4977    name: &str,
4978    args: &[Rc<Filter>],
4979    input: &JqVal,
4980    env: &Env,
4981    out: Sink,
4982) -> R<()> {
4983    // `pick/1` is the ONE spelling jq and yq both define, and they take
4984    // different arguments: jq wants path expressions (`pick(.a, .b)`) and yq
4985    // wants an array of keys (`pick(["a","b"])`), which jq refuses outright.
4986    // The Rust arm decides by looking at the argument and calls jq's own
4987    // definition for jq's form — so the decision has to happen BEFORE the
4988    // definition lookup, or the definition always wins and yq's form is an
4989    // error.
4990    let collision = name == "pick" && args.len() == 1;
4991    if !collision {
4992        if let Some(node) = env.find_fn(name, args.len()) {
4993            let (body, benv) = bind_call(it, &node, args, env)?;
4994            return eval(it, &body, input, &benv, out);
4995        }
4996    }
4997    builtin(it, name, args, input, env, out)
4998}
4999
5000/// Evaluate `f` and require exactly one output — the shape every builtin that
5001/// takes a VALUE argument (rather than a filter) needs.
5002fn one(it: &Interp, f: &Filter, input: &JqVal, env: &Env) -> R<JqVal> {
5003    let mut got = None;
5004    eval(it, f, input, env, &mut |v| {
5005        if got.is_none() {
5006            // Unboxed: an ARGUMENT to a jq builtin is a value, and every builtin
5007            // reached through here is a value operation. The yq operators that
5008            // need the node itself are dispatched before `builtin` unboxes its
5009            // input, so none of them come through this path.
5010            got = Some(v.bare().clone());
5011        }
5012        Ok(())
5013    })?;
5014    got.ok_or_else(|| JqErr::msg("argument produced no value"))
5015}
5016
5017/// A string input, or jq's FIXED message for this builtin — the C builtins that
5018/// say e.g. "trim input must be a string" do not name the offending value.
5019fn str_or(v: &JqVal, msg: &str) -> R<Rc<str>> {
5020    match v.bare() {
5021        JqVal::Str(s) => Ok(s.clone()),
5022        _ => Err(JqErr::msg(msg)),
5023    }
5024}
5025
5026/// A libm argument, refused with jq's `<type> (<value>) number required`.
5027fn num_required(v: &JqVal) -> R<f64> {
5028    v.as_f64().ok_or_else(|| {
5029        let b = v.bare();
5030        JqErr::msg(format!("{}{} number required", b.type_name(), paren_of(b)))
5031    })
5032}
5033
5034/// `utf8bytelength`, with jq's "only strings have UTF-8 byte length" refusal.
5035fn utf8_len_input(v: &JqVal) -> R<f64> {
5036    match v.bare() {
5037        JqVal::Str(s) => Ok(s.len() as f64),
5038        other => Err(JqErr::msg(format!(
5039            "{}{} only strings have UTF-8 byte length",
5040            other.type_name(),
5041            paren_of(other)
5042        ))),
5043    }
5044}
5045
5046fn want_str(v: &JqVal, who: &str) -> R<Rc<str>> {
5047    match v.bare() {
5048        JqVal::Str(s) => Ok(s.clone()),
5049        other => Err(JqErr::msg(format!(
5050            "{}{} cannot be {who}",
5051            other.type_name(),
5052            paren_of(other)
5053        ))),
5054    }
5055}
5056
5057// ─────────────────────────────────────────────────────────────────────────────
5058// Builtins implemented in Rust
5059//
5060// Everything that jq implements in C lives here; everything jq defines in
5061// `src/builtin.jq` lives in `PRELUDE` below, transcribed from those definitions
5062// so the semantics come from jq's own source rather than from a paraphrase.
5063// ─────────────────────────────────────────────────────────────────────────────
5064
5065/// The libm entry points jq exposes that the `libc` crate does not declare on
5066/// every platform. Each is a pure `double -> double` (or `double, double`) C
5067/// function from `<math.h>`; declaring them here is the same binding `libc`
5068/// would provide, with no state and no allocation.
5069mod libm {
5070    extern "C" {
5071        pub fn lgamma(x: f64) -> f64;
5072        pub fn tgamma(x: f64) -> f64;
5073        pub fn erf(x: f64) -> f64;
5074        pub fn erfc(x: f64) -> f64;
5075        pub fn j0(x: f64) -> f64;
5076        pub fn j1(x: f64) -> f64;
5077        pub fn y0(x: f64) -> f64;
5078        pub fn y1(x: f64) -> f64;
5079        pub fn jn(n: i32, x: f64) -> f64;
5080        pub fn yn(n: i32, x: f64) -> f64;
5081        pub fn frexp(x: f64, exp: *mut i32) -> f64;
5082        pub fn modf(x: f64, iptr: *mut f64) -> f64;
5083        pub fn remainder(x: f64, y: f64) -> f64;
5084        pub fn fdim(x: f64, y: f64) -> f64;
5085        pub fn fmod(x: f64, y: f64) -> f64;
5086        pub fn nextafter(x: f64, y: f64) -> f64;
5087    }
5088}
5089
5090/// The builtins whose arguments are jq VALUE parameters, and the order jq
5091/// enumerates their combinations in. `Some(true)`: a C function, whose LAST
5092/// argument varies slowest (`[pow(2,3;2,4)]` is `[4,9,16,81]`, measured against
5093/// jq 1.8.2). `Some(false)`: a `def f($a; $b)` from jq's `builtin.jq`, which
5094/// binds left to right so the FIRST varies slowest (`[range(1,2;3,4)]` is
5095/// `[1,2,1,2,3,2,2,3]`). Builtins whose arguments are closures (`limit`,
5096/// `sub`'s replacement, `path`) are not listed: they consume the generator
5097/// themselves.
5098fn value_param_order(name: &str, arity: usize) -> Option<bool> {
5099    match (name, arity) {
5100        ("range", 2) | ("range", 3) => Some(false),
5101        ("split", 1)
5102        | ("startswith", 1)
5103        | ("endswith", 1)
5104        | ("_strindices", 1)
5105        | ("setpath", 2)
5106        | ("delpaths", 1)
5107        | ("has", 1)
5108        | ("contains", 1)
5109        | ("bsearch", 1)
5110        | ("strftime", 1)
5111        | ("strflocaltime", 1)
5112        | ("strptime", 1)
5113        | ("format", 1)
5114        | ("halt_error", 1)
5115        | ("_match_impl", 3)
5116        | ("fma", 3) => Some(true),
5117        (
5118            "pow" | "atan2" | "fmin" | "fmax" | "ldexp" | "copysign" | "drem" | "fdim" | "fmod"
5119            | "hypot" | "nextafter" | "nexttoward" | "remainder" | "scalb" | "scalbln" | "jn"
5120            | "yn",
5121            2,
5122        ) => Some(true),
5123        _ => None,
5124    }
5125}
5126
5127/// Bind each argument of a value-parameter builtin in `order` (lazily, so an
5128/// argument that raises after yielding still lets the earlier combinations
5129/// answer first) and call it once per combination with literal arguments.
5130#[allow(clippy::too_many_arguments)]
5131fn value_param_product(
5132    it: &Interp,
5133    name: &str,
5134    args: &[Rc<Filter>],
5135    order: &[usize],
5136    bound: &mut Vec<JqVal>,
5137    input: &JqVal,
5138    env: &Env,
5139    out: Sink,
5140) -> R<()> {
5141    let Some((&i, rest)) = order.split_first() else {
5142        let lits: Vec<Rc<Filter>> = bound
5143            .iter()
5144            .map(|v| Rc::new(Filter::Lit(v.clone())))
5145            .collect();
5146        return builtin(it, name, &lits, input, env, out);
5147    };
5148    eval(it, &args[i], input, env, &mut |v| {
5149        bound[i] = v.bare().clone();
5150        value_param_product(it, name, args, rest, bound, input, env, out)
5151    })
5152}
5153
5154fn builtin(
5155    it: &Interp,
5156    name: &str,
5157    args: &[Rc<Filter>],
5158    input: &JqVal,
5159    env: &Env,
5160    out: Sink,
5161) -> R<()> {
5162    // The yq surface is the ONLY thing that may look at the node box, so it is
5163    // dispatched first, with `input` still wrapped. Everything below is a jq
5164    // builtin whose answer is about the VALUE, so it runs against the unboxed
5165    // one — that is what keeps a commented YAML scalar behaving in `sort`,
5166    // `tostring` and `+` exactly as the same scalar read from JSON does.
5167    if is_yq_builtin(name, args.len()) {
5168        return yq_builtin(it, name, args, input, env, out);
5169    }
5170    // A VALUE parameter that yields several values runs the builtin once per
5171    // combination, as jq does (`has("a","b")` is `true, false`). Once every
5172    // argument is a literal the call proceeds below as a plain one.
5173    if let Some(last_outer) = value_param_order(name, args.len()) {
5174        if !args.iter().all(|a| matches!(**a, Filter::Lit(_))) {
5175            let order: Vec<usize> = if last_outer {
5176                (0..args.len()).rev().collect()
5177            } else {
5178                (0..args.len()).collect()
5179            };
5180            let mut bound = vec![JqVal::Null; args.len()];
5181            return value_param_product(it, name, args, &order, &mut bound, input, env, out);
5182        }
5183    }
5184    let input = input.bare();
5185    match (name, args.len()) {
5186        ("empty", 0) => Ok(()),
5187        ("error", 0) => Err(JqErr::Err(input.clone())),
5188        ("error", 1) => eval(it, &args[0], input, env, &mut |m| Err(JqErr::Err(m))),
5189        ("not", 0) => out(JqVal::Bool(!input.truthy())),
5190        ("type", 0) => out(JqVal::str(input.type_name())),
5191
5192        ("length", 0) => out(match input {
5193            JqVal::Null => JqVal::num(0.0),
5194            JqVal::Bool(_) => {
5195                return Err(JqErr::msg(format!(
5196                    "{}{} has no length",
5197                    input.type_name(),
5198                    paren_of(input)
5199                )))
5200            }
5201            // `jv_number_abs`: a literal drops its sign as a decNumber
5202            // (`decNumberAbs`), which is what negating it already does.
5203            JqVal::Num(n, lit) if n.is_sign_negative() => negate_num(*n, lit),
5204            JqVal::Num(..) => input.clone(),
5205            JqVal::Str(s) => JqVal::num(s.chars().count() as f64),
5206            JqVal::Arr(a) => JqVal::num(a.len() as f64),
5207            JqVal::Obj(m) => JqVal::num(m.len() as f64),
5208            JqVal::Node(_) => unreachable!("bare() never returns a Node"),
5209        }),
5210        ("utf8bytelength", 0) => out(JqVal::num(utf8_len_input(input)?)),
5211
5212        ("keys", 0) | ("keys_unsorted", 0) => {
5213            let mut ks = match input {
5214                JqVal::Obj(m) => m
5215                    .iter()
5216                    .map(|(k, _)| JqVal::Str(k.clone()))
5217                    .collect::<Vec<_>>(),
5218                JqVal::Arr(a) => (0..a.len()).map(|i| JqVal::num(i as f64)).collect(),
5219                other => {
5220                    return Err(JqErr::msg(format!(
5221                        "{}{} has no keys",
5222                        other.type_name(),
5223                        paren_of(other)
5224                    )))
5225                }
5226            };
5227            if name == "keys" {
5228                ks.sort_by(cmp_sort);
5229            }
5230            out(JqVal::arr(ks))
5231        }
5232        ("has", 1) => {
5233            let k = one(it, &args[0], input, env)?;
5234            out(JqVal::Bool(match (input, &k) {
5235                // `jv_has`: null has no key of any type, and says so quietly.
5236                (JqVal::Null, _) => false,
5237                (JqVal::Obj(_), JqVal::Str(s)) => input.obj_get(s).is_some(),
5238                (JqVal::Arr(a), JqVal::Num(n, _)) => *n >= 0.0 && (*n as usize) < a.len(),
5239                (a, b) => {
5240                    return Err(JqErr::msg(format!(
5241                        "Cannot check whether {} has a {} key",
5242                        a.type_name(),
5243                        b.type_name()
5244                    )))
5245                }
5246            }))
5247        }
5248        ("contains", 1) => {
5249            let b = one(it, &args[0], input, env)?;
5250            out(JqVal::Bool(contains(input, &b)?))
5251        }
5252
5253        ("tostring", 0) => out(to_string_val(input)),
5254        ("tojson", 0) => out(JqVal::str(render(input))),
5255        ("fromjson", 0) => {
5256            let JqVal::Str(s) = input.bare() else {
5257                return Err(JqErr::msg(format!(
5258                    "{}{} only strings can be parsed",
5259                    input.bare().type_name(),
5260                    paren_of(input.bare())
5261                )));
5262            };
5263            // jq's own reader (`jv_parse.c`), so what it accepts and the
5264            // refusal it words are both jq's. The refusal quotes the text with a C
5265            // `%s`, which stops at the first NUL.
5266            let shown = s.split('\0').next().unwrap_or_default();
5267            out(crate::jvparse::parse(s)
5268                .map_err(|e| JqErr::msg(format!("{e} (while parsing '{shown}')")))?)
5269        }
5270        ("tonumber", 0) => match input {
5271            JqVal::Num(..) => out(input.clone()),
5272            // jq 1.8 keeps the text as the number's literal, so `"1.000"` is
5273            // printed `1.000` and `"1e2"` `1E+2`, as a literal in a program is.
5274            JqVal::Str(s) => match s.parse::<f64>() {
5275                Ok(n) => out(num_from_literal(n, s)),
5276                Err(_) => Err(JqErr::msg(format!(
5277                    "{}{} cannot be parsed as a number",
5278                    input.type_name(),
5279                    paren_of(input)
5280                ))),
5281            },
5282            other => Err(JqErr::msg(format!(
5283                "{}{} cannot be parsed as a number",
5284                other.type_name(),
5285                paren_of(other)
5286            ))),
5287        },
5288        ("explode", 0) => out(JqVal::arr(
5289            str_or(input, "explode input must be a string")?
5290                .chars()
5291                .map(|c| JqVal::num(c as u32 as f64))
5292                .collect(),
5293        )),
5294        ("implode", 0) => {
5295            let JqVal::Arr(a) = input else {
5296                return Err(JqErr::msg("implode input must be an array"));
5297            };
5298            let mut s = String::with_capacity(a.len());
5299            for e in a.iter() {
5300                // `f_string_implode` refuses a NaN code point like a non-number.
5301                let n = e.as_f64().filter(|n| !n.is_nan()).ok_or_else(|| {
5302                    JqErr::msg(format!(
5303                        "{}{} can't be imploded, unicode codepoint needs to be numeric",
5304                        e.type_name(),
5305                        paren_of(e)
5306                    ))
5307                })?;
5308                // jq 1.8 truncates to `int` first (`-0.25` is the NUL character), then
5309                // writes U+FFFD for a code point that is not a Unicode scalar value
5310                // -- negative, a surrogate, or past U+10FFFF.
5311                let cp = n as i32;
5312                let scalar = u32::try_from(cp).ok().and_then(char::from_u32);
5313                s.push(scalar.unwrap_or('\u{FFFD}'));
5314            }
5315            out(JqVal::str(s))
5316        }
5317        ("ascii_downcase", 0) => out(JqVal::str(
5318            str_or(input, "explode input must be a string")?.to_ascii_lowercase(),
5319        )),
5320        ("ascii_upcase", 0) => out(JqVal::str(
5321            str_or(input, "explode input must be a string")?.to_ascii_uppercase(),
5322        )),
5323        ("startswith", 1) | ("endswith", 1) => {
5324            let pre = one(it, &args[0], input, env)?;
5325            match (input, &pre) {
5326                (JqVal::Str(s), JqVal::Str(p)) => out(JqVal::Bool(if name == "startswith" {
5327                    s.starts_with(&**p)
5328                } else {
5329                    s.ends_with(&**p)
5330                })),
5331                _ => Err(JqErr::msg(format!("{name}() requires string inputs"))),
5332            }
5333        }
5334        ("ltrim", 0) | ("rtrim", 0) | ("trim", 0) => {
5335            let s = str_or(input, "trim input must be a string")?;
5336            let trimmed = match name {
5337                "ltrim" => s.trim_start(),
5338                "rtrim" => s.trim_end(),
5339                _ => s.trim(),
5340            };
5341            // Nothing to trim: jq hands back the input string itself.
5342            out(if trimmed.len() == s.len() {
5343                JqVal::Str(s)
5344            } else {
5345                JqVal::str(trimmed)
5346            })
5347        }
5348        ("split", 1) => {
5349            let sep = one(it, &args[0], input, env)?;
5350            let s = str_or(input, "split input and separator must be strings")?;
5351            let sep = str_or(&sep, "split input and separator must be strings")?;
5352            out(JqVal::arr(split_str(&s, &sep)))
5353        }
5354        ("_strindices", 1) => {
5355            let needle = one(it, &args[0], input, env)?;
5356            // `f_string_indexes`: the input refuses first, then the needle.
5357            let h = want_str(input, "searched, as it is not a string")?;
5358            let JqVal::Str(n) = needle.bare().clone() else {
5359                return Err(JqErr::msg(format!(
5360                    "{}{} is not a string",
5361                    needle.type_name(),
5362                    paren_of(&needle)
5363                )));
5364            };
5365            let mut hits = Vec::new();
5366            if !n.is_empty() {
5367                let mut from = 0usize;
5368                // jq 1.8 reports CODE-POINT offsets (1.7 reported bytes), and
5369                // overlapping hits count, so the scan resumes one character —
5370                // not one byte — past each hit.
5371                while let Some(off) = h[from..].find(&*n) {
5372                    let at = from + off;
5373                    hits.push(JqVal::num(cp_index(&h, at) as f64));
5374                    from = at + h[at..].chars().next().map_or(1, char::len_utf8);
5375                }
5376            }
5377            out(JqVal::arr(hits))
5378        }
5379
5380        ("sort", 0) => {
5381            let a = want_arr(input, "sorted")?;
5382            let mut v = a.as_ref().clone();
5383            v.sort_by(cmp_sort);
5384            out(JqVal::arr(v))
5385        }
5386        // jq 1.8.2's `def reverse: [.[length - 1 - range(0;length)]];` -- so a
5387        // non-array with a length of zero (`null`, `""`, `{}`, `0`) is `[]`, and
5388        // any other input fails on its first INDEX (`"abc"` is `Cannot index
5389        // string with number (2)`) or on `length` itself (`true`).
5390        ("reverse", 0) => match input {
5391            JqVal::Arr(a) => out(JqVal::arr(a.iter().rev().cloned().collect())),
5392            other => {
5393                let mut len = 0.0;
5394                builtin(it, "length", &[], other, env, &mut |n| {
5395                    len = n.as_f64().unwrap_or(0.0);
5396                    Ok(())
5397                })?;
5398                if len > 0.0 {
5399                    index_value(other, &JqVal::num(len - 1.0))?;
5400                }
5401                out(JqVal::arr(Vec::new()))
5402            }
5403        },
5404        ("unique", 0) => {
5405            let mut v = want_arr(input, "sorted")?.as_ref().clone();
5406            v.sort_by(cmp_sort);
5407            v.dedup_by(|b, a| eq_vals(a, b));
5408            out(JqVal::arr(v))
5409        }
5410        ("sort_by", 1) | ("group_by", 1) | ("unique_by", 1) => {
5411            let keyed = keyed_elements(
5412                it,
5413                &args[0],
5414                input,
5415                env,
5416                "cannot be sorted, as they are not both arrays",
5417            )?;
5418            out(sort_family(name, keyed))
5419        }
5420        ("min_by", 1) | ("max_by", 1) => {
5421            let keyed = keyed_elements(it, &args[0], input, env, "cannot be iterated over")?;
5422            out(minmax_by(name == "min_by", keyed))
5423        }
5424        // The C halves of jq's `sort_by(f)` = `_sort_by_impl(map([f]))` family,
5425        // reached by the path-mode definitions of those builtins.
5426        ("_sort_by_impl", 1)
5427        | ("_group_by_impl", 1)
5428        | ("_unique_by_impl", 1)
5429        | ("_min_by_impl", 1)
5430        | ("_max_by_impl", 1) => {
5431            let keys = one(it, &args[0], input, env)?;
5432            let minmax = name.starts_with("_m");
5433            let pair_msg = if minmax {
5434                "cannot be iterated over"
5435            } else {
5436                "cannot be sorted, as they are not both arrays"
5437            };
5438            let (JqVal::Arr(a), JqVal::Arr(k)) = (input.bare(), keys.bare()) else {
5439                return Err(pair_error(input, &keys, pair_msg));
5440            };
5441            if a.len() != k.len() {
5442                return Err(pair_error(input, &keys, pair_msg));
5443            }
5444            let keyed: Vec<(JqVal, JqVal)> = k.iter().cloned().zip(a.iter().cloned()).collect();
5445            out(if minmax {
5446                minmax_by(name == "_min_by_impl", keyed)
5447            } else {
5448                sort_family(
5449                    name.trim_start_matches('_').trim_end_matches("_impl"),
5450                    keyed,
5451                )
5452            })
5453        }
5454        ("min", 0) | ("max", 0) => {
5455            // jq's `minmax_by(x, x)` names the input twice.
5456            let JqVal::Arr(a) = input else {
5457                return Err(JqErr::msg(format!(
5458                    "{}{} and {}{} cannot be iterated over",
5459                    input.type_name(),
5460                    paren_of(input),
5461                    input.type_name(),
5462                    paren_of(input)
5463                )));
5464            };
5465            let best = if name == "min" {
5466                a.iter().cloned().reduce(|x, y| {
5467                    if cmp_vals(&y, &x) == Ordering::Less {
5468                        y
5469                    } else {
5470                        x
5471                    }
5472                })
5473            } else {
5474                a.iter().cloned().reduce(|x, y| {
5475                    if cmp_vals(&y, &x) == Ordering::Less {
5476                        x
5477                    } else {
5478                        y
5479                    }
5480                })
5481            };
5482            out(best.unwrap_or(JqVal::Null))
5483        }
5484
5485        ("range", 2) | ("range", 3) => {
5486            let from = one(it, &args[0], input, env)?;
5487            let upto = one(it, &args[1], input, env)?;
5488            let Some(by) = args.get(2) else {
5489                // range/2 is jq's RANGE opcode (src/execute.c): both bounds must
5490                // be numbers, and it stops on the raw C `x >= upto`, so a NaN
5491                // on either side never stops (`limit(3; range(0; nan))` is
5492                // `[0,1,2]`).
5493                let (Some(mut x), Some(u)) = (from.as_f64(), upto.as_f64()) else {
5494                    return Err(JqErr::msg("Range bounds must be numeric"));
5495                };
5496                // `!(x >= u)` in C: true for x < u and for NaN on either side. The
5497                // first output is the lower bound itself, literal text and all
5498                // (`range(1e1000; nan)` starts at `1E+1000`).
5499                let mut first = Some(from.bare().clone());
5500                while x < u || x.is_nan() || u.is_nan() {
5501                    out(first.take().unwrap_or_else(|| JqVal::num(x)))?;
5502                    x += 1.0;
5503                }
5504                return Ok(());
5505            };
5506            // range/3 is jq-coded (src/builtin.jq): `if $by > 0 then
5507            // $init|while(. < $upto; . + $by) elif $by < 0 then
5508            // $init|while(. > $upto; . + $by) else empty end`. Its compares
5509            // and its `+` are jq's, so any types are accepted, NaN orders below
5510            // every number, and a bad `$by` raises from the `+`.
5511            let by = one(it, by, input, env)?;
5512            let zero = JqVal::num(0.0);
5513            let keep_going = match cmp_vals(&by, &zero) {
5514                Ordering::Greater => Ordering::Less,
5515                Ordering::Less => Ordering::Greater,
5516                Ordering::Equal => return Ok(()),
5517            };
5518            let mut x = from;
5519            while cmp_vals(&x, &upto) == keep_going {
5520                out(x.clone())?;
5521                x = binop(BinOp::Add, &x, &by)?;
5522            }
5523            Ok(())
5524        }
5525
5526        ("floor", 0)
5527        | ("ceil", 0)
5528        | ("round", 0)
5529        | ("sqrt", 0)
5530        | ("fabs", 0)
5531        | ("log", 0)
5532        | ("log2", 0)
5533        | ("log10", 0)
5534        | ("exp", 0)
5535        | ("exp2", 0)
5536        | ("exp10", 0)
5537        | ("trunc", 0)
5538        | ("cbrt", 0)
5539        | ("sin", 0)
5540        | ("cos", 0)
5541        | ("tan", 0)
5542        | ("asin", 0)
5543        | ("acos", 0)
5544        | ("atan", 0)
5545        | ("sinh", 0)
5546        | ("cosh", 0)
5547        | ("tanh", 0)
5548        | ("nearbyint", 0)
5549        | ("significand", 0)
5550        | ("logb", 0)
5551        | ("acosh", 0)
5552        | ("asinh", 0)
5553        | ("atanh", 0)
5554        | ("expm1", 0)
5555        | ("log1p", 0)
5556        | ("rint", 0)
5557        | ("gamma", 0)
5558        | ("lgamma", 0)
5559        | ("tgamma", 0)
5560        | ("erf", 0)
5561        | ("erfc", 0)
5562        | ("j0", 0)
5563        | ("j1", 0)
5564        | ("y0", 0)
5565        | ("y1", 0) => {
5566            let n = input.as_f64().ok_or_else(|| {
5567                JqErr::msg(format!(
5568                    "{}{} number required",
5569                    input.type_name(),
5570                    paren_of(input)
5571                ))
5572            })?;
5573            out(JqVal::num(match name {
5574                "floor" => n.floor(),
5575                "ceil" => n.ceil(),
5576                "round" => n.round(),
5577                "sqrt" => n.sqrt(),
5578                "fabs" => n.abs(),
5579                "log" => n.ln(),
5580                "log2" => n.log2(),
5581                "log10" => n.log10(),
5582                "exp" => n.exp(),
5583                "exp2" => n.exp2(),
5584                "exp10" => 10f64.powf(n),
5585                "trunc" => n.trunc(),
5586                "cbrt" => n.cbrt(),
5587                "sin" => n.sin(),
5588                "cos" => n.cos(),
5589                "tan" => n.tan(),
5590                "asin" => n.asin(),
5591                "acos" => n.acos(),
5592                "atan" => n.atan(),
5593                "sinh" => n.sinh(),
5594                "cosh" => n.cosh(),
5595                "tanh" => n.tanh(),
5596                // `significand` and `logb` read the exponent `frexp` reports, which is
5597                // exact for subnormals where `log2` is not.
5598                "significand" if n == 0.0 || !n.is_finite() => n,
5599                "significand" => {
5600                    let mut e: i32 = 0;
5601                    // SAFETY: `e` is a live, correctly typed out-parameter.
5602                    unsafe { libm::frexp(n, &mut e) * 2.0 }
5603                }
5604                "logb" if n == 0.0 => f64::NEG_INFINITY,
5605                "logb" if n.is_nan() => n,
5606                "logb" if n.is_infinite() => f64::INFINITY,
5607                "logb" => {
5608                    let mut e: i32 = 0;
5609                    // SAFETY: as above.
5610                    unsafe { libm::frexp(n, &mut e) };
5611                    f64::from(e - 1)
5612                }
5613                "acosh" => n.acosh(),
5614                "asinh" => n.asinh(),
5615                "atanh" => n.atanh(),
5616                "expm1" => n.exp_m1(),
5617                "log1p" => n.ln_1p(),
5618                // `rint` and `nearbyint` round half to EVEN under the default
5619                // rounding mode, which is not `round`'s half-away-from-zero.
5620                "rint" | "nearbyint" => n.round_ties_even(),
5621                // SAFETY: each of these is a pure `double -> double` libm call.
5622                "lgamma" => unsafe { libm::lgamma(n) },
5623                // jq's `gamma` is `tgamma`, not the historical C alias for
5624                // `lgamma`: measured, `0.5 | gamma` is 1.7724538509055159.
5625                "gamma" | "tgamma" => unsafe { libm::tgamma(n) },
5626                "erf" => unsafe { libm::erf(n) },
5627                "erfc" => unsafe { libm::erfc(n) },
5628                "j0" => unsafe { libm::j0(n) },
5629                "j1" => unsafe { libm::j1(n) },
5630                "y0" => unsafe { libm::y0(n) },
5631                "y1" => unsafe { libm::y1(n) },
5632                _ => unreachable!("not a one-argument math builtin: {name}"),
5633            }))
5634        }
5635        // `frexp` and `modf` split a double into two parts, so they answer with a
5636        // two-element array rather than a number.
5637        ("frexp", 0) | ("modf", 0) | ("lgamma_r", 0) => {
5638            let n = num_required(input)?;
5639            let (a, b) = match name {
5640                "frexp" => {
5641                    let mut e: i32 = 0;
5642                    // SAFETY: `e` is a live, correctly typed out-parameter.
5643                    let m = unsafe { libm::frexp(n, &mut e) };
5644                    (m, f64::from(e))
5645                }
5646                "modf" => {
5647                    let mut i: f64 = 0.0;
5648                    // SAFETY: same — one out-parameter, one return value.
5649                    let f = unsafe { libm::modf(n, &mut i) };
5650                    (f, i)
5651                }
5652                // `lgamma_r` is the reentrant `lgamma` — the log-magnitude plus
5653                // the sign libm reports (builtin.c `LIBM_DA(lgamma_r, int)`).
5654                // It comes from the `libm` crate (musl's lgamma_r), not the
5655                // host libm: glibc's answer differs in the last ulp (`-180.5`
5656                // gives ...013 where Apple's libm, this crate and the jq 1.8.2
5657                // release binaries give ...015). Deriving the sign from
5658                // `tgamma` is wrong wherever `tgamma` underflows to zero. For
5659                // ±0 and NaN jq's sign depends on whether the libm writes it;
5660                // the jq 1.8.2 Linux release prints 1 there, and so does arb.
5661                _ => {
5662                    let (v, sign) = ::libm::lgamma_r(n);
5663                    let sign = if n == 0.0 || n.is_nan() { 1 } else { sign };
5664                    (v, f64::from(sign))
5665                }
5666            };
5667            out(JqVal::arr(vec![JqVal::num(a), JqVal::num(b)]))
5668        }
5669        ("isfinite", 0) => out(JqVal::Bool(input.as_f64().is_some_and(f64::is_finite))),
5670        ("format", 1) => {
5671            let f = one(it, &args[0], input, env)?;
5672            let JqVal::Str(f) = f.bare() else {
5673                return Err(JqErr::msg(format!(
5674                    "{}{} is not a valid format",
5675                    f.type_name(),
5676                    paren_of(f.bare())
5677                )));
5678            };
5679            out(JqVal::str(apply_format(f, input)?))
5680        }
5681        ("pow", 2)
5682        | ("atan2", 2)
5683        | ("fmin", 2)
5684        | ("fmax", 2)
5685        | ("ldexp", 2)
5686        | ("copysign", 2)
5687        | ("drem", 2)
5688        | ("fdim", 2)
5689        | ("fmod", 2)
5690        | ("hypot", 2)
5691        | ("nextafter", 2)
5692        | ("nexttoward", 2)
5693        | ("remainder", 2)
5694        | ("scalb", 2)
5695        | ("scalbln", 2)
5696        | ("jn", 2)
5697        | ("yn", 2) => {
5698            let a = num_required(&one(it, &args[0], input, env)?)?;
5699            let b = num_required(&one(it, &args[1], input, env)?)?;
5700            out(JqVal::num(match name {
5701                "pow" => a.powf(b),
5702                "atan2" => a.atan2(b),
5703                "fmin" => a.min(b),
5704                "fmax" => a.max(b),
5705                "hypot" => a.hypot(b),
5706                "copysign" => a.copysign(b),
5707                // SAFETY: pure libm calls on plain doubles.
5708                "drem" | "remainder" => unsafe { libm::remainder(a, b) },
5709                "fdim" => unsafe { libm::fdim(a, b) },
5710                "fmod" => unsafe { libm::fmod(a, b) },
5711                "nextafter" | "nexttoward" => unsafe { libm::nextafter(a, b) },
5712                "jn" => unsafe { libm::jn(a as i32, b) },
5713                "yn" => unsafe { libm::yn(a as i32, b) },
5714                // `ldexp`/`scalb`/`scalbln` all scale the FIRST argument by a
5715                // power of two. Measured against jq 1.8.2: `ldexp(2;3)` is 16 and
5716                // `scalb(3;2)` is 12, so both are `a * 2^b` — not C's
5717                // `ldexp(value, exp)` argument order.
5718                _ => a * 2f64.powi(b as i32),
5719            }))
5720        }
5721        ("fma", 3) => {
5722            let g = |i: usize| -> R<f64> { num_required(&one(it, &args[i], input, env)?) };
5723            out(JqVal::num(g(0)?.mul_add(g(1)?, g(2)?)))
5724        }
5725        ("infinite", 0) => out(JqVal::num(f64::INFINITY)),
5726        ("nan", 0) => out(JqVal::num(f64::NAN)),
5727        ("isnan", 0) => out(JqVal::Bool(input.as_f64().is_some_and(f64::is_nan))),
5728        ("isinfinite", 0) => out(JqVal::Bool(input.as_f64().is_some_and(f64::is_infinite))),
5729        ("isnormal", 0) => out(JqVal::Bool(input.as_f64().is_some_and(f64::is_normal))),
5730
5731        // Each path is emitted as it is found, so one that is not intact refuses
5732        // AFTER the paths before it have gone out.
5733        ("path", 1) => eval_paths(
5734            it,
5735            &args[0],
5736            input,
5737            &Tracked::root(input),
5738            input,
5739            env,
5740            &mut |p, v| out(JqVal::arr(intact_path(p, &v)?)),
5741        ),
5742        ("getpath", 1) => eval(it, &args[0], input, env, &mut |p| {
5743            let JqVal::Arr(segs) = &p else {
5744                return Err(JqErr::msg("Path must be specified as an array"));
5745            };
5746            out(get_path(input, segs)?)
5747        }),
5748        ("setpath", 2) => {
5749            let p = one(it, &args[0], input, env)?;
5750            let v = one(it, &args[1], input, env)?;
5751            let JqVal::Arr(segs) = &p else {
5752                return Err(JqErr::msg("Path must be specified as an array"));
5753            };
5754            out(set_path(input, segs, v)?)
5755        }
5756        ("delpaths", 1) => {
5757            let p = one(it, &args[0], input, env)?;
5758            out(delpaths_value(input, &p)?)
5759        }
5760        ("_flatten", 1) => {
5761            // builtin.jq: `def flatten($x): if $x < 0 then error(…) else
5762            // _flatten($x) end`. The guard is jq's ORDER, not a number check:
5763            // null, booleans and NaN sort below 0 and count as negative; a
5764            // string, array or object sorts above it and reaches `_flatten`,
5765            // where `$x - 1` refuses on the first nested array.
5766            let d = one(it, &args[0], input, env)?;
5767            if cmp_vals(&d, &JqVal::num(0.0)) == Ordering::Less {
5768                return Err(JqErr::msg("flatten depth must not be negative"));
5769            }
5770            // jq's `flatten` is `reduce .[] as $i (…)`, so its TOP level iterates
5771            // an object as well as an array (`{"a":[1,[2]]} | flatten` is
5772            // `[1,2]`); only the RECURSION is array-only. Same rule here, and the
5773            // refusal is the iterate error jq raises, not an array-only one.
5774            let top: Vec<JqVal> = match input.bare() {
5775                JqVal::Arr(a) => a.as_ref().clone(),
5776                JqVal::Obj(m) => m.iter().map(|(_, v)| v.clone()).collect(),
5777                other => {
5778                    return Err(JqErr::msg(format!(
5779                        "Cannot iterate over {}{}",
5780                        other.type_name(),
5781                        paren_of(other)
5782                    )))
5783                }
5784            };
5785            let mut res = Vec::new();
5786            flatten_into(&top, &d, &mut res)?;
5787            out(JqVal::arr(res))
5788        }
5789
5790        ("_match_impl", 3) => {
5791            let re = one(it, &args[0], input, env)?;
5792            let flags = one(it, &args[1], input, env)?;
5793            let testmode = one(it, &args[2], input, env)?;
5794            out(regex_match(input, &re, &flags, testmode.truthy())?)
5795        }
5796        ("splits_impl", 2) | ("_split_re", 2) => {
5797            let re = one(it, &args[0], input, env)?;
5798            let flags = one(it, &args[1], input, env)?;
5799            out(regex_split(input, &re, &flags)?)
5800        }
5801        ("sub_impl", 3) => {
5802            // The replacement is a FILTER run with the capture object as `.`, so
5803            // it must stay unevaluated until each match is known.
5804            let re = one(it, &args[0], input, env)?;
5805            let flags = one(it, &args[2], input, env)?;
5806            regex_sub(it, input, &re, &args[1], &flags, env, out)
5807        }
5808
5809        ("env", 0) => out(it.env_object()),
5810        // `gen_builtin_list` lists with `block_list_funcs(builtins, 1)`:
5811        // names starting with `_` are internal and omitted.
5812        ("builtins", 0) => out(JqVal::arr(
5813            builtin_names()
5814                .into_iter()
5815                .filter(|n| !n.starts_with('_'))
5816                .map(JqVal::str)
5817                .collect(),
5818        )),
5819        ("input", 0) => match it.next_input() {
5820            Some(v) => out(v),
5821            // jq 1.8's `f_input` raises the bare word `break`, which is what
5822            // its `def inputs` catches.
5823            None => Err(JqErr::msg("break")),
5824        },
5825        ("inputs", 0) => loop {
5826            match it.next_input() {
5827                Some(v) => out(v)?,
5828                None => return Ok(()),
5829            }
5830        },
5831        ("input_line_number", 0) => out(JqVal::num(it.line.get())),
5832        ("debug", 0) => {
5833            eprintln!("[\"DEBUG:\",{}]", render(input));
5834            out(input.clone())
5835        }
5836        ("debug", 1) => {
5837            eval(it, &args[0], input, env, &mut |m| {
5838                eprintln!("[\"DEBUG:\",{}]", render(&m));
5839                Ok(())
5840            })?;
5841            out(input.clone())
5842        }
5843        // main.c stderr_cb: a string is written raw, anything else as compact
5844        // JSON, with no trailing newline either way.
5845        ("stderr", 0) => {
5846            match input {
5847                JqVal::Str(s) => eprint!("{s}"),
5848                _ => eprint!("{}", render(input)),
5849            }
5850            out(input.clone())
5851        }
5852        ("halt", 0) => Err(JqErr::Halt(0, None)),
5853        ("halt_error", 0) => Err(JqErr::Halt(5, Some(input.clone()))),
5854        ("halt_error", 1) => {
5855            let code = one(it, &args[0], input, env)?
5856                .as_f64()
5857                .ok_or_else(|| JqErr::msg("halt_error/1: number required"))?;
5858            Err(JqErr::Halt(code as i32, Some(input.clone())))
5859        }
5860        // Every stream arb reads is its standard input, which jq names `<stdin>`
5861        // once it has read from it; before any input, there is no file.
5862        ("input_filename", 0) => out(if it.current_doc().is_some() {
5863            JqVal::str("<stdin>")
5864        } else {
5865            JqVal::Null
5866        }),
5867        // jq's module-system introspection. arb has no jq module search path —
5868        // its own `import` is the arb preset system — so the two path builtins
5869        // report where the program came from and the search list is empty.
5870        ("get_jq_origin", 0) => out(JqVal::str("arb")),
5871        ("get_prog_origin", 0) => out(JqVal::str(".")),
5872        ("get_search_list", 0) => out(JqVal::arr(Vec::new())),
5873        ("modulemeta", 0) => match input {
5874            JqVal::Str(s) => Err(JqErr::msg(format!("module not found: {s}"))),
5875            _ => Err(JqErr::msg("modulemeta input module name must be a string")),
5876        },
5877        ("have_literal_numbers", 0) => out(JqVal::Bool(true)),
5878        // jq 1.8.2 is built with decNumber, and arb keeps its number model:
5879        // literals survive unmodified values, negate exactly and compare as
5880        // decimals (`num_from_literal`, `negate_num`, `cmp_decimal`).
5881        ("have_decnum", 0) => out(JqVal::Bool(true)),
5882        ("$__loc__", 0) => out(JqVal::obj(vec![
5883            (Rc::from("file"), JqVal::str("<top-level>")),
5884            (Rc::from("line"), JqVal::num(1.0)),
5885        ])),
5886
5887        ("now", 0) => out(JqVal::num(unix_now())),
5888        ("mktime", 0) => out(JqVal::num(mktime(input)? as f64)),
5889        ("gmtime", 0) | ("localtime", 0) => {
5890            let t = input
5891                .as_f64()
5892                .ok_or_else(|| JqErr::msg(format!("{name}() requires numeric inputs")))?;
5893            out(broken_down(t, name == "localtime")?)
5894        }
5895        ("strftime", 1) | ("strflocaltime", 1) => {
5896            let f = one(it, &args[0], input, env)?;
5897            let f = str_or(&f, &format!("{name}/1 requires a string format"))?;
5898            out(JqVal::str(strftime_val(
5899                input,
5900                &f,
5901                name == "strflocaltime",
5902            )?))
5903        }
5904        ("strptime", 1) => {
5905            let f = one(it, &args[0], input, env)?;
5906            let f = str_or(&f, "strptime/1 requires string inputs and arguments")?;
5907            let s = str_or(input, "strptime/1 requires string inputs and arguments")?;
5908            out(strptime_val(&s, &f)?)
5909        }
5910
5911        _ => Err(JqErr::msg(format!("{name}/{} is not defined", args.len()))),
5912    }
5913}
5914
5915fn want_arr(v: &JqVal, who: &str) -> R<Rc<Vec<JqVal>>> {
5916    match v.bare() {
5917        JqVal::Arr(a) => Ok(a.clone()),
5918        other => Err(JqErr::msg(format!(
5919            "{}{} cannot be {who}, as it is not an array",
5920            other.type_name(),
5921            paren_of(other)
5922        ))),
5923    }
5924}
5925
5926/// jq's `type_error2` over the input and its key array.
5927fn pair_error(input: &JqVal, keys: &JqVal, msg: &str) -> JqErr {
5928    JqErr::msg(format!(
5929        "{}{} and {}{} {msg}",
5930        input.bare().type_name(),
5931        paren_of(input),
5932        keys.bare().type_name(),
5933        paren_of(keys)
5934    ))
5935}
5936
5937/// `sort_by`, `group_by` or `unique_by` over `(key, element)` pairs.
5938fn sort_family(name: &str, mut keyed: Vec<(JqVal, JqVal)>) -> JqVal {
5939    keyed.sort_by(|a, b| cmp_sort(&a.0, &b.0));
5940    match name {
5941        "sort_by" => JqVal::arr(keyed.into_iter().map(|(_, v)| v).collect()),
5942        "unique_by" => {
5943            let mut seen: Option<JqVal> = None;
5944            let mut res = Vec::new();
5945            for (k, v) in keyed {
5946                if seen.as_ref().is_none_or(|s| !eq_vals(s, &k)) {
5947                    res.push(v);
5948                    seen = Some(k);
5949                }
5950            }
5951            JqVal::arr(res)
5952        }
5953        _ => {
5954            let mut groups: Vec<JqVal> = Vec::new();
5955            let mut cur: Vec<JqVal> = Vec::new();
5956            let mut seen: Option<JqVal> = None;
5957            for (k, v) in keyed {
5958                if seen.as_ref().is_some_and(|s| !eq_vals(s, &k)) {
5959                    groups.push(JqVal::arr(std::mem::take(&mut cur)));
5960                }
5961                seen = Some(k);
5962                cur.push(v);
5963            }
5964            if seen.is_some() {
5965                groups.push(JqVal::arr(cur));
5966            }
5967            JqVal::arr(groups)
5968        }
5969    }
5970}
5971
5972/// `min_by` keeps the FIRST minimum and `max_by` the LAST maximum (measured
5973/// against jq 1.8.2), so the comparisons are not symmetric.
5974fn minmax_by(min: bool, keyed: Vec<(JqVal, JqVal)>) -> JqVal {
5975    let best = if min {
5976        keyed.into_iter().reduce(|a, b| {
5977            if cmp_vals(&b.0, &a.0) == Ordering::Less {
5978                b
5979            } else {
5980                a
5981            }
5982        })
5983    } else {
5984        keyed.into_iter().reduce(|a, b| {
5985            if cmp_vals(&b.0, &a.0) == Ordering::Less {
5986                a
5987            } else {
5988                b
5989            }
5990        })
5991    };
5992    best.map_or(JqVal::Null, |(_, v)| v)
5993}
5994
5995/// Pair every element of the input array with `[f]` evaluated over it — the key
5996/// array jq's `_sort_by_impl` family sorts on. An OBJECT survives jq's
5997/// `map([f])` (it maps the values) and is refused by the C implementation with
5998/// both operands named: `pair_msg` is that implementation's wording.
5999fn keyed_elements(
6000    it: &Interp,
6001    f: &Filter,
6002    input: &JqVal,
6003    env: &Env,
6004    pair_msg: &str,
6005) -> R<Vec<(JqVal, JqVal)>> {
6006    // jq runs `map([f])` first, so a scalar input fails as an ITERATION.
6007    if !matches!(input.bare(), JqVal::Arr(_) | JqVal::Obj(_)) {
6008        let b = input.bare();
6009        return Err(JqErr::msg(format!(
6010            "Cannot iterate over {}{}",
6011            b.type_name(),
6012            paren_of(b)
6013        )));
6014    }
6015    if let JqVal::Obj(m) = input.bare() {
6016        let mut keys = Vec::with_capacity(m.len());
6017        for (_, e) in m.iter() {
6018            let mut key = Vec::new();
6019            eval(it, f, e, env, &mut |k| {
6020                key.push(k);
6021                Ok(())
6022            })?;
6023            keys.push(JqVal::arr(key));
6024        }
6025        let keys = JqVal::arr(keys);
6026        return Err(JqErr::msg(format!(
6027            "{}{} and {}{} {pair_msg}",
6028            input.bare().type_name(),
6029            paren_of(input),
6030            keys.type_name(),
6031            paren_of(&keys)
6032        )));
6033    }
6034    let a = want_arr(input, "sorted")?;
6035    let mut keyed = Vec::with_capacity(a.len());
6036    for e in a.iter() {
6037        let mut key = Vec::new();
6038        eval(it, f, e, env, &mut |k| {
6039            key.push(k);
6040            Ok(())
6041        })?;
6042        keyed.push((JqVal::arr(key), e.clone()));
6043    }
6044    Ok(keyed)
6045}
6046
6047/// builtin.jq `_flatten($x)`: `reduce .[] as $i ([]; if $i | type == "array"
6048/// and $x != 0 then . + ($i | _flatten($x-1)) else . + [$i] end)`.
6049fn flatten_into(a: &[JqVal], depth: &JqVal, out: &mut Vec<JqVal>) -> R<()> {
6050    for e in a {
6051        // Whether an element RECURSES is about its value; what comes out is the
6052        // element itself, box and all.
6053        match e.bare() {
6054            JqVal::Arr(inner) if !eq_vals(depth, &JqVal::num(0.0)) => {
6055                let next = binop(BinOp::Sub, depth, &JqVal::num(1.0))?;
6056                flatten_into(inner, &next, out)?
6057            }
6058            _ => out.push(e.clone()),
6059        }
6060    }
6061    Ok(())
6062}
6063
6064/// jq's `contains` builtin (`f_contains`, src/builtin.c): the two TOP-LEVEL
6065/// values must share a jv kind — `true` and `false` are DIFFERENT kinds there,
6066/// so `true | contains(false)` raises — and only then is the recursive check run.
6067fn contains(a: &JqVal, b: &JqVal) -> R<bool> {
6068    let (a, b) = (a.bare(), b.bare());
6069    if jv_kind(a) != jv_kind(b) {
6070        return Err(JqErr::msg(format!(
6071            "{}{} and {}{} cannot have their containment checked",
6072            a.type_name(),
6073            paren_of(a),
6074            b.type_name(),
6075            paren_of(b)
6076        )));
6077    }
6078    contains_at(a, b, 0).ok_or_else(|| JqErr::msg("Containment check too deep"))
6079}
6080
6081/// jq's `MAX_CONTAINS_DEPTH` (src/jv.c).
6082const MAX_CONTAINS_DEPTH: usize = 10_000;
6083
6084/// Port of `jvp_contains` (src/jv.c). NESTED values of different kinds are
6085/// simply not contained — no error below the top level. `None` is jq's `-1`
6086/// ("too deep").
6087fn contains_at(a: &JqVal, b: &JqVal, depth: usize) -> Option<bool> {
6088    if depth > MAX_CONTAINS_DEPTH {
6089        return None;
6090    }
6091    let (a, b) = (a.bare(), b.bare());
6092    if jv_kind(a) != jv_kind(b) {
6093        return Some(false);
6094    }
6095    match (a, b) {
6096        // `jvp_object_contains`: every key of `b` must be present in `a` with a
6097        // containing value; a missing key reads as jq's INVALID, which no kind
6098        // matches.
6099        (JqVal::Obj(_), JqVal::Obj(bm)) => {
6100            for (k, bv) in bm.iter() {
6101                match a.obj_get(k) {
6102                    Some(av) => match contains_at(av, bv, depth + 1) {
6103                        Some(true) => {}
6104                        r => return r,
6105                    },
6106                    None => return Some(false),
6107                }
6108            }
6109            Some(true)
6110        }
6111        // `jvp_array_contains`: every element of `b` must be contained by SOME
6112        // element of `a`; a too-deep answer stops the scan.
6113        (JqVal::Arr(aa), JqVal::Arr(ba)) => {
6114            for bv in ba.iter() {
6115                let mut hit = Some(false);
6116                for av in aa.iter() {
6117                    hit = contains_at(av, bv, depth + 1);
6118                    if hit != Some(false) {
6119                        break;
6120                    }
6121                }
6122                if hit != Some(true) {
6123                    return hit;
6124                }
6125            }
6126            Some(true)
6127        }
6128        (JqVal::Str(x), JqVal::Str(y)) => Some(x.contains(&**y)),
6129        (x, y) => Some(eq_vals(x, y)),
6130    }
6131}
6132
6133/// jq's `jv_kind`: like `type`, except `true` and `false` are distinct kinds.
6134fn jv_kind(v: &JqVal) -> (&'static str, bool) {
6135    (v.type_name(), matches!(v.bare(), JqVal::Bool(true)))
6136}
6137// ─────────────────────────────────────────────────────────────────────────────
6138// ─────────────────────────────────────────────────────────────────────────────
6139// Regex builtins
6140//
6141// jq links Oniguruma and compiles every pattern with `ONIG_SYNTAX_PERL_NG` and
6142// `ONIG_OPTION_CAPTURE_GROUP` (src/builtin.c `f_match`). arb binds the same
6143// library, so look-around, backreferences, `\K`, subexpression calls, case
6144// folding and the engine's error text are jq's own rather than an emulation.
6145// ─────────────────────────────────────────────────────────────────────────────
6146
6147/// Compiled engines keyed by (pattern, option bits), with the compile FAILURE
6148/// cached alongside so a bad pattern raises on every call.
6149type ReCache = std::collections::HashMap<(String, u32), Result<Rc<onig::Regex>, String>>;
6150
6151/// Compile a jq regex + modifier string the way `f_match` does: each modifier
6152/// letter maps to one Oniguruma option, and any other letter refuses with the
6153/// WHOLE modifier string named.
6154fn compile_re(pat: &str, flags: &str) -> R<(Rc<onig::Regex>, bool)> {
6155    use onig::RegexOptions as O;
6156    thread_local! {
6157        /// A regex builtin runs once PER RECORD, so without this a
6158        /// `scan("[0-9]+")` over a stream recompiles the same pattern for
6159        /// every line.
6160        static RE_CACHE: RefCell<ReCache> = RefCell::new(ReCache::new());
6161    }
6162    let mut global = false;
6163    let mut opts = O::REGEX_OPTION_CAPTURE_GROUP;
6164    for f in flags.chars() {
6165        match f {
6166            'g' => global = true,
6167            'i' => opts |= O::REGEX_OPTION_IGNORECASE,
6168            'x' => opts |= O::REGEX_OPTION_EXTEND,
6169            'm' => opts |= O::REGEX_OPTION_MULTILINE,
6170            's' => opts |= O::REGEX_OPTION_SINGLELINE,
6171            'p' => opts |= O::REGEX_OPTION_MULTILINE | O::REGEX_OPTION_SINGLELINE,
6172            'l' => opts |= O::REGEX_OPTION_FIND_LONGEST,
6173            'n' => opts |= O::REGEX_OPTION_FIND_NOT_EMPTY,
6174            _ => {
6175                return Err(JqErr::msg(format!(
6176                    "{flags} is not a valid modifier string"
6177                )))
6178            }
6179        }
6180    }
6181    let key = (pat.to_string(), opts.bits());
6182    let cached = RE_CACHE.with(|c| c.borrow().get(&key).cloned());
6183    let entry = cached.unwrap_or_else(|| {
6184        let e = onig::Regex::with_options(pat, opts, onig::Syntax::perl_ng())
6185            .map(Rc::new)
6186            .map_err(|e| format!("Regex failure: {}", e.description()));
6187        RE_CACHE.with(|c| c.borrow_mut().insert(key, e.clone()));
6188        e
6189    });
6190    entry.map(|re| (re, global)).map_err(JqErr::msg)
6191}
6192
6193/// Byte offset -> code-point offset. jq reports both offsets and lengths in code
6194/// points, so every byte index a match reports has to be converted.
6195fn cp_index(s: &str, byte: usize) -> usize {
6196    s[..byte].chars().count()
6197}
6198
6199/// `f_match`'s argument checks (src/builtin.c): the regex and the modifiers
6200/// each refuse a non-string with `<type> (<value>) is not a string`; null
6201/// modifiers mean none.
6202fn re_args(re: &JqVal, flags: &JqVal) -> R<(Rc<str>, String)> {
6203    let not_string =
6204        |v: &JqVal| JqErr::msg(format!("{}{} is not a string", v.type_name(), paren_of(v)));
6205    let pat = match re.bare() {
6206        JqVal::Str(s) => s.clone(),
6207        other => return Err(not_string(other)),
6208    };
6209    let fl = match flags.bare() {
6210        JqVal::Null => String::new(),
6211        JqVal::Str(s) => s.to_string(),
6212        other => return Err(not_string(other)),
6213    };
6214    Ok((pat, fl))
6215}
6216
6217/// One match: the byte span of every group, group 0 first; `None` for a group
6218/// that did not take part.
6219type Spans = Vec<Option<(usize, usize)>>;
6220
6221/// `f_match`'s search loop. After a match it resumes at the match's END, or —
6222/// for an empty one — ONE BYTE past it, so over a multi-byte character the
6223/// scan keeps matching at the interior byte positions (`"😀" | [match("";"g") |
6224/// .offset]` is `[0,1,1,1,1]`). Measured against jq 1.8.2.
6225fn onig_scan(rx: &onig::Regex, s: &str, global: bool, first_only: bool) -> R<Vec<Spans>> {
6226    let mut hits = Vec::new();
6227    let mut region = onig::Region::new();
6228    let mut start = 0usize;
6229    loop {
6230        let found = rx.search_with_param(
6231            s,
6232            start,
6233            s.len(),
6234            onig::SearchOptions::SEARCH_OPTION_NONE,
6235            Some(&mut region),
6236            onig::MatchParam::default(),
6237        );
6238        match found {
6239            Ok(Some(_)) => {
6240                let spans: Spans = (0..region.len()).map(|g| region.pos(g)).collect();
6241                let (beg, end) = spans[0].expect("group 0 always participates");
6242                hits.push(spans);
6243                if first_only {
6244                    break;
6245                }
6246                start = if beg == end { end + 1 } else { end };
6247            }
6248            Ok(None) => break,
6249            Err(e) => return Err(JqErr::msg(format!("Regex failure: {}", e.description()))),
6250        }
6251        if !(global && start <= s.len()) {
6252            break;
6253        }
6254    }
6255    Ok(hits)
6256}
6257
6258/// `jvp_utf8_decode_length`: the width jq steps by when it counts characters,
6259/// judged from the lead byte alone.
6260fn utf8_step(lead: u8) -> usize {
6261    match lead {
6262        0x00..=0x7f => 1,
6263        b if b & 0xe0 == 0xc0 => 2,
6264        b if b & 0xf0 == 0xe0 => 3,
6265        _ => 4,
6266    }
6267}
6268
6269/// The characters passed before byte `to`, counted the way `f_match` counts.
6270fn chars_before(s: &str, to: usize) -> usize {
6271    let b = s.as_bytes();
6272    let (mut at, mut n) = (0, 0);
6273    while at < to {
6274        at += utf8_step(b[at]);
6275        n += 1;
6276    }
6277    n
6278}
6279
6280/// The `{offset,length,string,name}` object for a capture group that matched
6281/// text, and the `(offset, string, length, name)` shape jq builds for an empty
6282/// or absent one — key order is visible in the output.
6283fn capture_obj(s: &str, span: Option<(usize, usize)>, zero_width_at: Option<usize>) -> JqVal {
6284    let name = (Rc::from("name"), JqVal::Null);
6285    let empty = |offset: f64, string: JqVal| {
6286        JqVal::obj(vec![
6287            (Rc::from("offset"), JqVal::num(offset)),
6288            (Rc::from("string"), string),
6289            (Rc::from("length"), JqVal::num(0.0)),
6290            name.clone(),
6291        ])
6292    };
6293    match (span, zero_width_at) {
6294        (None, _) => empty(-1.0, JqVal::Null),
6295        (Some(_), Some(idx)) => empty(idx as f64, JqVal::str("")),
6296        (Some((b, e)), None) if b == e => empty(chars_before(s, b) as f64, JqVal::str("")),
6297        (Some((b, e)), None) => {
6298            let (idx, len) = span_chars(s, b, e);
6299            JqVal::obj(vec![
6300                (Rc::from("offset"), JqVal::num(idx as f64)),
6301                (Rc::from("length"), JqVal::num(len as f64)),
6302                (
6303                    Rc::from("string"),
6304                    JqVal::str(String::from_utf8_lossy(&s.as_bytes()[b..e])),
6305                ),
6306                name,
6307            ])
6308        }
6309    }
6310}
6311
6312/// `f_match`'s `for (idx = len = 0; fr < end; len++) { if (fr == beg) idx =
6313/// len, len = 0; … }`: the character offset of `beg` and the characters from
6314/// there to `end`.
6315fn span_chars(s: &str, beg: usize, end: usize) -> (usize, usize) {
6316    let b = s.as_bytes();
6317    let (mut at, mut idx, mut len) = (0, 0, 0);
6318    while at < end {
6319        if at == beg {
6320            idx = len;
6321            len = 0;
6322        }
6323        at += utf8_step(b[at]);
6324        len += 1;
6325    }
6326    (idx, len)
6327}
6328
6329/// jq's `_match_impl`: an array of match objects, or a boolean in test mode.
6330fn regex_match(input: &JqVal, re: &JqVal, flags: &JqVal, testmode: bool) -> R<JqVal> {
6331    let s = match input {
6332        JqVal::Str(s) => s.clone(),
6333        other => {
6334            return Err(JqErr::msg(format!(
6335                "{}{} cannot be matched, as it is not a string",
6336                other.type_name(),
6337                paren_of(other)
6338            )))
6339        }
6340    };
6341    let (pat, fl) = re_args(re, flags)?;
6342    let (rx, global) = compile_re(&pat, &fl)?;
6343    let scanned = onig_scan(&rx, &s, global, testmode)?;
6344    if testmode {
6345        return Ok(JqVal::Bool(!scanned.is_empty()));
6346    }
6347    // Group numbers carry the names; a name may cover several groups.
6348    let mut names: Vec<Option<Rc<str>>> = vec![None; rx.captures_len() + 1];
6349    rx.foreach_name(|name, groups| {
6350        for &g in groups {
6351            if let Some(slot) = names.get_mut(g as usize) {
6352                *slot = Some(Rc::from(name));
6353            }
6354        }
6355        true
6356    });
6357    let mut hits = Vec::with_capacity(scanned.len());
6358    for spans in &scanned {
6359        let (beg, end) = spans[0].expect("group 0 always participates");
6360        let zero = beg == end;
6361        let at = zero.then(|| chars_before(&s, beg));
6362        let captures: Vec<JqVal> = spans
6363            .iter()
6364            .enumerate()
6365            .skip(1)
6366            .map(|(g, span)| {
6367                let cap = capture_obj(&s, *span, at);
6368                match (&names[g], cap) {
6369                    (Some(n), JqVal::Obj(fields)) => {
6370                        let mut fields = fields.as_ref().clone();
6371                        if let Some(slot) = fields.iter_mut().find(|(k, _)| &**k == "name") {
6372                            slot.1 = JqVal::Str(n.clone());
6373                        }
6374                        JqVal::obj(fields)
6375                    }
6376                    (_, cap) => cap,
6377                }
6378            })
6379            .collect();
6380        let (idx, len) = match at {
6381            Some(idx) => (idx, 0),
6382            None => span_chars(&s, beg, end),
6383        };
6384        hits.push(JqVal::obj(vec![
6385            (Rc::from("offset"), JqVal::num(idx as f64)),
6386            (Rc::from("length"), JqVal::num(len as f64)),
6387            (
6388                Rc::from("string"),
6389                JqVal::str(String::from_utf8_lossy(&s.as_bytes()[beg..end])),
6390            ),
6391            (Rc::from("captures"), JqVal::arr(captures)),
6392        ]));
6393    }
6394    Ok(JqVal::arr(hits))
6395}
6396
6397/// A string cut by CODE-POINT offsets, which is how jq's `.[a:b]` — and so
6398/// `splits` and `sub` — slice it. A start past the end yields `""`.
6399struct CpSlicer<'a> {
6400    s: &'a str,
6401    /// Byte position of every character boundary; `None` for ASCII, where
6402    /// character and byte offsets coincide.
6403    bounds: Option<Vec<usize>>,
6404}
6405
6406impl<'a> CpSlicer<'a> {
6407    fn new(s: &'a str) -> Self {
6408        let bounds = (!s.is_ascii()).then(|| {
6409            let mut b: Vec<usize> = s.char_indices().map(|(i, _)| i).collect();
6410            b.push(s.len());
6411            b
6412        });
6413        CpSlicer { s, bounds }
6414    }
6415
6416    fn slice(&self, from: usize, to: Option<usize>) -> &'a str {
6417        let n = self.bounds.as_ref().map_or(self.s.len(), |b| b.len() - 1);
6418        let from = from.min(n);
6419        let to = to.map_or(n, |t| t.min(n)).max(from);
6420        match &self.bounds {
6421            Some(b) => &self.s[b[from]..b[to]],
6422            None => &self.s[from..to],
6423        }
6424    }
6425}
6426
6427/// jq's regex `split/2`: `[splits($re; $flags)]`, where `splits` is
6428/// `.[foreach (match($re; $flags+"g"), null) as {$offset,$length} …]` — the
6429/// pieces BETWEEN matches, cut by the matches' code-point offsets. The flags
6430/// are joined with jq's `+` (and refused by it) before the input and the regex
6431/// are checked.
6432fn regex_split(input: &JqVal, re: &JqVal, flags: &JqVal) -> R<JqVal> {
6433    let flags = binop(BinOp::Add, flags, &JqVal::str("g"))?;
6434    let JqVal::Arr(edits) = regex_match(input, re, &flags, false)? else {
6435        unreachable!("match mode answers an array")
6436    };
6437    let s = want_str(input, "matched, as it is not a string")?;
6438    let cp = CpSlicer::new(&s);
6439    let mut parts = Vec::with_capacity(edits.len() + 1);
6440    let mut next = 0usize;
6441    for edit in edits.iter() {
6442        let (offset, length) = match_span(edit);
6443        parts.push(JqVal::str(cp.slice(next, Some(offset))));
6444        next = offset + length;
6445    }
6446    parts.push(JqVal::str(cp.slice(next, None)));
6447    Ok(JqVal::arr(parts))
6448}
6449
6450/// `(offset, length)` of a match object built by [`regex_match`].
6451fn match_span(m: &JqVal) -> (usize, usize) {
6452    let field = |k: &str| m.obj_get(k).and_then(JqVal::as_f64).unwrap_or(0.0) as usize;
6453    (field("offset"), field("length"))
6454}
6455
6456/// jq's `sub`/`gsub`, transcribed from jq 1.8's `def sub($re; s; $flags)`. The
6457/// replacement is a FILTER evaluated with the named-capture object as `.`, and
6458/// it is a generator — but its outputs are combined POSITIONALLY across
6459/// matches, not as a cartesian product: output `k` of every match feeds result
6460/// `k`, so `"aaa" | [gsub("a"; "b","c")]` is `["bbb","ccc"]`. A match that yields
6461/// fewer outputs than an earlier one leaves the extra results un-extended, and
6462/// no result at all falls back to the input (jq's trailing `// $in`).
6463fn regex_sub(
6464    it: &Interp,
6465    input: &JqVal,
6466    re: &JqVal,
6467    repl: &Filter,
6468    flags: &JqVal,
6469    env: &Env,
6470    out: Sink,
6471) -> R<()> {
6472    let JqVal::Arr(edits) = regex_match(input, re, flags, false)? else {
6473        unreachable!("match mode answers an array")
6474    };
6475    let s = want_str(input, "matched, as it is not a string")?;
6476    let cp = CpSlicer::new(&s);
6477    let mut results: Vec<String> = Vec::new();
6478    let mut previous = 0usize;
6479    for edit in edits.iter() {
6480        let (offset, length) = match_span(edit);
6481        let gap = cp.slice(previous, Some(offset));
6482        // `reduce (.captures[] | select(.name != null) | {(.name): .string})`:
6483        // a repeated name keeps its first position and takes the last value.
6484        let mut named: Vec<(Rc<str>, JqVal)> = Vec::new();
6485        if let Some(JqVal::Arr(caps)) = edit.obj_get("captures") {
6486            for cap in caps.iter() {
6487                let (Some(JqVal::Str(n)), Some(v)) = (cap.obj_get("name"), cap.obj_get("string"))
6488                else {
6489                    continue;
6490                };
6491                match named.iter_mut().find(|(k, _)| k == n) {
6492                    Some(slot) => slot.1 = v.clone(),
6493                    None => named.push((n.clone(), v.clone())),
6494                }
6495            }
6496        }
6497        let mut inserts = Vec::new();
6498        eval(it, repl, &JqVal::obj(named), env, &mut |r| {
6499            inserts.push(r);
6500            Ok(())
6501        })?;
6502        // jq joins with `$gap + $inserts[$ix]`, so a non-string replacement
6503        // fails as that ADDITION does (`string ("") and number (1) cannot be
6504        // added`); a successful `string + x` is always a string.
6505        for (ix, r) in inserts.iter().enumerate() {
6506            // `.result[$ix] += …` is a `_modify`, entering one label.
6507            it.next_label();
6508            let piece = render_raw(&binop(BinOp::Add, &JqVal::str(gap), r)?);
6509            match results.get_mut(ix) {
6510                Some(acc) => acc.push_str(&piece),
6511                None => results.push(piece),
6512            }
6513        }
6514        previous = offset + length;
6515    }
6516    if results.is_empty() {
6517        return out(input.clone());
6518    }
6519    let tail = cp.slice(previous, None);
6520    for r in results {
6521        out(JqVal::str(format!("{r}{tail}")))?;
6522    }
6523    Ok(())
6524}
6525
6526// ─────────────────────────────────────────────────────────────────────────────
6527// Date builtins
6528// ─────────────────────────────────────────────────────────────────────────────
6529
6530fn unix_now() -> f64 {
6531    std::time::SystemTime::now()
6532        .duration_since(std::time::UNIX_EPOCH)
6533        .map_or(0.0, |d| d.as_secs_f64())
6534}
6535
6536/// jq's `tm2jv`: `[year, month0, mday, hour, min, sec, wday, yday]`, where
6537/// `sec` carries the sub-second fraction `fsecs - floor(fsecs)`.
6538fn tm2jv(tm: &libc::tm, fsecs: f64) -> JqVal {
6539    JqVal::arr(vec![
6540        JqVal::num(f64::from(tm.tm_year) + 1900.0),
6541        JqVal::num(f64::from(tm.tm_mon)),
6542        JqVal::num(f64::from(tm.tm_mday)),
6543        JqVal::num(f64::from(tm.tm_hour)),
6544        JqVal::num(f64::from(tm.tm_min)),
6545        JqVal::num(f64::from(tm.tm_sec) + (fsecs - fsecs.floor())),
6546        JqVal::num(f64::from(tm.tm_wday)),
6547        JqVal::num(f64::from(tm.tm_yday)),
6548    ])
6549}
6550
6551/// jq's `f_gmtime`/`f_localtime`. The whole seconds are the input TRUNCATED
6552/// (`time_t secs = fsecs`), and the fraction is taken against the floor, so
6553/// `-1.5` is `23:59:59.5`, as jq answers.
6554fn broken_down(t: f64, local: bool) -> R<JqVal> {
6555    let tt = t as libc::time_t;
6556    let mut tm: libc::tm = unsafe { std::mem::zeroed() };
6557    let ok = unsafe {
6558        if local {
6559            !libc::localtime_r(&tt, &mut tm).is_null()
6560        } else {
6561            !libc::gmtime_r(&tt, &mut tm).is_null()
6562        }
6563    };
6564    if !ok {
6565        return Err(JqErr::msg(
6566            "error converting number of seconds since epoch to datetime",
6567        ));
6568    }
6569    Ok(tm2jv(&tm, t))
6570}
6571
6572/// jq's `jv2tm`: up to eight numeric fields in `tm` order — a missing one stays
6573/// 0, each is clamped to `int` — then normalized the way jq does, through
6574/// `timegm` for UTC or `mktime` (DST unknown) for local time. `None` when a
6575/// field is not a number, or is NaN.
6576fn jv2tm(v: &JqVal, local: bool) -> Option<libc::tm> {
6577    let JqVal::Arr(a) = v.bare() else {
6578        return None;
6579    };
6580    let mut f = [0i32; 8];
6581    for (i, (slot, x)) in f.iter_mut().zip(a.iter()).enumerate() {
6582        let d = x.as_f64().filter(|d| !d.is_nan())?;
6583        // The year is offset BEFORE the clamp; `as` saturates, which is jq's
6584        // INT_MIN/INT_MAX clamp.
6585        *slot = if i == 0 { d - 1900.0 } else { d } as i32;
6586    }
6587    let mut tm: libc::tm = unsafe { std::mem::zeroed() };
6588    tm.tm_year = f[0];
6589    tm.tm_mon = f[1];
6590    tm.tm_mday = f[2];
6591    tm.tm_hour = f[3];
6592    tm.tm_min = f[4];
6593    tm.tm_sec = f[5];
6594    tm.tm_wday = f[6];
6595    tm.tm_yday = f[7];
6596    unsafe {
6597        if local {
6598            tm.tm_isdst = -1;
6599            libc::mktime(&mut tm);
6600        } else {
6601            libc::timegm(&mut tm);
6602        }
6603    }
6604    Some(tm)
6605}
6606
6607fn mktime(v: &JqVal) -> R<i64> {
6608    if !matches!(v, JqVal::Arr(_)) {
6609        return Err(JqErr::msg("mktime requires array inputs"));
6610    }
6611    let mut tm =
6612        jv2tm(v, false).ok_or_else(|| JqErr::msg("mktime requires parsed datetime inputs"))?;
6613    // `timegm` is the UTC counterpart of `mktime`; jq uses it so a broken-down
6614    // time round-trips through `gmtime` exactly.
6615    match unsafe { libc::timegm(&mut tm) } {
6616        -1 => Err(JqErr::msg("invalid gmtime representation")),
6617        t => Ok(t),
6618    }
6619}
6620
6621/// Expand the directives libc would answer from the process's LOCAL zone, for
6622/// `strftime`, which formats UTC: `%Z`/`%z` read `UTC`/`+0000` and `%s` is the
6623/// UTC epoch. jq gets the same by switching `TZ` to UTC around the call on
6624/// macOS; changing the environment is not thread-safe here, so the three are
6625/// expanded instead. `%%` and every other directive are left for libc.
6626fn utc_zone_directives(fmt: &str, epoch: i64) -> String {
6627    let mut out = String::with_capacity(fmt.len());
6628    let mut cs = fmt.chars();
6629    while let Some(c) = cs.next() {
6630        if c != '%' {
6631            out.push(c);
6632            continue;
6633        }
6634        match cs.next() {
6635            Some('Z') => out.push_str("UTC"),
6636            Some('z') => out.push_str("+0000"),
6637            Some('s') => out.push_str(&epoch.to_string()),
6638            Some(d) => {
6639                out.push('%');
6640                out.push(d);
6641            }
6642            None => out.push('%'),
6643        }
6644    }
6645    out
6646}
6647
6648/// jq's `f_strftime`/`f_strflocaltime`: a number goes through `gmtime` (or
6649/// `localtime`) first, an array through `jv2tm`.
6650fn strftime_val(v: &JqVal, fmt: &str, local: bool) -> R<String> {
6651    let name = if local { "strflocaltime" } else { "strftime" };
6652    let bad_input = || JqErr::msg(format!("{name}/1 requires parsed datetime inputs"));
6653    let tm = match v.bare() {
6654        JqVal::Num(n, _) => jv2tm(&broken_down(*n, local)?, local),
6655        JqVal::Arr(_) => jv2tm(v, local),
6656        _ => return Err(bad_input()),
6657    }
6658    .ok_or_else(bad_input)?;
6659    let fmt = if local {
6660        fmt.to_string()
6661    } else {
6662        utc_zone_directives(fmt, unsafe { libc::timegm(&mut tm.clone()) })
6663    };
6664    let cfmt = std::ffi::CString::new(fmt).map_err(|_| JqErr::msg("bad format string"))?;
6665    let mut buf = vec![0u8; 512];
6666    let n = unsafe { libc::strftime(buf.as_mut_ptr().cast(), buf.len(), cfmt.as_ptr(), &tm) };
6667    buf.truncate(n);
6668    Ok(String::from_utf8_lossy(&buf).into_owned())
6669}
6670
6671/// jq's `set_tm_wday`: Gauss's day-of-week, from year, month and day alone.
6672fn set_tm_wday(tm: &mut libc::tm) {
6673    let century = (1900 + tm.tm_year) / 100;
6674    let mut year = (1900 + tm.tm_year) % 100;
6675    if tm.tm_mon < 2 {
6676        year -= 1;
6677    }
6678    // March is 1, …, January 11, February 12.
6679    let mut mon = tm.tm_mon - 1;
6680    if mon < 1 {
6681        mon += 12;
6682    }
6683    let mut wday = (tm.tm_mday
6684        + (2.6 * f64::from(mon) - 0.2).floor() as i32
6685        + year
6686        + (f64::from(year) / 4.0).floor() as i32
6687        + (f64::from(century) / 4.0).floor() as i32
6688        - 2 * century)
6689        % 7;
6690    if wday < 0 {
6691        wday += 7;
6692    }
6693    tm.tm_wday = wday;
6694}
6695
6696/// jq's `set_tm_yday`: the day of the year from month and day, with jq's
6697/// bounds folding of an out-of-range month.
6698fn set_tm_yday(tm: &mut libc::tm) {
6699    const D: [i32; 12] = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334];
6700    let year = 1900 + tm.tm_year;
6701    let leap = tm.tm_mon > 1 && ((year % 4 == 0 && year % 100 != 0) || year % 400 == 0);
6702    let mut mon = tm.tm_mon.abs();
6703    if mon > 11 {
6704        mon %= 12;
6705    }
6706    tm.tm_yday = D[mon as usize] + i32::from(leap) + tm.tm_mday - 1;
6707}
6708
6709/// jq's `f_strptime`. Fields the format does not set stay as jq zeroes them
6710/// (`"10:30" | strptime("%H:%M")` is year 1900, month 0, day 0), and wday/yday
6711/// are always derived from year/month/day — jq's macOS branch, which this
6712/// follows on every platform so the answer does not depend on the libc. Input
6713/// left over after the format is allowed when it starts with whitespace, and is
6714/// appended to the result as a string, as jq does.
6715fn strptime_val(s: &str, fmt: &str) -> R<JqVal> {
6716    let cs = std::ffi::CString::new(s).map_err(|_| JqErr::msg("bad date string"))?;
6717    let cf = std::ffi::CString::new(fmt).map_err(|_| JqErr::msg("bad format string"))?;
6718    let mut tm: libc::tm = unsafe { std::mem::zeroed() };
6719    let end = unsafe { libc::strptime(cs.as_ptr(), cf.as_ptr(), &mut tm) };
6720    let rest = (!end.is_null()).then(|| {
6721        unsafe { std::ffi::CStr::from_ptr(end) }
6722            .to_string_lossy()
6723            .into_owned()
6724    });
6725    let Some(rest) =
6726        rest.filter(|r| r.starts_with([' ', '\t', '\n', '\x0b', '\x0c', '\r']) || r.is_empty())
6727    else {
6728        return Err(JqErr::msg(format!(
6729            "date \"{s}\" does not match format \"{fmt}\""
6730        )));
6731    };
6732    set_tm_wday(&mut tm);
6733    set_tm_yday(&mut tm);
6734    let JqVal::Arr(mut a) = tm2jv(&tm, 0.0) else {
6735        unreachable!("tm2jv builds an array")
6736    };
6737    if !rest.is_empty() {
6738        Rc::make_mut(&mut a).push(JqVal::str(rest));
6739    }
6740    Ok(JqVal::Arr(a))
6741}
6742
6743// ─────────────────────────────────────────────────────────────────────────────
6744// Prelude — jq's own `src/builtin.jq`, transcribed
6745//
6746// These are the builtins jq itself writes in jq rather than in C. Keeping them
6747// as jq source (rather than re-deriving them in Rust) is what makes the corner
6748// cases match: `from_entries`' six accepted key spellings, `limit`'s early
6749// `break`, `walk`'s post-order, `tostream`'s path trick. Definitions are ordered
6750// so each one only refers to those above it, which is what the environment chain
6751// makes visible.
6752// ─────────────────────────────────────────────────────────────────────────────
6753
6754const PRELUDE: &str = r#"
6755def error(msg): msg|error;
6756def _assign(paths; $value): reduce path(paths) as $p (.; setpath($p; $value));
6757def _modify(paths; update):
6758    reduce path(paths) as $p ([., []];
6759        . as $dot
6760      | null
6761      | label $out
6762      | ($dot[0] | getpath($p)) as $v
6763      | (
6764          (   $v
6765            | update
6766            | (., break $out) as $v
6767            | $dot
6768            | setpath([0] + $p; $v)
6769          ),
6770          (
6771              $dot
6772            | setpath([1, (.[1] | length)]; $p)
6773          )
6774        )
6775    ) | . as $dot | $dot[0] | delpaths($dot[1]);
6776def halt_error: halt_error(5);
6777def map(f): [.[] | f];
6778def select(f): if f then . else empty end;
6779def recurse(f): def r: ., (f | r); r;
6780def recurse(f; cond): def r: ., (f | select(cond) | r); r;
6781def recurse: recurse(.[]?);
6782def values: select(. != null);
6783def nulls: select(. == null);
6784def booleans: select(type == "boolean");
6785def numbers: select(type == "number");
6786def strings: select(type == "string");
6787def arrays: select(type == "array");
6788def objects: select(type == "object");
6789def iterables: select(type |. == "array" or . == "object");
6790def scalars: select(type |. != "array" and . != "object");
6791def finites: select(type == "number" and (isinfinite or isnan | not));
6792def normals: select(isnormal);
6793def to_entries: [keys_unsorted[] as $k | {key: $k, value: .[$k]}];
6794def add: reduce .[] as $x (null; . + $x);
6795def add(f): reduce f as $x (null; . + $x);
6796def from_entries: map({ (.key // .Key // .name // .Name):
6797  if has("value") then .value else .Value end }) | add // {};
6798def with_entries(f): to_entries | map(f) | from_entries;
6799def join($x): reduce .[] as $i (null;
6800            (if .==null then "" else .+$x end) +
6801            ($i | if type=="boolean" or type=="number" then tostring else .//"" end)
6802        ) // "";
6803def flatten: _flatten(1e9);
6804def flatten($x): _flatten($x);
6805def ltrimstr($left): if startswith($left) then .[($left|length):] else . end;
6806def rtrimstr($right): if endswith($right) then .[:length - ($right|length)] else . end;
6807def range($x): range(0; $x);
6808def first(f): label $out | (f | ., break $out);
6809def isempty(g): first((g|false), true);
6810def first: .[0];
6811def last(f): reduce f as $x (null; [$x]) | values | .[0];
6812def last: .[-1];
6813def any(g; y): isempty(g | y or empty) | not;
6814def all(g; y): isempty(g | y and empty);
6815def any(y): any(.[]; y);
6816def all(y): all(.[]; y);
6817def any: any(.);
6818def all: all(.);
6819def limit($n; f): if $n > 0 then label $out | foreach f as $item ($n; . - 1; $item, if . <= 0 then break $out else empty end)
6820                  elif $n == 0 then empty
6821                  else error("limit doesn't support negative count") end;
6822def skip($n; f): if $n > 0 then foreach f as $item ($n; . - 1; if . < 0 then $item else empty end)
6823                 elif $n == 0 then f
6824                 else error("skip doesn't support negative count") end;
6825def nth($n): .[$n];
6826def nth($n; f): if $n < 0 then error("nth doesn't support negative indices") else first(skip($n; f)) end;
6827def until(cond; update): def _until: if cond then . else (update | _until) end; _until;
6828def while(cond; update): def _while: if cond then ., (update | _while) else empty end; _while;
6829def repeat(f): def _repeat: f, _repeat; _repeat;
6830def in(xs): . as $x | xs | has($x);
6831def inside(xs): . as $x | xs | contains($x);
6832def combinations: if length == 0 then [] else .[0][] as $x | (.[1:] | combinations) as $w | [$x] + $w end;
6833def combinations(n): . as $dot | [range(n)] | map($dot) | combinations;
6834def map_values(f): .[] |= f;
6835def walk(f): def w: if type == "object" then map_values(w) elif type == "array" then map(w) else . end | f; w;
6836def del(f): delpaths([path(f)]);
6837def paths: path(..) | select(length > 0);
6838def paths(node_filter): path(..|select(node_filter)) | select(length > 0);
6839def leaf_paths: paths(scalars);
6840def pick(pathexps): . as $top | reduce path(pathexps) as $p (null; setpath($p; $top | getpath($p)));
6841def transpose: [range(0; (map(length) | max) // 0) as $j | map(.[$j])];
6842def env: $ENV;
6843def isfinite: type == "number" and (isinfinite | not);
6844def trimstr($val): ltrimstr($val) | rtrimstr($val);
6845def toboolean: if type == "boolean" then .
6846  elif type == "string" and (. == "true" or . == "false") then . == "true"
6847  else error("\(type) (\(tojson)) cannot be parsed as a boolean") end;
6848def JOIN($idx; idx_expr): [.[] | [., $idx[idx_expr]]];
6849def JOIN($idx; stream; idx_expr): stream | [., $idx[idx_expr]];
6850def JOIN($idx; stream; idx_expr; join_expr): stream | [., $idx[idx_expr]] | join_expr;
6851def bsearch($target):
6852  if type != "array" then error("\(type) (\(tojson)) cannot be searched from")
6853  else . as $in
6854    | {s: 0, e: length, at: null}
6855    | until(.s >= .e or .at != null;
6856        (.s + ((.e - .s) / 2 | floor)) as $mid
6857        | if $target == $in[$mid] then .at = $mid
6858          elif $target < $in[$mid] then .e = $mid
6859          else .s = $mid + 1 end)
6860    | .at // (-1 - .s)
6861  end;
6862def toarray: if type == "array" then . else [.] end;
6863def abs: if . < 0 then - . else . end;
6864def isvalid(f): try (f|true) catch false;
6865def indices($i): if type == "array" and ($i|type) == "array" then .[$i]
6866                 elif type == "array" then .[[$i]]
6867                 elif type == "string" and ($i|type) == "string" then _strindices($i)
6868                 else .[$i] end;
6869def index($i): indices($i) | .[0];
6870def rindex($i): indices($i) | .[-1:][0];
6871def tostream: path(def r: (.[]?|r), .; r) as $p | getpath($p)
6872  | reduce path(.[]?) as $q ([$p, .]; [$p+$q]);
6873def fromstream(f): { x: null, e: false } as $init
6874  | foreach f as $i ($init;
6875      if .e then $init else . end
6876      | if $i | length == 2 then setpath(["e"]; $i[0] | length == 0) | setpath(["x"] + $i[0]; $i[1])
6877        else setpath(["e"]; $i[0] | length == 1) end;
6878      if .e then .x else empty end);
6879def truncate_stream(stream): . as $n | null | stream | . as $input
6880  | if (.[0]|length) > $n then setpath([0]; .[0][$n:]) else empty end;
6881def match($regex; $flags): _match_impl($regex; $flags; false) | .[];
6882def match($val): ($val|type) as $vt
6883  | if $vt == "string" then match($val; null)
6884    elif $vt == "array" and ($val|length) > 1 then match($val[0]; $val[1])
6885    elif $vt == "array" and ($val|length) > 0 then match($val[0]; null)
6886    else error($vt + " not a string or array") end;
6887def test($regex; $flags): _match_impl($regex; $flags; true);
6888def test($val): ($val|type) as $vt
6889  | if $vt == "string" then test($val; null)
6890    elif $vt == "array" and ($val|length) > 1 then test($val[0]; $val[1])
6891    elif $vt == "array" and ($val|length) > 0 then test($val[0]; null)
6892    else error($vt + " not a string or array") end;
6893def capture($re; $flags): match($re; $flags)
6894  | reduce (.captures | .[] | select(.name != null) | { (.name): .string }) as $pair ({}; . + $pair);
6895def capture($val): ($val|type) as $vt
6896  | if $vt == "string" then capture($val; null)
6897    elif $vt == "array" and ($val|length) > 1 then capture($val[0]; $val[1])
6898    elif $vt == "array" and ($val|length) > 0 then capture($val[0]; null)
6899    else error($vt + " not a string or array") end;
6900def scan($re; $flags): match($re; "g" + $flags)
6901  | if (.captures | length) > 0 then [.captures | .[] | .string] else .string end;
6902def scan($re): scan($re; null);
6903def split($re; $flags): _split_re($re; $flags);
6904def splits($re; $flags): split($re; $flags) | .[];
6905def splits($re): splits($re; null);
6906def sub($re; str): sub_impl($re; str; "");
6907def sub($re; str; $flags): sub_impl($re; str; $flags);
6908def gsub($re; str): sub_impl($re; str; "g");
6909def gsub($re; str; $flags): sub_impl($re; str; $flags + "g");
6910def ascii(i): [i] | implode;
6911def todate(f): strftime(f);
6912def todateiso8601: strftime("%Y-%m-%dT%H:%M:%SZ");
6913def todate: todateiso8601;
6914def fromdateiso8601: strptime("%Y-%m-%dT%H:%M:%SZ") | mktime;
6915def fromdate: fromdateiso8601;
6916def date: todate;
6917def IN(source): any(source == .; .);
6918def IN(src; s): any(src == s; .);
6919def INDEX(stream; idx_expr): reduce stream as $row ({}; .[$row|idx_expr|tostring] = $row);
6920def INDEX(idx_expr): INDEX(.[]; idx_expr);
6921def _pm_splits($re; $flags):
6922  .[foreach (match($re; $flags+"g"), null) as {$offset, $length}
6923      (null; {start: .next, end: $offset, next: ($offset+$length)})];
6924def _pm_splits($re): _pm_splits($re; null);
6925def _pm_split($re; $flags): [ _pm_splits($re; $flags) ];
6926def _pm_sub($re; s; $flags):
6927   . as $in
6928   | (reduce match($re; $flags) as $edit
6929        ({result: [], previous: 0};
6930            $in[ .previous: ($edit | .offset) ] as $gap
6931            | [reduce ( $edit | .captures | .[] | select(.name != null) | { (.name) : .string } ) as $pair
6932                 ({}; . + $pair) | s ] as $inserts
6933            | reduce range(0; $inserts|length) as $ix (.; .result[$ix] += $gap + $inserts[$ix])
6934            | .previous = ($edit | .offset + .length ) )
6935          | .result[] + $in[.previous:] )
6936      // $in;
6937def _pm_sub($re; s): _pm_sub($re; s; "");
6938def _pm_gsub($re; s; flags): _pm_sub($re; s; flags + "g");
6939def _pm_gsub($re; s): _pm_sub($re; s; "g");
6940def _pm_reverse: [.[length - 1 - range(0;length)]];
6941def _pm_sort_by(f): _sort_by_impl(map([f]));
6942def _pm_group_by(f): _group_by_impl(map([f]));
6943def _pm_unique_by(f): _unique_by_impl(map([f]));
6944def _pm_max_by(f): _max_by_impl(map([f]));
6945def _pm_min_by(f): _min_by_impl(map([f]));
6946def _pm_debug(msgs): (msgs | debug | empty), .;
6947.
6948"#;
6949
6950thread_local! {
6951    /// The prelude is parsed once per thread and every compiled program shares
6952    /// the resulting environment, so a per-line query pays for it exactly once.
6953    static PRELUDE_ENV: Env = build_prelude();
6954}
6955
6956fn build_prelude() -> Env {
6957    let mut env = Env::default();
6958    let mut f = match parse(PRELUDE) {
6959        Ok(f) => f,
6960        // The prelude is a compile-time constant of this crate: a parse failure
6961        // is a bug in this file, not in user input, so it fails loudly here
6962        // rather than silently degrading every query.
6963        Err(e) => panic!("jqlang: prelude does not parse: {e}"),
6964    };
6965    while let Filter::Def(def, rest) = f {
6966        env = env.define(def);
6967        f = *rest;
6968    }
6969    env
6970}
6971
6972fn prelude_env() -> Env {
6973    PRELUDE_ENV.with(Clone::clone)
6974}
6975
6976/// jq's `builtins`: every callable name as `name/arity`.
6977fn builtin_names() -> Vec<String> {
6978    // The Rust half, listed explicitly: these have no `def` to walk.
6979    const NATIVE: &[&str] = &[
6980        "empty/0",
6981        "error/0",
6982        "error/1",
6983        "not/0",
6984        "type/0",
6985        "length/0",
6986        "utf8bytelength/0",
6987        "keys/0",
6988        "keys_unsorted/0",
6989        "has/1",
6990        "contains/1",
6991        "tostring/0",
6992        "tojson/0",
6993        "fromjson/0",
6994        "tonumber/0",
6995        "explode/0",
6996        "implode/0",
6997        "ascii_downcase/0",
6998        "ascii_upcase/0",
6999        "startswith/1",
7000        "endswith/1",
7001        "ltrim/0",
7002        "rtrim/0",
7003        "trim/0",
7004        "split/1",
7005        "_strindices/1",
7006        "sort/0",
7007        "reverse/0",
7008        "unique/0",
7009        "sort_by/1",
7010        "group_by/1",
7011        "unique_by/1",
7012        "min_by/1",
7013        "max_by/1",
7014        "min/0",
7015        "max/0",
7016        "range/2",
7017        "range/3",
7018        "floor/0",
7019        "ceil/0",
7020        "round/0",
7021        "sqrt/0",
7022        "fabs/0",
7023        "log/0",
7024        "log2/0",
7025        "log10/0",
7026        "exp/0",
7027        "exp2/0",
7028        "exp10/0",
7029        "trunc/0",
7030        "cbrt/0",
7031        "sin/0",
7032        "cos/0",
7033        "tan/0",
7034        "asin/0",
7035        "acos/0",
7036        "atan/0",
7037        "sinh/0",
7038        "cosh/0",
7039        "tanh/0",
7040        "nearbyint/0",
7041        "significand/0",
7042        "logb/0",
7043        "pow/2",
7044        "atan2/2",
7045        "fmin/2",
7046        "fmax/2",
7047        "ldexp/2",
7048        "infinite/0",
7049        "nan/0",
7050        "isnan/0",
7051        "isinfinite/0",
7052        "isnormal/0",
7053        "path/1",
7054        "getpath/1",
7055        "setpath/2",
7056        "delpaths/1",
7057        "_flatten/1",
7058        "_match_impl/3",
7059        "_split_re/2",
7060        "sub_impl/3",
7061        "env/0",
7062        "builtins/0",
7063        "input/0",
7064        "inputs/0",
7065        "input_line_number/0",
7066        "debug/0",
7067        "debug/1",
7068        "stderr/0",
7069        "halt/0",
7070        "halt_error/0",
7071        "halt_error/1",
7072        "input_filename/0",
7073        "have_literal_numbers/0",
7074        "have_decnum/0",
7075        "now/0",
7076        "mktime/0",
7077        "gmtime/0",
7078        "localtime/0",
7079        "strftime/1",
7080        "strflocaltime/1",
7081        "strptime/1",
7082        "acosh/0",
7083        "asinh/0",
7084        "atanh/0",
7085        "expm1/0",
7086        "log1p/0",
7087        "rint/0",
7088        "gamma/0",
7089        "lgamma/0",
7090        "tgamma/0",
7091        "erf/0",
7092        "erfc/0",
7093        "j0/0",
7094        "j1/0",
7095        "y0/0",
7096        "y1/0",
7097        "frexp/0",
7098        "modf/0",
7099        "lgamma_r/0",
7100        "isfinite/0",
7101        "format/1",
7102        "copysign/2",
7103        "drem/2",
7104        "fdim/2",
7105        "fmod/2",
7106        "hypot/2",
7107        "nextafter/2",
7108        "nexttoward/2",
7109        "remainder/2",
7110        "scalb/2",
7111        "scalbln/2",
7112        "jn/2",
7113        "yn/2",
7114        "fma/3",
7115        "get_jq_origin/0",
7116        "get_prog_origin/0",
7117        "get_search_list/0",
7118        "modulemeta/0",
7119    ];
7120    let mut names: Vec<String> = NATIVE.iter().map(|s| (*s).to_string()).collect();
7121    // The yq half of the superset claim. Listed from the same table `builtin`
7122    // dispatches from, so a name can never be callable but unlisted (or listed
7123    // but not callable) — `yq_superset_probe` measures exactly this set.
7124    names.extend(yq_builtin_names());
7125    prelude_env().walk_fn_names(&mut names);
7126    names.sort();
7127    names.dedup();
7128    names
7129}
7130
7131impl Env {
7132    fn walk_fn_names(&self, out: &mut Vec<String>) {
7133        let mut cur = self.funcs.clone();
7134        while let Some(n) = cur {
7135            out.push(format!("{}/{}", n.name, n.arity));
7136            cur = n.next.clone();
7137        }
7138    }
7139}
7140
7141// ─────────────────────────────────────────────────────────────────────────────
7142// The yq surface
7143//
7144// arb's docs claim a jq/xpath/css/yq superset. `superset_probe` measures the jq
7145// leg by containment — every `name/arity` jq defines must exist here — and
7146// `yq_superset_probe` does the same for yq's own operator index. This section is
7147// what closes that leg: the ~60 operators yq has that jq has no equivalent for.
7148//
7149// Three groups, and only the first needs the node box:
7150//
7151//   * NODE METADATA — `anchor`, `alias`, `tag`, `style`, the three comments,
7152//     `key`, `is_key`, `path`, `parent`, `line`, `column`, `kind`,
7153//     `document_index`, `filename`, `fileIndex`. These read (and, through
7154//     `anchor = "x"`, write) `crate::ynode::NodeMeta`, which is exactly the
7155//     metadata a jq value has no slot for.
7156//   * ENCODERS — `to_json`/`from_json` and the yaml/xml/props/csv/tsv family,
7157//     plus `env`/`strenv`/`envsubst` and the `load` family. Pure text; see
7158//     `crate::yqfmt`.
7159//   * RESHAPING — `pick`/`omit`/`with`/`sort_keys`/`pivot`/`shuffle`/`ireduce`/
7160//     `eval`/`ref`/`splitDoc` and the `downcase`/`upcase`/`to_string`/
7161//     `to_number` spellings.
7162//
7163// Where a spelling had to change, it is because yq's grammar is not jq's and
7164// the difference is stated rather than papered over — see `ireduce` and `ref`.
7165// ─────────────────────────────────────────────────────────────────────────────
7166
7167/// Every yq `name/arity` this engine defines. The single source of truth: both
7168/// [`is_yq_builtin`] and the `builtins` listing read it, so a name can never be
7169/// dispatchable but unlisted (or listed but undispatchable).
7170const YQ_BUILTINS: &[(&str, usize)] = &[
7171    // node metadata, read
7172    ("anchor", 0),
7173    ("alias", 0),
7174    ("tag", 0),
7175    ("style", 0),
7176    ("kind", 0),
7177    ("line", 0),
7178    ("column", 0),
7179    ("head_comment", 0),
7180    ("headComment", 0),
7181    ("line_comment", 0),
7182    ("lineComment", 0),
7183    ("foot_comment", 0),
7184    ("footComment", 0),
7185    ("comments", 0),
7186    ("key", 0),
7187    ("is_key", 0),
7188    ("parent", 0),
7189    ("path", 0),
7190    ("document_index", 0),
7191    ("documentIndex", 0),
7192    ("di", 0),
7193    ("filename", 0),
7194    ("fileIndex", 0),
7195    ("splitDoc", 0),
7196    ("split_doc", 0),
7197    ("explode", 1),
7198    // encoders
7199    ("to_json", 0),
7200    ("to_json", 1),
7201    ("from_json", 0),
7202    ("to_yaml", 0),
7203    ("to_yaml", 1),
7204    ("from_yaml", 0),
7205    ("to_xml", 0),
7206    ("to_xml", 1),
7207    ("from_xml", 0),
7208    ("to_props", 0),
7209    ("from_props", 0),
7210    ("to_csv", 0),
7211    ("from_csv", 0),
7212    ("to_tsv", 0),
7213    ("from_tsv", 0),
7214    // environment and files
7215    ("env", 1),
7216    ("strenv", 1),
7217    ("envsubst", 0),
7218    ("load", 1),
7219    ("load_str", 1),
7220    ("load_props", 1),
7221    ("load_xml", 1),
7222    // dates
7223    ("format_datetime", 1),
7224    ("from_unix", 0),
7225    ("to_unix", 0),
7226    ("tz", 1),
7227    ("with_dtf", 2),
7228    // reshaping
7229    ("omit", 1),
7230    ("with", 2),
7231    ("ref", 2),
7232    ("sort_keys", 1),
7233    ("sortKeys", 1),
7234    ("shuffle", 0),
7235    ("pivot", 0),
7236    ("pick", 1),
7237    ("ireduce", 2),
7238    ("eval", 1),
7239    ("downcase", 0),
7240    ("upcase", 0),
7241    ("to_string", 0),
7242    ("to_number", 0),
7243];
7244
7245/// Does arb define `src` as a FUNCTION NAME at some arity?
7246///
7247/// Asked when a one-word jq program fails to compile, to tell an unknown verb
7248/// apart from a known name called at the wrong arity. Both references report the
7249/// latter as an arity problem — `jq 'ltrimstr'` says "ltrimstr/0 is not
7250/// defined", `yq -n 'ref'` says "'ref' expects 2 args" — so answering "unknown
7251/// verb" for a name that exists is wrong information, not merely a worse
7252/// message.
7253pub fn defines_name(src: &str) -> bool {
7254    let word = src.trim();
7255    if word.is_empty() || !word.chars().all(|c| c.is_alphanumeric() || c == '_') {
7256        return false;
7257    }
7258    if YQ_BUILTINS.iter().any(|&(n, _)| n == word) {
7259        return true;
7260    }
7261    let prefix = format!("{word}/");
7262    builtin_names().iter().any(|n| n.starts_with(&prefix))
7263}
7264
7265/// Is `name/arity` one of the yq operators dispatched by [`yq_builtin`]?
7266///
7267/// Checked BEFORE `builtin` unboxes its input, because the metadata group is the
7268/// only code in the engine allowed to see a `JqVal::Node`.
7269fn is_yq_builtin(name: &str, arity: usize) -> bool {
7270    YQ_BUILTINS.iter().any(|&(n, a)| n == name && a == arity)
7271}
7272
7273/// The names for the `builtins` listing, in jq's `name/arity` spelling.
7274fn yq_builtin_names() -> Vec<String> {
7275    YQ_BUILTINS
7276        .iter()
7277        .map(|(n, a)| format!("{n}/{a}"))
7278        .collect()
7279}
7280
7281/// Split a metadata assignment's left-hand side into the path it selects (or
7282/// `None` for `.` itself) and the metadata field being written.
7283fn meta_assign_target(lhs: &Filter) -> Option<(Option<&Filter>, &str)> {
7284    match lhs {
7285        Filter::Call(name, args) if args.is_empty() && is_meta_setter(name) => Some((None, name)),
7286        Filter::Pipe(p, tail) => match &**tail {
7287            Filter::Call(name, args) if args.is_empty() && is_meta_setter(name) => {
7288                Some((Some(&**p), name))
7289            }
7290            _ => None,
7291        },
7292        _ => None,
7293    }
7294}
7295
7296/// The metadata accessors that may stand on the LEFT of `=`.
7297///
7298/// yq spells the assignment as a postfix on a path (`.a anchor = "x"`). arb's
7299/// grammar is jq's, where `|` binds loosest, so the DOCUMENT-preserving spelling
7300/// is `.a |= (anchor = "x")`: the update operator applies the edit at the path
7301/// and hands the whole document back, which is what yq's postfix does. A bare
7302/// `anchor = "x"` sets it on `.` and yields that node alone. Both reach here
7303/// through [`eval_assign`].
7304fn is_meta_setter(name: &str) -> bool {
7305    matches!(
7306        name,
7307        "anchor"
7308            | "tag"
7309            | "style"
7310            | "head_comment"
7311            | "headComment"
7312            | "line_comment"
7313            | "lineComment"
7314            | "foot_comment"
7315            | "footComment"
7316            | "comments"
7317    )
7318}
7319
7320/// Apply a metadata assignment to one node.
7321fn set_meta(node: &JqVal, name: &str, val: &JqVal) -> JqVal {
7322    let text: Rc<str> = match val.bare() {
7323        JqVal::Str(s) => s.clone(),
7324        JqVal::Null => Rc::from(""),
7325        other => Rc::from(render_raw(other).as_str()),
7326    };
7327    // Setting a CORE-SCHEMA tag converts the value, which is what the tag means:
7328    // `.a tag = "!!str"` on `a: 1` gives `a: "1"` in yq, not `a: !!str 1`. Once
7329    // converted the tag is implicit, so it is not written out as well.
7330    if name == "tag" {
7331        if let Some(v) = coerce_to_tag(node.bare(), &text) {
7332            let implicit = crate::ynode::implicit_tag(&v) == &*text;
7333            let mut meta = node.meta().cloned().unwrap_or_default();
7334            meta.tag = if implicit { Rc::from("") } else { text.clone() };
7335            meta.raw = Rc::from("");
7336            meta.blank = false;
7337            return JqVal::wrap(v, meta);
7338        }
7339    }
7340    node.with_meta(|m| match name {
7341        "anchor" => m.anchor = text.clone(),
7342        "tag" => m.tag = text.clone(),
7343        "style" => m.style = crate::ynode::Style::parse(&text),
7344        "head_comment" | "headComment" => m.head = text.clone(),
7345        "line_comment" | "lineComment" => m.line = text.clone(),
7346        "foot_comment" | "footComment" => m.foot = text.clone(),
7347        // `... comments = ""` is yq's spelling for "strip every comment here".
7348        "comments" => {
7349            m.head = text.clone();
7350            m.line = text.clone();
7351            m.foot = text.clone();
7352        }
7353        _ => {}
7354    })
7355}
7356
7357/// Convert a value to the type a core-schema tag names, or `None` for a tag with
7358/// no conversion (a local `!mytag`, or one already matching).
7359fn coerce_to_tag(v: &JqVal, tag: &str) -> Option<JqVal> {
7360    match tag {
7361        "!!str" => Some(JqVal::str(render_raw(v))),
7362        "!!int" => v
7363            .as_f64()
7364            .or_else(|| match v {
7365                JqVal::Str(s) => s.trim().parse().ok(),
7366                _ => None,
7367            })
7368            .map(|n| JqVal::num(n.trunc())),
7369        "!!float" => v
7370            .as_f64()
7371            .or_else(|| match v {
7372                JqVal::Str(s) => s.trim().parse().ok(),
7373                _ => None,
7374            })
7375            .map(JqVal::num),
7376        "!!bool" => match v {
7377            JqVal::Bool(_) => Some(v.clone()),
7378            JqVal::Str(s) => match &**s {
7379                "true" => Some(JqVal::Bool(true)),
7380                "false" => Some(JqVal::Bool(false)),
7381                _ => None,
7382            },
7383            _ => None,
7384        },
7385        "!!null" => Some(JqVal::Null),
7386        _ => None,
7387    }
7388}
7389
7390/// Read a file, reporting yq's own message shape on failure.
7391fn read_file(path: &str) -> R<String> {
7392    std::fs::read_to_string(path).map_err(|e| JqErr::msg(format!("failed to load {path}: {e}")))
7393}
7394
7395fn yq_builtin(
7396    it: &Interp,
7397    name: &str,
7398    args: &[Rc<Filter>],
7399    input: &JqVal,
7400    env: &Env,
7401    out: Sink,
7402) -> R<()> {
7403    let meta = input.meta().cloned().unwrap_or_default();
7404    let str_arg = |i: usize| -> R<Rc<str>> {
7405        let v = one(it, &args[i], input, env)?;
7406        Ok(match v.bare() {
7407            JqVal::Str(s) => s.clone(),
7408            other => Rc::from(render_raw(other).as_str()),
7409        })
7410    };
7411    match (name, args.len()) {
7412        // ── node metadata ───────────────────────────────────────────────────
7413        ("anchor", 0) => out(JqVal::Str(meta.anchor)),
7414        ("alias", 0) => out(JqVal::Str(meta.alias)),
7415        ("tag", 0) => out(JqVal::str(if meta.tag.is_empty() {
7416            crate::ynode::resolved_tag(input)
7417        } else {
7418            return out(JqVal::Str(meta.tag));
7419        })),
7420        ("style", 0) => out(JqVal::str(meta.style.name())),
7421        ("kind", 0) => out(JqVal::str(crate::ynode::kind_of(input))),
7422        ("line", 0) => out(JqVal::num(meta.line_no.max(1) as f64)),
7423        ("column", 0) => out(JqVal::num(meta.col_no.max(1) as f64)),
7424        ("head_comment", 0) | ("headComment", 0) => out(JqVal::Str(meta.head)),
7425        ("line_comment", 0) | ("lineComment", 0) => out(JqVal::Str(meta.line)),
7426        ("foot_comment", 0) | ("footComment", 0) => out(JqVal::Str(meta.foot)),
7427        // Read back, `comments` is every comment on the node, in the order they
7428        // appear on the page.
7429        ("comments", 0) => {
7430            let all: Vec<&str> = [&*meta.head, &*meta.line, &*meta.foot]
7431                .into_iter()
7432                .filter(|s| !s.is_empty())
7433                .collect();
7434            out(JqVal::str(all.join("\n")))
7435        }
7436        ("key", 0) => out(match &meta.key {
7437            Some(k) => (**k).clone(),
7438            // A node with no key (a document root, a sequence item) has none;
7439            // yq answers null there too.
7440            None => JqVal::Null,
7441        }),
7442        ("is_key", 0) => out(JqVal::Bool(meta.is_key)),
7443        ("path", 0) => out(JqVal::arr(meta.path.as_ref().clone())),
7444        ("parent", 0) => {
7445            // The document the node was READ from, walked to the path one step
7446            // short of the node. See `crate::ynode` for what this does not
7447            // promise once a value has been moved.
7448            let segs = meta.path.as_ref();
7449            match (it.current_doc(), segs.split_last()) {
7450                (Some(doc), Some((_, up))) => out(get_path(&doc, up)?),
7451                _ => out(JqVal::Null),
7452            }
7453        }
7454        ("document_index", 0) | ("documentIndex", 0) | ("di", 0) => {
7455            out(JqVal::num(meta.doc as f64))
7456        }
7457        ("filename", 0) => out(JqVal::str(if meta.file.is_empty() {
7458            Rc::from("-")
7459        } else {
7460            meta.file.clone()
7461        })),
7462        ("fileIndex", 0) => out(JqVal::num(meta.file_index as f64)),
7463        // arb's stream is already one document per output value, and `out.yaml`
7464        // separates them with `---`. `splitDoc` therefore has nothing left to
7465        // do — it is the identity here, not a stub: the split it asks for has
7466        // already happened by the time a value reaches it.
7467        ("splitDoc", 0) | ("split_doc", 0) => out(input.clone()),
7468        // `explode(f)`: drop the anchor/alias metadata under `f`, so an aliased
7469        // node is written out in full instead of as `*name`.
7470        ("explode", 1) => {
7471            let mut cur = input.clone();
7472            let mut paths = Vec::new();
7473            eval_paths(
7474                it,
7475                &args[0],
7476                input,
7477                &Tracked::root(input),
7478                input,
7479                env,
7480                &mut |p, v| {
7481                    let p = intact_path(p, &v)?;
7482                    paths.push(p);
7483                    Ok(())
7484                },
7485            )?;
7486            for p in paths {
7487                let at = get_path(&cur, &p)?;
7488                let flat = explode_node(&at);
7489                cur = if p.is_empty() {
7490                    flat
7491                } else {
7492                    set_path(&cur, &p, flat)?
7493                };
7494            }
7495            out(cur)
7496        }
7497
7498        // ── encoders ────────────────────────────────────────────────────────
7499        ("to_json", 0) => out(JqVal::str(json_indented(input, 2))),
7500        ("to_json", 1) => {
7501            let n = one(it, &args[0], input, env)?.as_f64().unwrap_or(2.0);
7502            out(JqVal::str(json_indented(input, n.max(0.0) as usize)))
7503        }
7504        ("from_json", 0) => {
7505            let s = want_str(input, "parsed as JSON")?;
7506            out(parse_json(&s).map_err(JqErr::msg)?)
7507        }
7508        ("to_yaml", 0) => out(JqVal::str(crate::ynode::emit_doc(
7509            input,
7510            crate::ynode::Emit::default(),
7511        ))),
7512        ("to_yaml", 1) => {
7513            let n = one(it, &args[0], input, env)?.as_f64().unwrap_or(2.0);
7514            out(JqVal::str(crate::ynode::emit_doc(
7515                input,
7516                crate::ynode::Emit {
7517                    indent: n.max(0.0) as usize,
7518                },
7519            )))
7520        }
7521        ("from_yaml", 0) => {
7522            let s = want_str(input, "parsed as YAML")?;
7523            out(crate::yaml::documents(&s)
7524                .into_iter()
7525                .next()
7526                .unwrap_or(JqVal::Null))
7527        }
7528        ("to_xml", 0) => out(JqVal::str(crate::yqfmt::to_xml(input, 2))),
7529        ("to_xml", 1) => {
7530            let n = one(it, &args[0], input, env)?.as_f64().unwrap_or(2.0);
7531            out(JqVal::str(crate::yqfmt::to_xml(input, n.max(0.0) as usize)))
7532        }
7533        ("from_xml", 0) => out(crate::yqfmt::from_xml(&want_str(input, "parsed as XML")?)),
7534        ("to_props", 0) => out(JqVal::str(crate::yqfmt::to_props(input))),
7535        ("from_props", 0) => out(crate::yqfmt::from_props(&want_str(
7536            input,
7537            "parsed as properties",
7538        )?)),
7539        ("to_csv", 0) => out(JqVal::str(crate::yqfmt::to_delim(input, ','))),
7540        ("to_tsv", 0) => out(JqVal::str(crate::yqfmt::to_delim(input, '\t'))),
7541        ("from_csv", 0) => out(crate::yqfmt::from_delim(
7542            &want_str(input, "parsed as CSV")?,
7543            ',',
7544        )),
7545        ("from_tsv", 0) => out(crate::yqfmt::from_delim(
7546            &want_str(input, "parsed as TSV")?,
7547            '\t',
7548        )),
7549
7550        // ── environment and files ───────────────────────────────────────────
7551        // `env(NAME)` resolves the value the way YAML would (`env(PORT)` is a
7552        // number); `strenv(NAME)` always answers a string. That difference is
7553        // the whole reason yq has both.
7554        ("env", 1) => {
7555            let n = str_arg(0)?;
7556            out(match std::env::var(&*n) {
7557                Ok(v) => crate::yaml::documents(&v)
7558                    .into_iter()
7559                    .next()
7560                    .unwrap_or(JqVal::Null),
7561                Err(_) => JqVal::Null,
7562            })
7563        }
7564        ("strenv", 1) => {
7565            let n = str_arg(0)?;
7566            out(JqVal::str(std::env::var(&*n).unwrap_or_default()))
7567        }
7568        ("envsubst", 0) => out(JqVal::str(crate::yqfmt::envsubst(&want_str(
7569            input, "expanded",
7570        )?))),
7571        ("load", 1) => {
7572            let path = str_arg(0)?;
7573            let text = read_file(&path)?;
7574            out(crate::yaml::documents_from(&text, &path, 0)
7575                .into_iter()
7576                .next()
7577                .unwrap_or(JqVal::Null))
7578        }
7579        ("load_str", 1) => out(JqVal::str(read_file(&str_arg(0)?)?)),
7580        ("load_props", 1) => out(crate::yqfmt::from_props(&read_file(&str_arg(0)?)?)),
7581        ("load_xml", 1) => out(crate::yqfmt::from_xml(&read_file(&str_arg(0)?)?)),
7582
7583        // ── dates ───────────────────────────────────────────────────────────
7584        ("format_datetime", 1) => {
7585            let layout = str_arg(0)?;
7586            let secs = to_unix_secs(input)?;
7587            out(JqVal::str(crate::yqfmt::format_go(secs, &layout, true)))
7588        }
7589        ("from_unix", 0) => {
7590            let secs = input.as_f64().unwrap_or(0.0);
7591            out(JqVal::str(crate::yqfmt::format_go(
7592                secs,
7593                "2006-01-02T15:04:05Z07:00",
7594                false,
7595            )))
7596        }
7597        ("to_unix", 0) => out(JqVal::num(to_unix_secs(input)?)),
7598        ("tz", 1) => {
7599            // Only UTC is a zone this build can resolve without a tzdata
7600            // dependency; any other name is answered in UTC and says so.
7601            let zone = str_arg(0)?;
7602            let secs = to_unix_secs(input)?;
7603            let utc = matches!(&*zone, "UTC" | "utc" | "Z" | "GMT" | "");
7604            out(JqVal::str(crate::yqfmt::format_go(
7605                secs,
7606                "2006-01-02T15:04:05Z07:00",
7607                utc,
7608            )))
7609        }
7610        // `with_dtf(layout; f)` runs `f` with `layout` as the date format. arb
7611        // has no dynamically scoped format, so the layout is applied to `f`'s
7612        // result the way yq's own `with_dtf` applies it to what `f` produces.
7613        ("with_dtf", 2) => {
7614            let layout = str_arg(0)?;
7615            eval(it, &args[1], input, env, &mut |v| match v.bare() {
7616                JqVal::Num(n, _) => out(JqVal::str(crate::yqfmt::format_go(*n, &layout, true))),
7617                other => out(other.clone()),
7618            })
7619        }
7620
7621        // ── reshaping ───────────────────────────────────────────────────────
7622        // `pick(["a","b"])` is yq's spelling and `pick(.a, .b)` is jq's. jq
7623        // REFUSES the array form ("Invalid path expression with result
7624        // [\"a\"]"), so answering it is a superset extension rather than a
7625        // conflict, and the jq form still reaches jq's own definition below.
7626        ("pick", 1) => {
7627            // yq's key list is an array LITERAL; anything else is a jq path
7628            // expression (`pick(first)` is `[0]`, and `pick(empty)` is null).
7629            if !is_key_list(&args[0]) {
7630                return builtin_jq_pick(it, args, input, env, out);
7631            }
7632            let keys = one(it, &args[0], input, env)?;
7633            let JqVal::Arr(want) = keys.bare() else {
7634                return builtin_jq_pick(it, args, input, env, out);
7635            };
7636            if !want.iter().all(|k| matches!(k.bare(), JqVal::Str(_))) {
7637                return builtin_jq_pick(it, args, input, env, out);
7638            }
7639            let JqVal::Obj(m) = input.bare() else {
7640                return out(input.clone());
7641            };
7642            // In the ORDER ASKED FOR, which is what yq answers with
7643            // (`pick(["c","a"])` is `{c: …, a: …}`), and a key the object does
7644            // not have contributes nothing.
7645            let kept: Vec<(Rc<str>, JqVal)> = want
7646                .iter()
7647                .filter_map(|k| match k.bare() {
7648                    JqVal::Str(name) => input.obj_lookup(name).map(|v| (name.clone(), v.clone())),
7649                    _ => None,
7650                })
7651                .collect();
7652            let _ = m;
7653            out(match input.meta() {
7654                Some(mm) => JqVal::wrap(JqVal::obj(kept), mm.clone()),
7655                None => JqVal::obj(kept),
7656            })
7657        }
7658        ("omit", 1) => {
7659            let keys = one(it, &args[0], input, env)?;
7660            let JqVal::Arr(drop) = keys.bare() else {
7661                return Err(JqErr::msg("omit expects an array of keys"));
7662            };
7663            let JqVal::Obj(m) = input.bare() else {
7664                return out(input.clone());
7665            };
7666            let kept: Vec<(Rc<str>, JqVal)> = m
7667                .iter()
7668                .filter(|(k, _)| {
7669                    !drop
7670                        .iter()
7671                        .any(|d| matches!(d.bare(), JqVal::Str(s) if s == k))
7672                })
7673                .cloned()
7674                .collect();
7675            out(match input.meta() {
7676                Some(mm) => JqVal::wrap(JqVal::obj(kept), mm.clone()),
7677                None => JqVal::obj(kept),
7678            })
7679        }
7680        // `with(p; f)` and `ref(p; f)` are both "update at a path", which is what
7681        // yq's two spellings do — `ref` binds a mutable handle and `with` scopes
7682        // one, and in a model without mutable handles both are `p |= f`.
7683        ("with", 2) | ("ref", 2) => {
7684            let update = Filter::Assign(
7685                AssignOp::Update,
7686                Box::new((*args[0]).clone()),
7687                Box::new((*args[1]).clone()),
7688            );
7689            eval(it, &update, input, env, out)
7690        }
7691        ("sort_keys", 1) | ("sortKeys", 1) => {
7692            // yq's argument selects WHERE to sort: `sort_keys(.)` is this level,
7693            // `sort_keys(..)` is every level.
7694            let deep = matches!(&*args[0], Filter::RecurseDefault);
7695            out(crate::yqfmt::sort_keys(input, deep))
7696        }
7697        ("shuffle", 0) => out(crate::yqfmt::shuffle(input)),
7698        ("pivot", 0) => out(crate::yqfmt::pivot(input)),
7699        // yq writes this as `.[] as $item ireduce (0; . + $item)`. arb's grammar
7700        // is jq's, so the stream is the input's own elements and `$item` is bound
7701        // for the body — `[1,2,3] | ireduce(0; . + $item)` is 6, the same answer
7702        // yq gives for the same reduction.
7703        ("ireduce", 2) => {
7704            let mut acc = one(it, &args[0], input, env)?;
7705            let JqVal::Arr(items) = input.bare() else {
7706                return out(acc);
7707            };
7708            for e in items.iter() {
7709                let benv = env.bind(Rc::from("item"), e.clone());
7710                acc = one(it, &args[1], &acc, &benv)?;
7711            }
7712            out(acc)
7713        }
7714        ("eval", 1) => {
7715            let src = str_arg(0)?;
7716            let f = parse(&src).map_err(JqErr::msg)?;
7717            eval(it, &f, input, env, out)
7718        }
7719        ("downcase", 0) => out(JqVal::str(
7720            want_str(input, "downcased")?.to_lowercase().as_str(),
7721        )),
7722        ("upcase", 0) => out(JqVal::str(
7723            want_str(input, "upcased")?.to_uppercase().as_str(),
7724        )),
7725        // The SOURCE spelling where the reader kept one: `padded: 007` is the
7726        // string `007`, not `7`, which is what yq answers.
7727        ("to_string", 0) => out(JqVal::str(
7728            match input.meta().filter(|m| !m.raw.is_empty()) {
7729                Some(m) => m.raw.to_string(),
7730                None => render_raw(input),
7731            },
7732        )),
7733        ("to_number", 0) => match input.bare() {
7734            JqVal::Num(..) => out(input.bare().clone()),
7735            JqVal::Str(s) => match s.trim().parse::<f64>() {
7736                Ok(n) => out(num_from_literal(n, s.trim())),
7737                Err(_) => Err(JqErr::msg(format!("cannot convert '{s}' to a number"))),
7738            },
7739            other => Err(JqErr::msg(format!(
7740                "cannot convert {} to a number",
7741                other.type_name()
7742            ))),
7743        },
7744        _ => Err(JqErr::msg(format!("{name} is not a yq operator"))),
7745    }
7746}
7747
7748/// Is `f` a literal, non-empty list of string keys — `["a", "b"]` — which is yq's
7749/// spelling of `pick`? jq refuses an array there (it is no path), so only a list
7750/// that is plainly keys is read as yq's.
7751fn is_key_list(f: &Filter) -> bool {
7752    fn strings(f: &Filter) -> bool {
7753        match f {
7754            Filter::Comma(a, b) => strings(a) && strings(b),
7755            Filter::Lit(JqVal::Str(_)) => true,
7756            Filter::Str(pieces, None) => pieces.iter().all(|p| matches!(p, StrPiece::Lit(_))),
7757            _ => false,
7758        }
7759    }
7760    match f {
7761        Filter::Array(Some(inner)) => strings(inner),
7762        Filter::Lit(JqVal::Arr(a)) => !a.is_empty() && a.iter().all(|k| matches!(k, JqVal::Str(_))),
7763        _ => false,
7764    }
7765}
7766
7767/// jq's own `pick(pathexps)`, reached when the argument is not yq's array of
7768/// keys. Defined in the prelude, so it is called rather than reimplemented.
7769fn builtin_jq_pick(it: &Interp, args: &[Rc<Filter>], input: &JqVal, env: &Env, out: Sink) -> R<()> {
7770    let node = env
7771        .find_fn("pick", 1)
7772        .ok_or_else(|| JqErr::msg("pick/1 is not defined"))?;
7773    let (body, benv) = bind_call(it, &node, args, env)?;
7774    eval(it, &body, input, &benv, out)
7775}
7776
7777/// Drop anchor/alias metadata through a whole subtree, which is what `explode`
7778/// means: the document that comes out has no `&name`/`*name` left in it.
7779fn explode_node(v: &JqVal) -> JqVal {
7780    let stripped = match v.bare() {
7781        JqVal::Arr(a) => JqVal::arr(a.iter().map(explode_node).collect()),
7782        JqVal::Obj(m) => JqVal::obj(
7783            m.iter()
7784                .map(|(k, val)| (k.clone(), explode_node(val)))
7785                .collect(),
7786        ),
7787        other => other.clone(),
7788    };
7789    match v.meta() {
7790        Some(m) => {
7791            let mut m = m.clone();
7792            m.anchor = Rc::from("");
7793            m.alias = Rc::from("");
7794            JqVal::wrap(stripped, m)
7795        }
7796        None => stripped,
7797    }
7798}
7799
7800/// The Unix second count a value denotes: a number is already one, a string is
7801/// read as RFC-3339.
7802fn to_unix_secs(v: &JqVal) -> R<f64> {
7803    match v.bare() {
7804        JqVal::Num(n, _) => Ok(*n),
7805        JqVal::Str(s) => crate::yqfmt::parse_rfc3339(s)
7806            .ok_or_else(|| JqErr::msg(format!("cannot parse '{s}' as a date"))),
7807        other => Err(JqErr::msg(format!(
7808            "cannot read {} as a date",
7809            other.type_name()
7810        ))),
7811    }
7812}
7813
7814/// `to_json(n)`: jq's own compact rendering when `n` is 0, and an indented one
7815/// otherwise. Reuses `render` for the compact case so the two can never drift.
7816pub fn render_indented(v: &JqVal, indent: usize) -> String {
7817    json_indented(v, indent).trim_end_matches('\n').to_string()
7818}
7819
7820fn json_indented(v: &JqVal, indent: usize) -> String {
7821    if indent == 0 {
7822        return render(v);
7823    }
7824    let mut out = String::new();
7825    write_indented(&mut out, v, 0, indent);
7826    out.push('\n');
7827    out
7828}
7829
7830fn write_indented(out: &mut String, v: &JqVal, depth: usize, step: usize) {
7831    let pad = |out: &mut String, d: usize| out.push_str(&" ".repeat(d * step));
7832    match v.bare() {
7833        JqVal::Arr(a) if !a.is_empty() => {
7834            out.push_str("[\n");
7835            for (i, e) in a.iter().enumerate() {
7836                pad(out, depth + 1);
7837                write_indented(out, e, depth + 1, step);
7838                if i + 1 < a.len() {
7839                    out.push(',');
7840                }
7841                out.push('\n');
7842            }
7843            pad(out, depth);
7844            out.push(']');
7845        }
7846        JqVal::Obj(m) if !m.is_empty() => {
7847            out.push_str("{\n");
7848            for (i, (k, val)) in m.iter().enumerate() {
7849                pad(out, depth + 1);
7850                out.push_str(&render(&JqVal::Str(k.clone())));
7851                out.push_str(": ");
7852                write_indented(out, val, depth + 1, step);
7853                if i + 1 < m.len() {
7854                    out.push(',');
7855                }
7856                out.push('\n');
7857            }
7858            pad(out, depth);
7859            out.push('}');
7860        }
7861        other => out.push_str(&render(other)),
7862    }
7863}
7864
7865/// Names the resolver must accept that `builtins` does not list, because jq does
7866/// not list them either: its own internal helpers.
7867const NATIVE_ONLY: &[&str] = &[
7868    "_sort_by_impl/1",
7869    "_group_by_impl/1",
7870    "_unique_by_impl/1",
7871    "_min_by_impl/1",
7872    "_max_by_impl/1",
7873    "_match_impl/3",
7874    "_split_re/2",
7875    "sub_impl/3",
7876    "_flatten/1",
7877    "_strindices/1",
7878];
7879
7880/// Reject a call to an undefined function or a reference to an unbound variable,
7881/// the way jq's compiler does. `funcs` holds `name/arity` keys.
7882fn check_names(
7883    f: &Filter,
7884    funcs: &std::collections::HashSet<String>,
7885    vars: &std::collections::HashSet<String>,
7886) -> Result<(), String> {
7887    match f {
7888        Filter::Identity | Filter::RecurseDefault | Filter::Lit(_) | Filter::Format(_) => Ok(()),
7889        Filter::Str(pieces, _) => {
7890            for p in pieces {
7891                if let StrPiece::Interp(src) = p {
7892                    check_names(&parse(src)?, funcs, vars)?;
7893                }
7894            }
7895            Ok(())
7896        }
7897        Filter::Field(a, _)
7898        | Filter::Iterate(a)
7899        | Filter::Optional(a)
7900        | Filter::IndexOpt(a)
7901        | Filter::Neg(a) => check_names(a, funcs, vars),
7902        Filter::Index(a, b)
7903        | Filter::Pipe(a, b)
7904        | Filter::Comma(a, b)
7905        | Filter::Bin(_, a, b)
7906        | Filter::And(a, b)
7907        | Filter::Or(a, b)
7908        | Filter::Alt(a, b)
7909        | Filter::Assign(_, a, b) => {
7910            check_names(a, funcs, vars)?;
7911            check_names(b, funcs, vars)
7912        }
7913        Filter::Slice(a, lo, hi) => {
7914            check_names(a, funcs, vars)?;
7915            for x in [lo, hi].into_iter().flatten() {
7916                check_names(x, funcs, vars)?;
7917            }
7918            Ok(())
7919        }
7920        Filter::If(arms, els) => {
7921            for (c, t) in arms {
7922                check_names(c, funcs, vars)?;
7923                check_names(t, funcs, vars)?;
7924            }
7925            match els {
7926                Some(e) => check_names(e, funcs, vars),
7927                None => Ok(()),
7928            }
7929        }
7930        Filter::Try(a, h) => {
7931            check_names(a, funcs, vars)?;
7932            match h {
7933                Some(x) => check_names(x, funcs, vars),
7934                None => Ok(()),
7935            }
7936        }
7937        Filter::Reduce(src, pat, init, upd) => {
7938            check_names(src, funcs, vars)?;
7939            check_names(init, funcs, vars)?;
7940            let inner = with_pattern_vars(vars, std::slice::from_ref(pat));
7941            check_names(upd, funcs, &inner)
7942        }
7943        Filter::Foreach(src, pat, init, upd, ext) => {
7944            check_names(src, funcs, vars)?;
7945            check_names(init, funcs, vars)?;
7946            let inner = with_pattern_vars(vars, std::slice::from_ref(pat));
7947            check_names(upd, funcs, &inner)?;
7948            match ext {
7949                Some(e) => check_names(e, funcs, &inner),
7950                None => Ok(()),
7951            }
7952        }
7953        Filter::Bind(src, pats, body) => {
7954            check_names(src, funcs, vars)?;
7955            let inner = with_pattern_vars(vars, pats);
7956            check_names(body, funcs, &inner)
7957        }
7958        Filter::Label(name, body) => {
7959            let mut inner = vars.clone();
7960            inner.insert(format!("*label*{name}"));
7961            check_names(body, funcs, &inner)
7962        }
7963        Filter::Break(name) => {
7964            if vars.contains(&format!("*label*{name}")) {
7965                Ok(())
7966            } else {
7967                Err(format!("jq: $*label-{name} is not defined"))
7968            }
7969        }
7970        Filter::Var(name) => {
7971            if vars.contains(&**name) {
7972                Ok(())
7973            } else {
7974                Err(format!("jq: ${name} is not defined"))
7975            }
7976        }
7977        Filter::Call(name, args) => {
7978            let key = format!("{name}/{}", args.len());
7979            if !funcs.contains(&key) {
7980                return Err(format!("jq: {key} is not defined"));
7981            }
7982            for a in args {
7983                check_names(a, funcs, vars)?;
7984            }
7985            Ok(())
7986        }
7987        Filter::Def(def, rest) => {
7988            let mut outer = funcs.clone();
7989            outer.insert(format!("{}/{}", def.name, def.params.len()));
7990            let mut inner = outer.clone();
7991            for p in &def.params {
7992                inner.insert(format!("{p}/0"));
7993            }
7994            // A `$p` parameter is desugared into `p as $p | …`, so the variable
7995            // it binds is introduced by that `Bind` and needs nothing here.
7996            check_names(&def.body, &inner, vars)?;
7997            check_names(rest, &outer, vars)
7998        }
7999        Filter::Object(entries) => {
8000            for ObjEntry::KeyVal(k, v) in entries {
8001                check_names(k, funcs, vars)?;
8002                check_names(v, funcs, vars)?;
8003            }
8004            Ok(())
8005        }
8006        Filter::Array(inner) => match inner {
8007            Some(x) => check_names(x, funcs, vars),
8008            None => Ok(()),
8009        },
8010    }
8011}
8012
8013fn with_pattern_vars(
8014    vars: &std::collections::HashSet<String>,
8015    pats: &[Pattern],
8016) -> std::collections::HashSet<String> {
8017    let mut out = vars.clone();
8018    let mut names = Vec::new();
8019    for p in pats {
8020        collect_pattern_vars(p, &mut names);
8021    }
8022    out.extend(names.into_iter().map(|n| n.to_string()));
8023    out
8024}
8025
8026/// Visit every sub-filter of `f` exactly once. Used by the whole-program
8027/// questions (`reads_input_stream`) that do not care about structure, only about
8028/// whether some node appears.
8029fn for_each_child(f: &Filter, visit: &mut dyn FnMut(&Filter)) {
8030    match f {
8031        Filter::Identity
8032        | Filter::RecurseDefault
8033        | Filter::Lit(_)
8034        | Filter::Format(_)
8035        | Filter::Var(_)
8036        | Filter::Break(_)
8037        | Filter::Str(..) => {}
8038        Filter::Field(a, _)
8039        | Filter::Iterate(a)
8040        | Filter::Optional(a)
8041        | Filter::IndexOpt(a)
8042        | Filter::Neg(a) => {
8043            visit(a);
8044        }
8045        Filter::Index(a, b)
8046        | Filter::Pipe(a, b)
8047        | Filter::Comma(a, b)
8048        | Filter::Bin(_, a, b)
8049        | Filter::And(a, b)
8050        | Filter::Or(a, b)
8051        | Filter::Alt(a, b)
8052        | Filter::Assign(_, a, b) => {
8053            visit(a);
8054            visit(b);
8055        }
8056        Filter::Slice(a, lo, hi) => {
8057            visit(a);
8058            for x in [lo, hi].into_iter().flatten() {
8059                visit(x);
8060            }
8061        }
8062        Filter::If(arms, els) => {
8063            for (c, t) in arms {
8064                visit(c);
8065                visit(t);
8066            }
8067            if let Some(e) = els {
8068                visit(e);
8069            }
8070        }
8071        Filter::Try(a, h) => {
8072            visit(a);
8073            if let Some(x) = h {
8074                visit(x);
8075            }
8076        }
8077        Filter::Reduce(src, _, init, upd) => {
8078            visit(src);
8079            visit(init);
8080            visit(upd);
8081        }
8082        Filter::Foreach(src, _, init, upd, ext) => {
8083            visit(src);
8084            visit(init);
8085            visit(upd);
8086            if let Some(e) = ext {
8087                visit(e);
8088            }
8089        }
8090        Filter::Bind(src, _, body) => {
8091            visit(src);
8092            visit(body);
8093        }
8094        Filter::Label(_, body) => visit(body),
8095        Filter::Call(_, args) => args.iter().for_each(|a| visit(a)),
8096        Filter::Def(def, rest) => {
8097            visit(&def.body);
8098            visit(rest);
8099        }
8100        Filter::Object(entries) => {
8101            for ObjEntry::KeyVal(k, v) in entries {
8102                visit(k);
8103                visit(v);
8104            }
8105        }
8106        Filter::Array(inner) => {
8107            if let Some(x) = inner {
8108                visit(x);
8109            }
8110        }
8111    }
8112}