Skip to main content

unityrs_core/walk/python/
mod.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/TypeTreeHelper.py, UnityPy/streams/EndianBinaryReader.py. See THIRD_PARTY_LICENSES.
2//! UnityPy's pure-Python reader (`helpers/TypeTreeHelper.py:182-361`), for
3//! objects with `byte_size == 0`. It starts at `byte_start` in the whole
4//! `SerializedFile` and may read on past the object, with Python's reader
5//! rules at any position ([`crate::stream`]'s helpers; the position may go
6//! negative). **Alignment is relative to the file**, not the object:
7//! `align_stream` rounds the absolute position. Its differences from
8//! UnityPyBoost are `docs/CANONICAL_DUMP.md` section 7's list: aligned
9//! primitive arrays become tuples, with 16-bit signedness swapped; an
10//! aligned `SInt8` array raises at every length (`read_byte_array(reader,
11//! size)` before any loop), and an array of aligned `TypelessData` raises
12//! only when its length is above 0 (`read_bytes()` inside the loop; an empty
13//! one reads as `[]`); a negative or out-of-range string
14//! length reads as `""`, and a string of length 0 or read as `""` that way
15//! is not aligned after (`read_aligned_string` returns before
16//! `align_stream`: the base reader's, `streams/EndianBinaryReader.py:146-153`,
17//! which `FUNCTION_READ_MAP` holds for a `string` node and a `pair` run's
18//! child, and for an array's elements read from bytes the memoryview
19//! reader's override, `:266-273`, the same body); in an array whose aligned
20//! element is a vector, a negative inner length reads as `[]`, unless the
21//! inner element is an aligned primitive, whose `struct` format rejects it
22//! (`struct.error`, `other`); arrays of aligned classes align once and skip the
23//! registry check; `TypelessData` length -1 reads to the end of the file and
24//! other negative lengths follow Python slice semantics (so `bytes_read` can
25//! be negative), on the memory reader: a file loaded from a path is read by
26//! the stream reader's rules ([`read_with_reader`]), where such a length
27//! raises and no read passes the end; a `pair` with three or more children reads its first two,
28//! and an `Array` with three or more reads its elements through
29//! `m_Children[1]` (`:216`, `:309`), where UnityPyBoost raises both;
30//! an aligned `pair` array reads a child whose type is a key of
31//! `FUNCTION_READ_MAP` (every primitive, `string`, `TypelessData`) through
32//! that function, without the child's own align flag (a non-empty `string`
33//! still aligns itself, as `read_aligned_string` does), and any other child
34//! (a class, a vector, a `pair`) through `read_value`, which keeps its flag
35//! (`TypeTreeHelper.py:285-293`); a `ReferencedObject` reads `type` before anything else (a
36//! missing key is `KeyError`, `other`; a `type` with no `class`, `ns` or
37//! `asm` is `KeyError` and a non-dict `type` `AttributeError`, `:89-97`, both
38//! `other` where UnityPyBoost reports `ref_type`) and raises `SerializedFile has no
39//! ref_types` for an empty or absent list *before* the empty-class skip (no
40//! `ref_types` attribute is an `AttributeError` whose message the dump maps
41//! to `ref_type`); an aligned `pair` element with fewer than two children
42//! raises `IndexError` (`other`) at every length, since `m_Children[0]` and
43//! `[1]` are read before the loop (`:282-283`), while an empty array of
44//! non-aligned malformed `pair`s, or of three-child `pair`s, reads as `[]`
45//! (the probes: `CANONICAL_DUMP.md` section 7); likewise an aligned vector
46//! element whose `Array` has fewer than two children raises `IndexError` at
47//! every length, the empty one included, since `m_Children[0].m_Children[1]`
48//! is read before the loop (`:309`), where UnityPyBoost reads an empty one
49//! as `[]` (`read_value_array` reads an aligned element's `pair` children
50//! and its vector's element before its loop, and indexes everywhere else
51//! inside it); outside an array, a vector reads its length, and refuses a
52//! negative one, before it indexes its `Array`'s element (`:213-216`), and a
53//! `pair` reads its first child before it indexes its second (`:194-195`),
54//! so a malformed one fails with whatever those reads raise first (a vector
55//! whose `Array` has fewer than two children is `negative_length` at length
56//! -1 and `IndexError`, `other`, at 0), where UnityPyBoost checks each arity
57//! first and reports `other`: this reader never fails a compiled
58//! `BadVector` or `BadPair` on entry; and an
59//! aligned `ReferencedObject` array element whose class is empty or whose ref
60//! type has no tree raises ([`super::ReadDetail::RefTypeNoTree`]). Each
61//! difference is an oracle fixture of package B (plan section 7.3).
62//!
63//! Owner: package B.
64
65use std::sync::Arc;
66
67use bytes::Bytes;
68
69use super::dict::{Dict, FindError, RefIndex, RefNode, Trees, ref_tree, visit};
70use super::{
71    FloatMode, Out, ReadCtx, ReadDetail, ReadError, ReadErrorKind, RefTypes, Work, charge_error,
72    f32_bits, int, limit_refused, stream_refused, uint,
73};
74use crate::raw::RawStr;
75use crate::stream::{Endian, ReaderKind};
76use crate::typetree::{Kind, NodeId, Tree};
77use crate::value::{ListIx, Parsed, ReadBy, Value, ValueBuilder};
78
79/// Reads one value from `file` by the memory reader's rules (bytes),
80/// starting at `start` (any Python position). `bytes_read` counts from
81/// `start` and may be negative. Its work is the open's, counted on
82/// `ctx.meter` whatever the outcome (the module docs of [`super`], "Work").
83pub fn read(
84    file: &Bytes,
85    start: i128,
86    tree: &Arc<Tree>,
87    ctx: &ReadCtx<'_>,
88) -> Result<Parsed, ReadError> {
89    read_with_reader(file, start, tree, ctx, ReaderKind::Memory)
90}
91
92/// [`read`] by the rules of the file's reader: on the stream reader (a file
93/// loaded from a path) `start` is a position its `seek` took (never
94/// negative), a read stops at the end, a fixed-width read is
95/// `unpack(read(n))`, a `TypelessData` length below -1 raises, and an
96/// alignment to 2^63 or more raises as the `seek` it makes does
97/// ([`crate::stream::ReaderKind`]), so `bytes_read` is never negative.
98pub fn read_with_reader(
99    file: &Bytes,
100    start: i128,
101    tree: &Arc<Tree>,
102    ctx: &ReadCtx<'_>,
103    kind: ReaderKind,
104) -> Result<Parsed, ReadError> {
105    read_with_mode(file, start, tree, ctx, kind, (false, false))
106}
107
108pub(crate) fn read_with_mode(
109    file: &Bytes,
110    start: i128,
111    tree: &Arc<Tree>,
112    ctx: &ReadCtx<'_>,
113    kind: ReaderKind,
114    (head, object_mode): (bool, bool),
115) -> Result<Parsed, ReadError> {
116    read_with_fields(file, start, tree, ctx, kind, (head, object_mode), None)
117}
118
119pub(crate) fn read_with_fields(
120    file: &Bytes,
121    start: i128,
122    tree: &Arc<Tree>,
123    ctx: &ReadCtx<'_>,
124    kind: ReaderKind,
125    (head, object_mode): (bool, bool),
126    progress: Option<&mut super::FieldProgress>,
127) -> Result<Parsed, ReadError> {
128    let work = Work::start(ctx.options.limits, ctx.meter)?;
129    let builder =
130        ValueBuilder::new(ctx.meter, tree.list().clone()).map_err(|e| charge_error(0, e))?;
131    let trees = Trees::new(&builder, tree)?;
132    let mut r = Reader {
133        data: file,
134        bytes: file.as_ref(),
135        pos: start,
136        start,
137        kind,
138        head,
139        object_mode,
140        progress,
141        big: ctx.endian == Endian::Big,
142        floats: ctx.options.floats,
143        ref_types: ctx.ref_types,
144        refs: RefIndex::new(ctx.ref_types),
145        builder,
146        trees,
147        work,
148        has_registry: false,
149    };
150    let value = r.value(tree, 0, tree.root());
151    let at = r.at();
152    let ended = r.work.finish(at);
153    let value = value?;
154    ended?;
155    let built = value.into_built(&r.builder, at)?;
156    // UnityPy TypeTreeHelper.py:153: `bytes_read = reader.Position - pos`.
157    let read = r.pos.saturating_sub(start);
158    let bytes_read = i64::try_from(read).unwrap_or(if read < 0 { i64::MIN } else { i64::MAX });
159    let Reader { builder, .. } = r;
160    Ok(builder
161        .finish(built, bytes_read)
162        .with_read_by(ReadBy::Python))
163}
164
165/// `EndianBinaryReader_Memoryview` over the whole file
166/// (`streams/EndianBinaryReader.py:231-284`), or `_Streamable` (`:287-324`)
167/// for a file loaded from a path, and `TypeTreeConfig`
168/// (`helpers/TypeTreeHelper.py:78-85`).
169#[allow(clippy::struct_excessive_bools)] // Endian, tier, object mode and registry are independent.
170struct Reader<'a, 'c, 'p> {
171    data: &'a Bytes,
172    bytes: &'a [u8],
173    /// `reader.Position`: any Python integer on the memory reader (plan
174    /// 3.3); never negative on the stream reader.
175    pos: i128,
176    start: i128,
177    /// Which reader's rules.
178    kind: ReaderKind,
179    /// SF 23+ selects HEAD's aligned byte-array behavior.
180    head: bool,
181    object_mode: bool,
182    progress: Option<&'p mut super::FieldProgress>,
183    big: bool,
184    floats: FloatMode,
185    ref_types: RefTypes<'c>,
186    /// The ref types' search, one per read ([`RefIndex`]).
187    refs: RefIndex<'c>,
188    builder: ValueBuilder,
189    trees: Trees,
190    work: Work<'c>,
191    /// `config.has_registry`.
192    has_registry: bool,
193}
194
195/// A fixed-width number from its bytes in the file's order.
196macro_rules! num {
197    ($big:expr, $t:ty, $b:expr) => {
198        if $big {
199            <$t>::from_be_bytes($b)
200        } else {
201            <$t>::from_le_bytes($b)
202        }
203    };
204}
205
206// Declared after `num!`, which it reads with.
207mod array;
208
209/// A Python exception the reader raises.
210#[derive(Clone, Copy)]
211enum Py {
212    /// `struct.error`: an unpack past the buffer, a negative count.
213    Struct(u64),
214    /// `IndexError` on a node's `m_Children`.
215    Index,
216    /// A `TypeError` or `KeyError`/`AttributeError` (kind `other`).
217    Other(&'static str),
218    /// No Python exception: the open's work passed its allowance.
219    Limit(crate::error::LimitError),
220}
221
222impl Reader<'_, '_, '_> {
223    fn at(&self) -> u64 {
224        u64::try_from(self.pos.saturating_sub(self.start)).unwrap_or(0)
225    }
226
227    fn fail(&self, kind: ReadErrorKind, detail: ReadDetail) -> ReadError {
228        ReadError {
229            kind,
230            at: self.at(),
231            detail,
232        }
233    }
234
235    fn raise(&self, e: Py) -> ReadError {
236        match e {
237            // The dump maps none of these messages to a kind of its own.
238            Py::Struct(need) => self.fail(
239                ReadErrorKind::Other,
240                ReadDetail::Eof {
241                    need,
242                    exception: "error",
243                },
244            ),
245            Py::Index => self.fail(ReadErrorKind::Other, ReadDetail::Python("IndexError")),
246            Py::Other(m) => self.fail(ReadErrorKind::Other, ReadDetail::Python(m)),
247            Py::Limit(l) => limit_refused(self.at(), l),
248        }
249    }
250
251    /// `read(size)` by the reader's rules ([`ReaderKind::read`]): the range
252    /// it returns, the position moved; the stream reader refuses a size
253    /// below -1. A read that takes the position back (the memory reader's
254    /// negative size, its -1 past the end) is work the read will repeat
255    /// ([`Work::discard`]).
256    fn read(&mut self, size: i64) -> Result<std::ops::Range<usize>, ReadError> {
257        let (range, next) = self
258            .kind
259            .read(self.bytes.len(), self.pos, size)
260            .map_err(|e| stream_refused(self.at(), e))?;
261        if next < self.pos {
262            self.work.discard();
263        }
264        self.pos = next;
265        Ok(range)
266    }
267
268    /// `unpack(fmt, self.read(N))`, the base class's `read_byte`, `read_int`,
269    /// `read_float`... (`EndianBinaryReader.py:93-127`): `FUNCTION_READ_MAP`
270    /// holds these base functions (`TypeTreeHelper.py:29-52`), so every
271    /// primitive node read through it takes this path. On the memory reader
272    /// `read` is a Python slice that moves the position by `N` whatever it
273    /// returns, and `unpack` raises unless it has exactly `N` bytes: so at
274    /// position `-N` (`view[-N:0]`, empty) it raises where `unpack_from`
275    /// reads the last `N` bytes ([`Self::unpack_from`]). On the stream
276    /// reader `read` stops at the end.
277    fn read_n<const N: usize>(&mut self) -> Result<[u8; N], ReadError> {
278        let range = self.read(i64::try_from(N).unwrap_or(i64::MAX))?;
279        self.bytes
280            .get(range)
281            .and_then(|s| <[u8; N]>::try_from(s).ok())
282            .ok_or_else(|| self.raise(Py::Struct(N as u64)))
283    }
284
285    /// `read(1)` then `unpack` ([`Self::read_n`]).
286    fn read1(&mut self) -> Result<u8, ReadError> {
287        let [b] = self.read_n::<1>()?;
288        Ok(b)
289    }
290
291    /// The reader's own `read_int` of `N` bytes, set on the instance by the
292    /// `endian` setter (`EndianBinaryReader.py:75-82`, `:335-349`): the
293    /// lengths the reader reads with `reader.read_int()` (a vector's, a
294    /// string's, a `TypelessData`'s). On the memory reader
295    /// `struct.unpack_from(view, Position)`, the position moving on success
296    /// only; on the stream reader `unpack(stream.read(N))`
297    /// ([`ReaderKind::unpack`]).
298    fn unpack_from<const N: usize>(&mut self) -> Result<[u8; N], ReadError> {
299        let (at, next) = self.kind.unpack(self.bytes.len(), self.pos, N);
300        let b = at
301            .and_then(|at| self.bytes.get(at..at.checked_add(N)?))
302            .and_then(|s| <[u8; N]>::try_from(s).ok());
303        let Some(b) = b else {
304            let e = self.raise(Py::Struct(N as u64));
305            self.pos = next;
306            return Err(e);
307        };
308        self.pos = next;
309        Ok(b)
310    }
311
312    /// `reader.read_int()`: the instance's [`Self::unpack_from`].
313    fn read_int(&mut self) -> Result<i32, ReadError> {
314        let big = self.big;
315        Ok(num!(big, i32, self.unpack_from()?))
316    }
317
318    /// One frame UnityPy's reader pushes on its way down (plan 3.10,
319    /// "Bounds"): a `read_value` or `read_value_array` call, a list or dict
320    /// comprehension, the lambda a `pair` array reads a non-primitive child
321    /// through. Each counts one level against `max_value_depth`, so the count
322    /// is the depth of Python frames UnityPy's reader reaches (less the two
323    /// or fewer of its leaf reads, `read_int` and the like). Python raises
324    /// `RecursionError` past 1,000 frames less its caller's, so every object
325    /// it refuses that way passes `max_value_depth` (512) here first.
326    fn frame<R>(
327        &mut self,
328        f: impl FnOnce(&mut Self) -> Result<R, ReadError>,
329    ) -> Result<R, ReadError> {
330        self.work.enter(self.at())?;
331        let out = f(self);
332        self.work.leave();
333        out
334    }
335
336    /// `align_stream` (`EndianBinaryReader.py:155-156`): Python's floor modulo
337    /// on the file-absolute position, assigned through the `Position`
338    /// setter, which the stream reader refuses at 2^63 or more
339    /// ([`ReaderKind::align`]).
340    fn align(&mut self) -> Result<(), ReadError> {
341        self.pos = self
342            .kind
343            .align(self.pos, 4)
344            .map_err(|e| stream_refused(self.at(), e))?;
345        Ok(())
346    }
347
348    /// `FUNCTION_READ_MAP` (`TypeTreeHelper.py:29-52`) for a primitive
349    /// kind: the base class's `unpack(fmt, read(n))` ([`Self::read_n`]).
350    fn prim(&mut self, kind: Kind) -> Result<Value, ReadError> {
351        let big = self.big;
352        Ok(match kind {
353            Kind::S8 => int(i64::from(self.read1()?.cast_signed())),
354            Kind::U8 => int(i64::from(self.read1()?)),
355            Kind::Bool => Value::Bool(self.read1()? != 0),
356            Kind::S16 => int(i64::from(num!(big, i16, self.read_n()?))),
357            Kind::U16 => int(i64::from(num!(big, u16, self.read_n()?))),
358            Kind::S32 => int(i64::from(num!(big, i32, self.read_n()?))),
359            Kind::U32 => int(i64::from(num!(big, u32, self.read_n()?))),
360            Kind::S64 => int(num!(big, i64, self.read_n()?)),
361            Kind::U64 => uint(num!(big, u64, self.read_n()?)),
362            // `struct.unpack('f')` widens as UnityPyBoost does (probed: a
363            // signalling NaN comes back quiet).
364            Kind::F32 => Value::F32(f32_bits(num!(big, u32, self.read_n()?), self.floats)),
365            Kind::F64 => Value::F64(num!(big, u64, self.read_n()?)),
366            _ => return Err(self.raise(Py::Other("not a primitive"))),
367        })
368    }
369
370    /// `read_aligned_string` (`EndianBinaryReader.py:146-153`, the base
371    /// reader's, which `FUNCTION_READ_MAP` holds, and for an array's elements
372    /// read from bytes the memoryview reader's override, `:266-273`, the same
373    /// body): a length of 0, or one that is negative or past the end, is `""`
374    /// and does not align.
375    fn string(&mut self) -> Result<Value, ReadError> {
376        let len = self.read_int()?;
377        let room = i128::try_from(self.bytes.len())
378            .unwrap_or(i128::MAX)
379            .saturating_sub(self.pos);
380        if len > 0 && i128::from(len) <= room {
381            let range = self.read(i64::from(len))?;
382            let s = RawStr::from_shared(self.data.slice(range));
383            self.align()?;
384            return Ok(Value::Str(s));
385        }
386        Ok(Value::Str(RawStr::default()))
387    }
388
389    /// `read_byte_array` (`EndianBinaryReader.py:158-159`): `read(read_int())`:
390    /// 0 is empty and -1 reads to the end; on the memory reader a Python
391    /// slice, so any other negative length moves the position back; on the
392    /// stream reader one below -1 raises (`ValueError` "read length must be
393    /// non-negative or -1") and a read past the end stops there.
394    fn typeless(&mut self) -> Result<Value, ReadError> {
395        let len = self.read_int()?;
396        let range = self.read(i64::from(len))?;
397        Ok(Value::Bytes(self.data.slice(range)))
398    }
399
400    fn value(&mut self, t: &Arc<Tree>, lx: ListIx, node: NodeId) -> Result<Out, ReadError> {
401        if self.progress.as_ref().is_some_and(|p| p.error.is_some()) {
402            return Ok(Out::Plain(Value::Int(0)));
403        }
404        let at = self.at();
405        self.work.enter(at)?;
406        let out = self.value_inner(t, lx, node);
407        self.work.leave();
408        self.recover(out)
409    }
410
411    fn recover(&mut self, out: Result<Out, ReadError>) -> Result<Out, ReadError> {
412        match (out, &mut self.progress) {
413            (Err(error), Some(progress)) => progress.recover(error),
414            (out, _) => out,
415        }
416    }
417
418    fn child(t: &Tree, node: NodeId, i: usize) -> Result<NodeId, Py> {
419        t.list().children(node).get(i).copied().ok_or(Py::Index)
420    }
421
422    /// The vector's `Array` child, when the node reads as one: its first
423    /// child's `m_Type` is `"Array"` (`TypeTreeHelper.py:208`, `:306`).
424    fn array_child(t: &Tree, node: NodeId) -> Option<NodeId> {
425        let first = *t.list().children(node).first()?;
426        (t.py_kind(first) == Kind::Array).then_some(first)
427    }
428
429    /// `read_value` (`TypeTreeHelper.py:182-263`).
430    fn value_inner(&mut self, t: &Arc<Tree>, lx: ListIx, node: NodeId) -> Result<Out, ReadError> {
431        self.work.values(1, self.at())?;
432        let mut align = t.info(node).is_some_and(|i| i.align);
433        let kind = t.py_kind(node);
434        let out = if kind.prim_size().is_some() {
435            Out::Plain(self.prim(kind)?)
436        } else if kind == Kind::Str {
437            Out::Plain(self.string()?)
438        } else if kind == Kind::Bytes {
439            Out::Plain(self.typeless()?)
440        } else if kind == Kind::Pair {
441            // `:193-196`: the first child is read before the second is indexed.
442            let a = Self::child(t, node, 0).map_err(|e| self.raise(e))?;
443            let first = self.value(t, lx, a)?;
444            let second = match Self::child(t, node, 1) {
445                Ok(b) => self.value(t, lx, b)?,
446                Err(error) => {
447                    let error = self.raise(error);
448                    self.recover(Err(error))?;
449                    return self.tuple([first]);
450                }
451            };
452            self.tuple(vec_of2(first, second))?
453        } else if kind == Kind::ReferencedObject {
454            self.ref_object(t, lx, node, false)?
455        } else if let Some(array) = Self::array_child(t, node) {
456            // `:208-220`.
457            align |= t.info(array).is_some_and(|i| i.align);
458            let size = self.read_int()?;
459            let Ok(count) = usize::try_from(size) else {
460                return Err(self.fail(
461                    ReadErrorKind::NegativeLength,
462                    ReadDetail::NegativeLength(i64::from(size)),
463                ));
464            };
465            let elem = Self::child(t, array, 1).map_err(|e| self.raise(e))?;
466            if t.info(elem).is_some_and(|i| i.align) {
467                self.array(t, lx, elem, i64::from(size))?
468            } else {
469                // `[read_value(subtype, ...) for _ in range(size)]`: a frame.
470                self.frame(|r| r.list(t, lx, elem, count))?
471            }
472        } else {
473            self.class(t, lx, node)?
474        };
475        if align {
476            self.align()?;
477        }
478        Ok(out)
479    }
480
481    fn tuple<const N: usize>(&mut self, items: [Out; N]) -> Result<Out, ReadError> {
482        let at = self.at();
483        let mut v = self.builder.vec();
484        v.reserve_exact(N).map_err(|e| charge_error(at, e))?;
485        for item in items {
486            item.push_to(&mut v).map_err(|e| charge_error(at, e))?;
487        }
488        let built = self.builder.tuple(v).map_err(|e| charge_error(at, e))?;
489        Ok(Out::Built(built))
490    }
491
492    fn remaining(&self) -> usize {
493        let len = i128::try_from(self.bytes.len()).unwrap_or(i128::MAX);
494        usize::try_from(len.saturating_sub(self.pos).max(0)).unwrap_or(usize::MAX)
495    }
496
497    /// The class branch of `read_value` (`TypeTreeHelper.py:222-231`): children in order, a
498    /// `ManagedReferencesRegistry` skipped once one is in scope.
499    fn class(&mut self, t: &Arc<Tree>, lx: ListIx, node: NodeId) -> Result<Out, ReadError> {
500        self.dict(t, lx, node, true)
501    }
502
503    /// An aligned class element's `{child.m_Name: read_value(child) ...}`
504    /// (`TypeTreeHelper.py:316-318`), a dict comprehension and so a frame: no registry check.
505    fn plain_class(&mut self, t: &Arc<Tree>, lx: ListIx, node: NodeId) -> Result<Out, ReadError> {
506        self.frame(|r| r.dict(t, lx, node, false))
507    }
508
509    /// A class's dict, grown as its children are read ([`Dict`]): no pass
510    /// over them first (review round 7, as in UnityPyBoost's reader).
511    fn dict(
512        &mut self,
513        t: &Arc<Tree>,
514        lx: ListIx,
515        node: NodeId,
516        registry: bool,
517    ) -> Result<Out, ReadError> {
518        let at = self.at();
519        let kids = t.list().children(node);
520        let is_registry = |c: NodeId| registry && t.py_kind(c) == Kind::ManagedReferencesRegistry;
521        let dup = t.info(node).is_some_and(|i| i.dup_names);
522        let mut d = Dict::new(
523            &self.builder,
524            kids.len(),
525            dup && self.progress.is_none(),
526            at,
527        )?;
528        let outer = self.has_registry;
529        for c in kids {
530            visit();
531            if is_registry(*c) {
532                if self.has_registry {
533                    // A skipped child counts as a value (plan 3.10, "Bounds").
534                    self.work.skipped(self.at())?;
535                    continue;
536                }
537                // `config = config.copy(); config.has_registry = True`: for
538                // the rest of this class only.
539                self.has_registry = true;
540            }
541            let v = self.value(t, lx, *c)?;
542            let (key, slot) = t.info(*c).map_or((*c, 0), |i| (i.key, i.slot));
543            let at = self.at();
544            d.set(
545                &mut self.work,
546                if self.progress.is_some() { *c } else { key },
547                slot,
548                v,
549                at,
550            )?;
551            if self.progress.as_ref().is_some_and(|p| p.error.is_some()) {
552                break;
553            }
554        }
555        self.has_registry = outer;
556        if self.object_mode
557            && self.progress.is_none()
558            && t.list().type_name(node).starts_with(b"PPtr<")
559        {
560            self.work
561                .open
562                .steps(kids.len())
563                .map_err(|e| limit_refused(self.at(), e))?;
564            let has = |name: &[u8]| {
565                kids.iter().any(|&c| {
566                    if registry {
567                        crate::walk::write::cleans_to(t.list().name(c), name)
568                    } else {
569                        t.list().name(c) == name
570                    }
571                })
572            };
573            if !has(b"m_FileID") || !has(b"m_PathID") {
574                return Err(self.raise(Py::Other(if !registry {
575                    "TypeError"
576                } else if !has(b"m_FileID") {
577                    "KeyError: m_FileID"
578                } else {
579                    "KeyError: m_PathID"
580                })));
581            }
582            if !registry
583                && kids
584                    .iter()
585                    .any(|&c| !matches!(t.list().name(c), b"m_FileID" | b"m_PathID"))
586            {
587                return Err(self.raise(Py::Other("TypeError")));
588            }
589        }
590        let result = d.finish(&self.builder, lx, self.at())?;
591        if let Some(progress) = &mut self.progress {
592            progress.finish_class();
593        }
594        Ok(result)
595    }
596
597    /// A `ReferencedObject` (`TypeTreeHelper.py:197-206`), or an aligned array's element
598    /// (`:294-304`, `in_array`), where a ref type with no node is read as
599    /// `read_value(None)` and raises. Its dict grows as its children are
600    /// read and keeps each name's position ([`Dict`]), and its `type` is the
601    /// entry of the first child named `type` read so far, as in the Boost
602    /// reader: no pass over its children first (review round 7).
603    fn ref_object(
604        &mut self,
605        t: &Arc<Tree>,
606        lx: ListIx,
607        node: NodeId,
608        in_array: bool,
609    ) -> Result<Out, ReadError> {
610        let at = self.at();
611        let kids = t.list().children(node);
612        let mut d = Dict::new(&self.builder, kids.len(), true, at)?;
613        d.preserve_fields(self.progress.is_some());
614        // The slot of the children named `type`, once one is visited.
615        let mut type_slot = None;
616        let mut object_type = false;
617        // The current `type`'s resolution, kept until a child sets `type`
618        // again, as the Boost reader keeps it.
619        let mut resolved: Option<Option<RefNode>> = None;
620        for c in kids {
621            visit();
622            let (key, slot) = t.info(*c).map_or((*c, 0), |i| (i.key, i.slot));
623            if type_slot.is_none() && t.info(*c).is_some() && t.list().name(*c) == b"type" {
624                type_slot = Some(slot);
625            }
626            if t.list().name(*c) == b"type" {
627                object_type = self.object_mode && t.py_kind(*c) != Kind::ReferencedObject;
628            }
629            let v = if t.py_kind(*c) == Kind::ReferencedObjectData {
630                let node = if let Some(r) = &resolved {
631                    r.clone()
632                } else {
633                    let ty = type_slot
634                        .and_then(|s| d.position(s))
635                        .and_then(|p| d.entries.as_slice().get(p))
636                        .map(|(_, v)| v);
637                    let found = match self.ref_node(ty, object_type) {
638                        Ok(found) => found,
639                        Err(error) => {
640                            if let Some(progress) = &mut self.progress {
641                                progress.recover(error)?;
642                                break;
643                            }
644                            return Err(error);
645                        }
646                    };
647                    resolved.insert(found).clone()
648                };
649                match (node, in_array) {
650                    (Some(RefNode::Tree(rt)), _) => {
651                        let at = self.at();
652                        let rlx = self.trees.index(&mut self.builder, &rt, at)?;
653                        self.value(&rt, rlx, rt.root())?
654                    }
655                    (None | Some(RefNode::NoTree), false) => {
656                        // A skipped child counts as a value (plan 3.10, "Bounds").
657                        self.work.skipped(self.at())?;
658                        continue;
659                    }
660                    (None | Some(RefNode::NoTree), true) => {
661                        let error = self.fail(ReadErrorKind::Other, ReadDetail::RefTypeNoTree);
662                        if let Some(progress) = &mut self.progress {
663                            progress.recover(error)?;
664                            break;
665                        }
666                        return Err(error);
667                    }
668                }
669            } else {
670                self.value(t, lx, *c)?
671            };
672            let at = self.at();
673            d.set(
674                &mut self.work,
675                if self.progress.is_some() { *c } else { key },
676                slot,
677                v,
678                at,
679            )?;
680            if self.progress.as_ref().is_some_and(|p| p.error.is_some()) {
681                break;
682            }
683            if Some(slot) == type_slot {
684                resolved = None;
685            }
686        }
687        let result = d.finish(&self.builder, lx, self.at())?;
688        if let Some(progress) = &mut self.progress {
689            progress.finish_class();
690        }
691        Ok(result)
692    }
693
694    /// `get_ref_type_node` (`TypeTreeHelper.py:88-109`) on the dict read so
695    /// far: `type` first (`KeyError`), then its `class`, `ns` and `asm`
696    /// (`KeyError`, or `AttributeError` when `type` is not a dict), then
697    /// `ref_types` (absent or empty: `ref_type`), then the empty-class skip,
698    /// then the scan.
699    fn ref_node(
700        &mut self,
701        ty: Option<&Value>,
702        object_type: bool,
703    ) -> Result<Option<RefNode>, ReadError> {
704        let Some(ty) = ty else {
705            return Err(self.raise(Py::Other("KeyError: 'type'")));
706        };
707        let Value::Dict(m) = ty else {
708            return Err(self.raise(Py::Other("AttributeError: no attribute 'class'")));
709        };
710        let at = self.at();
711        let mut field = |name: &'static [u8], msg: &'static str| match self.trees.field(
712            m,
713            name,
714            &mut self.work.open,
715            object_type,
716        ) {
717            Ok(Some(v)) => Ok(v),
718            Ok(None) if object_type => Err(Py::Other("AttributeError")),
719            Ok(None) => Err(Py::Other(msg)),
720            Err(l) => Err(Py::Limit(l)),
721        };
722        let fields = (|| {
723            Ok((
724                field(b"class", "KeyError: 'class'")?,
725                field(b"ns", "KeyError: 'ns'")?,
726                field(b"asm", "KeyError: 'asm'")?,
727            ))
728        })();
729        let (cls, ns, asm) = fields.map_err(|e| match e {
730            Py::Limit(l) => limit_refused(at, l),
731            e => self.raise(e),
732        })?;
733        if !matches!(self.ref_types, RefTypes::List(l) if !l.is_empty()) {
734            return Err(self.fail(
735                ReadErrorKind::RefType,
736                ReadDetail::NoRefTypes {
737                    reader: ReadBy::Python,
738                    absent: matches!(self.ref_types, RefTypes::Absent),
739                },
740            ));
741        }
742        if matches!(cls, Value::Str(s) if s.is_empty()) {
743            return Ok(None);
744        }
745        let found = self
746            .refs
747            .find(self.builder.meter(), &mut self.work.open, cls, ns, asm)
748            .map_err(|e| match e {
749                FindError::Charge(e) => charge_error(at, e),
750                FindError::Work(l) => limit_refused(at, l),
751            })?;
752        if let Some(r) = found {
753            Ok(Some(ref_tree(r, &self.work.limits, at)?))
754        } else {
755            if let (Some(progress), Value::Str(cls), Value::Str(ns), Value::Str(asm)) =
756                (&mut self.progress, cls, ns, asm)
757            {
758                progress.reference_names = Some([cls.clone(), ns.clone(), asm.clone()]);
759            }
760            Err(self.fail(ReadErrorKind::RefType, ReadDetail::RefTypeNotFound))
761        }
762    }
763}
764
765fn vec_of2(a: Out, b: Out) -> [Out; 2] {
766    [a, b]
767}