Skip to main content

unityrs_core/walk/write/
mod.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/TypeTreeHelper.py, UnityPy/streams/EndianBinaryWriter.py. See THIRD_PARTY_LICENSES.
2//! UnityPy's pure-Python writer (`helpers/TypeTreeHelper.py:161-179`,
3//! `:381-458`). Dispatch is on the type name first (`FUNCTION_WRITE_MAP`), then
4//! `pair`, `ReferencedObject`, an `Array` first child, and a class. Under
5//! [`super::WriteRules::UnityPy`] each array element aligns after itself when
6//! its node is flagged, then the vector or `Array` flag aligns once; a class
7//! writes `value[child.m_Name]` for every child, a missing key failing and an
8//! extra key ignored; `ReferencedObject` data needs a non-empty `ref_types`
9//! (`:99-100`) and a ref type with a tree: an empty class, or a matched ref
10//! type with no tree, fails (`KeyError: 'data'` when the reader left `data`
11//! out, else an `AttributeError` on the `None` node); integers are
12//! range-checked as `struct.pack` checks them.
13//!
14//! **Duck typing (W2).** The writer takes any value Python's operations
15//! accept, not only the variant the reader makes for the node, which a
16//! duplicate-name object exercises (its dict holds one child's value under
17//! the other's node). Probed on UnityPy 1.25.2: a `bool` node takes any value
18//! (its truthiness; an empty `Str`, `Bytes`, `List`, `Tuple` or `Dict` is
19//! false); an integer node takes `Bool` and `Int`/`UInt` in range; a `float`
20//! or `double` node takes `Bool`, integers and floats; a `string` node only
21//! `Str`; `TypelessData` only `Bytes`; a `pair` node anything with items 0
22//! and 1 (`List`, `Tuple`, `Prims` or `Bytes` of length 2 or more, a `Str`
23//! of 2 or more characters written through the children's kinds); an array
24//! any sized iterable (`List`, `Tuple`, `Prims`, `Bytes` as integers, `Str`
25//! as one-character strings, a `Dict` as its keys), each element written by
26//! the element node under the same rules; a class with no children any value
27//! (its non-dict branch iterates no children and writes nothing); a class
28//! with children a `Dict` (`value[child.m_Name]`) or any other value that has
29//! each child's cleaned name as a Python attribute (`getattr(value,
30//! child._clean_name)`, `TypeTreeHelper.py:447-455`: an `int` value satisfies a child named
31//! `real`, a `list` one named `count`, whose bound method a `bool` node
32//! writes as true). An `Array` node with three or more children writes its
33//! elements through `m_Children[1]` (`:434`), as the pure-Python reader
34//! reads them.
35//!
36//! **The mirror.** Under [`super::WriteRules::MirrorReader`] the writer
37//! takes the rules of the reader that built the value ([`Parsed::read_by`]):
38//! its kinds (`Writer::kind`), its runs (`run.rs`), its empty strings and its
39//! `ReferencedObject` data. Review round 11: it took UnityPyBoost's for every
40//! value, so it refused the pure-Python reader's value of a zero-byte object
41//! read through a type name holding a NUL, which UnityPy writes.
42//!
43//! Owner: package B.
44
45use std::sync::Arc;
46
47use bytes::Bytes;
48
49use super::dict::{FindError, RefIndex, steps, visit};
50use super::{
51    OpenWork, RefTypes, VALUE_WORK, WriteCtx, WriteError, WriteRules, py_size_field_is_zero,
52};
53use crate::budget::DecodeBuf;
54use crate::raw::RawStr;
55use crate::typetree::{Kind, NodeId, Tree, TreeError};
56use crate::value::{Map, Parsed, ReadBy, Value};
57
58mod bounds;
59mod lookup;
60mod pyobj;
61mod run;
62
63use lookup::{KeptTables, Lookup};
64use pyobj::{CLEAN_MAX, Obj, chars, clean_name, narrow};
65pub use pyobj::{cleans_to, python_attributes};
66
67/// Writes `parsed` through `tree` (the object's own tree, or a `nodes=`
68/// override: keys are then matched by name), appending to `out`, a buffer
69/// on the object's input's meter that charges before it grows (a value read
70/// with a negative length can name the same bytes many times, so the output
71/// can be far larger than the value; plan section 3.15). Its work is the
72/// open's of `out`'s meter, counted as it goes whatever the outcome
73/// (`OpenWork`): [`VALUE_WORK`] for each value it writes or child it
74/// skips, but a primitive, which counts the bytes it writes, as a read counts
75/// a primitive run's; and each step of finding a child's entry that builds
76/// no value ([`super::STEP_WORK`], and the bytes of a name it compares or
77/// hashes). A write is refused before it starts once the open's work has
78/// passed its allowance, and fails once its own work takes the open past
79/// it (the module docs of [`super`], "Work").
80pub fn write(
81    parsed: &Parsed,
82    tree: &Tree,
83    ctx: &WriteCtx<'_>,
84    out: &mut DecodeBuf,
85) -> Result<(), WriteError> {
86    write_at(parsed, tree, ctx, out, out.len())
87}
88
89/// Append an object while aligning relative to a caller's stream origin.
90/// UnityPy's supplied writer aligns its complete stream, including any prefix
91/// (`streams/EndianBinaryWriter.py:88-97`). An origin past the current output
92/// refuses before writing. [`write`] retains object-relative alignment.
93pub fn write_at(
94    parsed: &Parsed,
95    tree: &Tree,
96    ctx: &WriteCtx<'_>,
97    out: &mut DecodeBuf,
98    alignment_origin: usize,
99) -> Result<(), WriteError> {
100    write_at_with_lengths(parsed, tree, ctx, out, alignment_origin, &|_| None)
101}
102
103/// Append a Python writer snapshot whose protocol lengths may differ from
104/// storage sizes. Overrides affect only length prefixes; all retained bytes
105/// and yielded elements still count toward work and output limits.
106pub fn write_at_with_lengths(
107    parsed: &Parsed,
108    tree: &Tree,
109    ctx: &WriteCtx<'_>,
110    out: &mut DecodeBuf,
111    alignment_origin: usize,
112    lengths: &dyn Fn(&Value) -> Option<usize>,
113) -> Result<(), WriteError> {
114    if alignment_origin > out.len() {
115        return Err(WriteError::OutOfRange {
116            node: RawStr::from_static(b"writer alignment origin"),
117        });
118    }
119    let meter = out.meter().clone();
120    let open = OpenWork::start(&meter).map_err(WriteError::Limit)?;
121    let mut w = Writer {
122        parsed,
123        lengths,
124        out,
125        base: alignment_origin,
126        big: ctx.endian == crate::stream::Endian::Big,
127        mirror: match ctx.rules {
128            WriteRules::UnityPy => None,
129            WriteRules::MirrorReader => Some(parsed.read_by()),
130        },
131        ref_types: ctx.ref_types,
132        refs: RefIndex::new(ctx.ref_types),
133        max_depth: ctx.limits.max_value_depth,
134        limits: *ctx.limits,
135        depth: 0,
136        values: 0,
137        repeated: 0,
138        open,
139        has_registry: false,
140        shared: 0,
141        kept: KeptTables::new(parsed.charge().meter()),
142    };
143    let written = w.value(tree, tree.root(), Obj::V(parsed.value()));
144    let ended = w.open.finish();
145    drop(w);
146    written?;
147    ended.map_err(WriteError::Limit)
148}
149
150struct Writer<'a, 'o> {
151    parsed: &'a Parsed,
152    lengths: &'o dyn Fn(&Value) -> Option<usize>,
153    out: &'o mut DecodeBuf,
154    /// Alignment origin of the caller's stream within `out`.
155    base: usize,
156    big: bool,
157    /// The reader whose rules [`WriteRules::MirrorReader`] writes by (the
158    /// one that built the value, [`Parsed::read_by`]); `None` under
159    /// [`WriteRules::UnityPy`].
160    mirror: Option<ReadBy>,
161    ref_types: RefTypes<'a>,
162    /// The ref types' search, one per write ([`RefIndex`]).
163    refs: RefIndex<'a>,
164    limits: crate::limits::Limits,
165    max_depth: u32,
166    depth: u32,
167    /// What counts against `max_values_per_object` ([`Self::count`]).
168    values: u64,
169    /// How many children whose name a sibling repeats are being written
170    /// ([`crate::typetree::NodeInfo::repeated`]).
171    repeated: u32,
172    /// The open's work, counted as the write goes.
173    open: OpenWork<'o>,
174    has_registry: bool,
175    /// How many classes whose children repeat a name (`dup_names`) are
176    /// being written: inside one, a dict can be written once a sibling,
177    /// and its name table is kept ([`KeptTables`]).
178    shared: u32,
179    kept: KeptTables<'a>,
180}
181
182/// What a `ReferencedObject`'s data child writes through, resolved once a
183/// write of the dict.
184#[derive(Clone)]
185enum Data {
186    /// Nothing: [`WriteRules::MirrorReader`] writes no data the reader that
187    /// read the value skipped.
188    Skip,
189    /// The matched ref type's tree, or none (the write then fails).
190    Through(Option<Arc<Tree>>),
191}
192
193impl<'a> Writer<'a, '_> {
194    fn logical_len(&self, value: Obj<'_>) -> Option<usize> {
195        if let Obj::V(value) = value
196            && let Some(len) = (self.lengths)(value)
197        {
198            return Some(len);
199        }
200        Self::len(value)
201    }
202
203    fn name(tree: &Tree, node: NodeId) -> RawStr {
204        tree.list()
205            .row(node)
206            .map(|r| r.name.clone())
207            .unwrap_or_default()
208    }
209
210    fn mismatch(tree: &Tree, node: NodeId, expected: &'static str) -> WriteError {
211        WriteError::TypeMismatch {
212            node: Self::name(tree, node),
213            expected,
214        }
215    }
216
217    fn put(&mut self, bytes: &[u8]) -> Result<(), WriteError> {
218        self.out
219            .extend_from_slice(bytes)
220            .map_err(WriteError::Charge)
221    }
222
223    /// Counts a `str`'s bytes as the open's work before a pass over them
224    /// finds its characters (UTF-8, each byte of no character one escape),
225    /// to measure or index it by character: a repeated name hands one
226    /// string to any number of `pair` or array siblings, each of which made
227    /// that pass uncounted, in every write (review round 6's sweep).
228    fn str_work(&mut self, o: Obj<'_>) -> Result<(), WriteError> {
229        let n = match o {
230            Obj::V(Value::Str(s)) => s.len(),
231            Obj::Str(s) => s.len(),
232            _ => return Ok(()),
233        };
234        let n = u64::try_from(n).unwrap_or(u64::MAX);
235        self.open.add(n).map_err(WriteError::Limit)
236    }
237
238    /// `o[i]` ([`Self::item`]), a `str`'s pass counted first.
239    fn index(&mut self, o: Obj<'a>, i: usize) -> Result<Option<Obj<'a>>, WriteError> {
240        self.str_work(o)?;
241        Ok(Self::item(o, i))
242    }
243
244    /// Puts a string's or a byte array's bytes, each a byte of the open's
245    /// work, counted first: a read holds them as a slice of its input, in
246    /// one step, and a write copies them, so K writes of objects over one
247    /// long string copied it K times on [`VALUE_WORK`] each (review round
248    /// 6's sweep).
249    fn put_counted(&mut self, bytes: &[u8]) -> Result<(), WriteError> {
250        let n = u64::try_from(bytes.len()).unwrap_or(u64::MAX);
251        self.open.add(n).map_err(WriteError::Limit)?;
252        self.put(bytes)
253    }
254
255    /// `align_stream` (`EndianBinaryWriter.py:94-97`): zeros to a multiple
256    /// of 4 from the selected stream origin.
257    fn align(&mut self) -> Result<(), WriteError> {
258        let pos = self.out.len().saturating_sub(self.base);
259        let pad = (4 - pos % 4) % 4;
260        self.put([0; 4].get(..pad).unwrap_or_default())
261    }
262
263    fn write_int(&mut self, n: usize, tree: &Tree, node: NodeId) -> Result<(), WriteError> {
264        let n = i32::try_from(n).map_err(|_| WriteError::OutOfRange {
265            node: Self::name(tree, node),
266        })?;
267        let b = if self.big {
268            n.to_be_bytes()
269        } else {
270            n.to_le_bytes()
271        };
272        self.put(&b)
273    }
274
275    /// `d[name]` on a dict value, by key string: inside a class whose
276    /// children repeat a name, by the dict's kept table (the dict may be
277    /// written once a sibling); else by a scan, which each write of a
278    /// `ReferencedObject` makes once ([`Self::ref_object`]). Each entry the
279    /// scan passes is a step of the open's work, counted first.
280    fn field(&mut self, m: &'a Map, name: &[u8]) -> Result<Option<&'a Value>, WriteError> {
281        let pos = if self.shared > 0 {
282            steps(1);
283            self.kept.position(self.parsed, m, name, &mut self.open)?
284        } else {
285            let mut found = None;
286            for (i, (n, _)) in self.parsed.entries(m).enumerate() {
287                steps(1);
288                self.open.steps(1).map_err(WriteError::Limit)?;
289                if n == name {
290                    found = Some(i);
291                    break;
292                }
293            }
294            found
295        };
296        Ok(pos.and_then(|p| m.entries().get(p)).map(|(_, v)| v))
297    }
298
299    /// The children of a class or `ReferencedObject` `node`, written by `f`;
300    /// a node whose children repeat a name keeps the name tables built
301    /// inside it until the outermost such node is written ([`KeptTables`]).
302    fn children(
303        &mut self,
304        tree: &Tree,
305        node: NodeId,
306        f: impl FnOnce(&mut Self) -> Result<(), WriteError>,
307    ) -> Result<(), WriteError> {
308        let dup = tree.info(node).is_some_and(|i| i.dup_names);
309        if dup {
310            self.shared = self.shared.saturating_add(1);
311        }
312        // One call of `f`, so it inlines here: a frame less a level.
313        let r = f(self);
314        if dup {
315            self.shared = self.shared.saturating_sub(1);
316            if self.shared == 0 {
317                self.kept = KeptTables::new(self.parsed.charge().meter());
318            }
319        }
320        r
321    }
322
323    /// `child`'s entry by `find`, with the kept tables inside a class whose
324    /// children repeat a name ([`Lookup::get`]).
325    fn find(
326        &mut self,
327        find: &mut Lookup<'a>,
328        tree: &Tree,
329        child: NodeId,
330    ) -> Result<Option<&'a Value>, WriteError> {
331        let kept = (self.shared > 0).then_some(&mut self.kept);
332        find.get(self.parsed, tree, child, kept, &mut self.open)
333    }
334
335    fn value(&mut self, tree: &Tree, node: NodeId, o: Obj<'a>) -> Result<(), WriteError> {
336        self.count(self.cost(tree, node))?;
337        self.frame(|w| w.value_inner(tree, node, o))
338    }
339
340    /// The open's work of writing `node`'s value ([`write`]): its bytes for
341    /// a primitive, [`VALUE_WORK`] for any other value.
342    fn cost(&self, tree: &Tree, node: NodeId) -> u64 {
343        self.kind(tree, node)
344            .prim_size()
345            .map_or(VALUE_WORK, u64::from)
346    }
347
348    /// The kind the write dispatches `node` on: under [`WriteRules::UnityPy`]
349    /// its whole type name's (`FUNCTION_WRITE_MAP` is a dict, `node.m_Type
350    /// == "pair"` a comparison of `str`s: [`Tree::py_kind`]), and so under
351    /// [`WriteRules::MirrorReader`] for a value the pure-Python reader read,
352    /// which dispatches on the whole name too (`TypeTreeHelper.py:190-208`);
353    /// for one UnityPyBoost read, the name's to its first NUL, as that reader
354    /// takes it (a `PPtr<` is a class either way). So a value read through a
355    /// type name holding a NUL writes back to what reads as it, by either
356    /// reader (review round 10's cases: UnityPy writes an `int\0x` element as
357    /// a class with no children, which writes nothing, where UnityPyBoost
358    /// reads an `int`; review round 11: the pure-Python reader reads that
359    /// node as such a class, and the mirror, taking it as an `int`, refused
360    /// the value).
361    fn kind(&self, tree: &Tree, node: NodeId) -> Kind {
362        match self.mirror {
363            Some(ReadBy::Boost) => tree.info(node).map_or(Kind::Unknown, |i| i.kind),
364            None | Some(ReadBy::Python) => tree.py_kind(node),
365        }
366    }
367
368    /// `write_aligned_string` (`EndianBinaryWriter.py:88-92`), W3: its length,
369    /// its bytes, then aligned. Under the pure-Python mirror an empty string
370    /// is not aligned: `read_aligned_string` returns `""` before its
371    /// `align_stream` (the base reader's, `EndianBinaryReader.py:146-153`,
372    /// which `FUNCTION_READ_MAP` holds, and the memoryview reader's override,
373    /// `:266-273`, which an array's elements read from bytes run: the same
374    /// body).
375    fn string(&mut self, tree: &Tree, node: NodeId, o: Obj<'a>) -> Result<(), WriteError> {
376        let s = Self::as_str(o).ok_or_else(|| Self::mismatch(tree, node, "str"))?;
377        let len = match o {
378            Obj::V(value) => (self.lengths)(value),
379            _ => None,
380        }
381        .unwrap_or(s.len());
382        self.write_int(len, tree, node)?;
383        self.put_counted(s)?;
384        if s.is_empty() && self.mirror == Some(ReadBy::Python) {
385            return Ok(());
386        }
387        self.align()
388    }
389
390    /// `write_byte_array` (`EndianBinaryWriter.py:110-112`), W4: its length,
391    /// then its bytes.
392    fn bytes(&mut self, tree: &Tree, node: NodeId, o: Obj<'a>) -> Result<(), WriteError> {
393        let Obj::V(Value::Bytes(b)) = o else {
394            return Err(Self::mismatch(tree, node, "bytes"));
395        };
396        let len = match o {
397            Obj::V(value) => (self.lengths)(value),
398            _ => None,
399        }
400        .unwrap_or(b.len());
401        self.write_int(len, tree, node)?;
402        self.put_counted(b)
403    }
404
405    /// `write_value` (`TypeTreeHelper.py:407-458`). The branches that
406    /// recurse ([`Self::class`], [`Self::class_dict`], [`Self::ref_object`])
407    /// are never inlined here, so a level's frame holds only its own
408    /// branch's locals. Measured by `tests/walk_stack.rs`'s `stack_measured`
409    /// (release, toolchain 1.99.1): out of line, no path's write needs more
410    /// stack than its read (each `Written` path's least stack equals its
411    /// `Refused` one); with the three `#[inline(always)]`, the `pair` shape's
412    /// `Written(Boost, UnityPy)` needs 520,192 bytes, where its read needs
413    /// 393,216 (review round 11's re-measure: the figures this cited for the
414    /// `class` shape, from before fix pass 10, no longer reproduce).
415    fn value_inner(&mut self, tree: &Tree, node: NodeId, o: Obj<'a>) -> Result<(), WriteError> {
416        let mut align = tree.info(node).is_some_and(|i| i.align);
417        let kind = self.kind(tree, node);
418        let kids = tree.list().children(node);
419        if kind.prim_size().is_some() {
420            self.prim(tree, node, kind, o)?;
421        } else if kind == Kind::Str {
422            self.string(tree, node, o)?;
423        } else if kind == Kind::Bytes {
424            self.bytes(tree, node, o)?;
425        } else if kind == Kind::Pair {
426            // `:419-421`: `value[0]`, `value[1]` through the first two children.
427            for i in 0..2 {
428                let item = self
429                    .index(o, i)?
430                    .ok_or_else(|| Self::mismatch(tree, node, "a sequence of two"))?;
431                let child = kids
432                    .get(i)
433                    .copied()
434                    .ok_or_else(|| WriteError::Malformed(Self::name(tree, node)))?;
435                self.value(tree, child, item)?;
436            }
437        } else if kind == Kind::ReferencedObject {
438            self.ref_object(tree, node, o)?;
439        } else if let Some(array) = kids
440            .first()
441            .copied()
442            .filter(|c| self.kind(tree, *c) == Kind::Array)
443        {
444            // `:429-435`, W5.
445            align |= tree.info(array).is_some_and(|i| i.align);
446            self.str_work(o)?;
447            let n = self
448                .logical_len(o)
449                .ok_or_else(|| Self::mismatch(tree, node, "a sized iterable"))?;
450            self.write_int(n, tree, node)?;
451            let elem = tree
452                .list()
453                .children(array)
454                .get(1)
455                .copied()
456                .ok_or_else(|| WriteError::Malformed(Self::name(tree, node)))?;
457            self.frame(|w| w.elements(tree, elem, o))?;
458        } else {
459            self.class(tree, node, o, true)?;
460        }
461        if align {
462            self.align()?;
463        }
464        Ok(())
465    }
466
467    /// `FUNCTION_WRITE_MAP`'s numbers (`TypeTreeHelper.py:381-404`): an
468    /// integer node takes an `int` or `bool` in its range, a float node a
469    /// number, `bool` any object's truth.
470    fn prim(
471        &mut self,
472        tree: &Tree,
473        node: NodeId,
474        kind: Kind,
475        o: Obj<'a>,
476    ) -> Result<(), WriteError> {
477        let big = self.big;
478        let range = || WriteError::OutOfRange {
479            node: Self::name(tree, node),
480        };
481        // `struct.pack`'s bytes, built on the stack: a write charges only
482        // its output.
483        let mut buf = [0_u8; 8];
484        macro_rules! put {
485            ($v:expr) => {{
486                let v = $v;
487                let b = if big {
488                    v.to_be_bytes()
489                } else {
490                    v.to_le_bytes()
491                };
492                let n = b.len();
493                buf.get_mut(..n).unwrap_or_default().copy_from_slice(&b);
494                n
495            }};
496        }
497        macro_rules! int {
498            ($t:ty) => {{
499                let i = Self::as_int(o).ok_or_else(|| Self::mismatch(tree, node, "int"))?;
500                put!(<$t>::try_from(i).map_err(|_| range())?)
501            }};
502        }
503        let n = match kind {
504            // `pack('?', value)`: the object's truth.
505            Kind::Bool => put!(u8::from(Self::truthy(o))),
506            Kind::F32 => put!(match o {
507                // A float read from a `float` node packs back to its bits.
508                Obj::V(Value::F32(b)) => *b,
509                Obj::F32(b) => b,
510                _ => {
511                    let x =
512                        Self::as_double(o).ok_or_else(|| Self::mismatch(tree, node, "float"))?;
513                    narrow(x).ok_or_else(range)?
514                }
515            }),
516            Kind::F64 => {
517                let x = Self::as_double(o).ok_or_else(|| Self::mismatch(tree, node, "float"))?;
518                put!(x.to_bits())
519            }
520            Kind::S8 => int!(i8),
521            Kind::U8 => int!(u8),
522            Kind::S16 => int!(i16),
523            Kind::U16 => int!(u16),
524            Kind::S32 => int!(i32),
525            Kind::U32 => int!(u32),
526            Kind::S64 => int!(i64),
527            _ => int!(u64),
528        };
529        let (bytes, _) = buf.split_at(n.min(8));
530        // Every caller counted this value first, its bytes as its work
531        // ([`Self::cost`]).
532        self.put(bytes)
533    }
534
535    /// The class branch (`TypeTreeHelper.py:437-455`), W6: `value[child.m_Name]` for a dict
536    /// ([`Self::class_dict`]), `getattr(value, child._clean_name)` otherwise;
537    /// the registry scope as on read.
538    ///
539    /// On a value that is not a dict, each child whose write writes no byte
540    /// counts against `max_values_per_object` ([`Self::bound`]): its value is
541    /// an attribute of the class's (an `int` element's `real`, or a bound
542    /// method), which neither the value's memory nor the output bounds, so a
543    /// class of many such children, written for each element of an array,
544    /// would do work nothing else counts. A child that writes bytes is
545    /// bounded by the output, charged to the meter, and a class with no
546    /// children writes nothing, so neither counts (review round 10: a node
547    /// whose type name holds a NUL, which UnityPyBoost reads as a primitive,
548    /// a string or bytes, was counted once an element by this branch, and
549    /// its re-save refused past the default bound where UnityPy writes it).
550    ///
551    /// With `registry` false, a registry child is written as any other
552    /// child, and puts no registry in scope: the pure-Python reader reads a
553    /// flagged run's class elements so (`TypeTreeHelper.py:314-318`, [`Self::run_element`]).
554    #[inline(never)]
555    fn class(
556        &mut self,
557        tree: &Tree,
558        node: NodeId,
559        o: Obj<'a>,
560        registry: bool,
561    ) -> Result<(), WriteError> {
562        if let Obj::V(Value::Dict(m)) = o {
563            return self.class_dict(tree, node, m, registry);
564        }
565        let outer = self.has_registry;
566        let kids = tree.list().children(node);
567        for c in kids {
568            visit();
569            if registry && self.kind(tree, *c) == Kind::ManagedReferencesRegistry {
570                if self.has_registry {
571                    self.skip()?;
572                    continue;
573                }
574                self.has_registry = true;
575            }
576            let name = tree.list().name(*c);
577            let mut buf = [0_u8; CLEAN_MAX];
578            let clean = clean_name(name, &mut buf).and_then(|n| buf.get(..n));
579            let attr = match clean {
580                Some(clean) => Self::getattr(o, clean),
581                None => Ok(None),
582            };
583            let item = match attr {
584                Ok(Some(a)) => a,
585                Ok(None) => {
586                    return Err(Self::mismatch(tree, *c, "an object with this attribute"));
587                }
588                Err(()) => {
589                    return Err(Self::mismatch(
590                        tree,
591                        *c,
592                        "a modelled (non-dunder) attribute",
593                    ));
594                }
595            };
596            let repeated = tree.info(*c).is_some_and(|i| i.repeated);
597            let before = self.out.len();
598            self.child(repeated, |w| w.value(tree, *c, item))?;
599            if self.out.len() == before {
600                self.bound()?;
601            }
602        }
603        self.has_registry = outer;
604        Ok(())
605    }
606
607    /// The class branch on a dict (`TypeTreeHelper.py:438-446`): `value[child.m_Name]` for
608    /// each child, found by a [`Lookup`]; a registry child as
609    /// [`Self::class`] takes it.
610    #[inline(never)]
611    fn class_dict(
612        &mut self,
613        tree: &Tree,
614        node: NodeId,
615        m: &'a Map,
616        registry: bool,
617    ) -> Result<(), WriteError> {
618        let outer = self.has_registry;
619        let mut find = Lookup::new(self.parsed, tree, node, m);
620        self.children(tree, node, |w| {
621            for c in tree.list().children(node) {
622                visit();
623                if registry && w.kind(tree, *c) == Kind::ManagedReferencesRegistry {
624                    if w.has_registry {
625                        w.skip()?;
626                        continue;
627                    }
628                    w.has_registry = true;
629                }
630                let v = w
631                    .find(&mut find, tree, *c)?
632                    .ok_or_else(|| WriteError::MissingKey(Self::name(tree, *c)))?;
633                let repeated = tree.info(*c).is_some_and(|i| i.repeated);
634                w.child(repeated, |w| w.value(tree, *c, Obj::V(v)))?;
635            }
636            Ok(())
637        })?;
638        self.has_registry = outer;
639        Ok(())
640    }
641
642    /// `ReferencedObject` (`TypeTreeHelper.py:422-428`), W7: each child's entry found by a
643    /// [`Lookup`]; the data's ref type resolved once a write of the dict,
644    /// which does not change while it is written (claude X, review round 2:
645    /// a node of many data children resolved it for each).
646    #[inline(never)]
647    fn ref_object(&mut self, tree: &Tree, node: NodeId, o: Obj<'a>) -> Result<(), WriteError> {
648        let kids = tree.list().children(node);
649        if kids.is_empty() {
650            return Ok(());
651        }
652        let Obj::V(Value::Dict(m)) = o else {
653            return Err(Self::mismatch(tree, node, "dict"));
654        };
655        let mut find = Lookup::new(self.parsed, tree, node, m);
656        let mut data: Option<Data> = None;
657        self.children(tree, node, |w| {
658            for c in kids {
659                visit();
660                let repeated = tree.info(*c).is_some_and(|i| i.repeated);
661                if w.kind(tree, *c) != Kind::ReferencedObjectData {
662                    let v = w
663                        .find(&mut find, tree, *c)?
664                        .ok_or_else(|| WriteError::MissingKey(Self::name(tree, *c)))?;
665                    w.child(repeated, |w| w.value(tree, *c, Obj::V(v)))?;
666                    continue;
667                }
668                let through = if let Some(d) = &data {
669                    d.clone()
670                } else {
671                    let d = match w.mirror {
672                        None => Data::Through(w.ref_node_py(m)?),
673                        // The reader skipped the data: so does the mirror.
674                        Some(ReadBy::Boost) => w
675                            .ref_node_boost(m)?
676                            .map_or(Data::Skip, |t| Data::Through(Some(t))),
677                        // The pure-Python reader skips it for an empty
678                        // class or a matched ref type with no tree
679                        // (`TypeTreeHelper.py:197-206`).
680                        Some(ReadBy::Python) => w
681                            .ref_node_py(m)?
682                            .map_or(Data::Skip, |t| Data::Through(Some(t))),
683                    };
684                    data.insert(d).clone()
685                };
686                let Data::Through(ref_tree) = through else {
687                    w.skip()?;
688                    continue;
689                };
690                // `value[child.m_Name]`, then `write_value(..., None)` raises.
691                let v = w
692                    .find(&mut find, tree, *c)?
693                    .ok_or_else(|| WriteError::MissingKey(Self::name(tree, *c)))?;
694                let Some(rt) = ref_tree else {
695                    return Err(Self::mismatch(tree, *c, "a ref type with a tree"));
696                };
697                w.child(repeated, |w| w.value(&rt, rt.root(), Obj::V(v)))?;
698            }
699            Ok(())
700        })
701    }
702
703    /// A matched ref type whose tree does not compile.
704    fn tree_error(e: TreeError) -> WriteError {
705        match e {
706            TreeError::Limit(l) => WriteError::Limit(l),
707            TreeError::Charge(c) => WriteError::Charge(c),
708            _ => WriteError::Malformed(RawStr::new(Bytes::from_static(b"ReferencedObjectData"))),
709        }
710    }
711
712    /// The type dict's `class`, `ns` and `asm` (`ref_object["type"]`, then
713    /// `typ["class"]`...; a type that is not a dict has no `class`
714    /// attribute).
715    fn names(&mut self, m: &'a Map) -> Result<(&'a Value, &'a Value, &'a Value), WriteError> {
716        let key = |k: &'static [u8]| RawStr::new(Bytes::from_static(k));
717        let t = match self.field(m, b"type")? {
718            None => return Err(WriteError::MissingKey(key(b"type"))),
719            Some(Value::Dict(t)) => t,
720            Some(_) => {
721                return Err(WriteError::TypeMismatch {
722                    node: key(b"type"),
723                    expected: "a dict or an object with class, ns and asm",
724                });
725            }
726        };
727        let mut get = |k: &'static [u8]| {
728            self.field(t, k)?
729                .ok_or_else(|| WriteError::MissingKey(key(k)))
730        };
731        Ok((get(b"class")?, get(b"ns")?, get(b"asm")?))
732    }
733
734    /// The first ref type whose names equal the three ([`RefIndex`]).
735    fn find_ref(
736        &mut self,
737        (cls, ns, asm): (&Value, &Value, &Value),
738    ) -> Result<Option<Arc<Tree>>, WriteError> {
739        let r = self
740            .refs
741            .find(self.parsed.charge().meter(), &mut self.open, cls, ns, asm)
742            .map_err(|e| match e {
743                FindError::Charge(e) => WriteError::Charge(e),
744                FindError::Work(l) => WriteError::Limit(l),
745            })?
746            .ok_or(WriteError::RefTypeNotFound)?;
747        r.tree(&self.limits).transpose().map_err(Self::tree_error)
748    }
749
750    /// The pure-Python `get_ref_type_node` (`TypeTreeHelper.py:88-109`):
751    /// `None` for an empty class; the writer then fails on it.
752    fn ref_node_py(&mut self, m: &'a Map) -> Result<Option<Arc<Tree>>, WriteError> {
753        let (cls, ns, asm) = self.names(m)?;
754        match self.ref_types {
755            RefTypes::List(l) if !l.is_empty() => {}
756            RefTypes::Absent => return Err(WriteError::NoRefTypesAttribute),
757            RefTypes::NoFile | RefTypes::List(_) => return Err(WriteError::NoRefTypes),
758        }
759        if matches!(cls, Value::Str(s) if s.as_bytes().is_empty()) {
760            return Ok(None);
761        }
762        self.find_ref((cls, ns, asm))
763    }
764
765    /// UnityPyBoost's resolution (R14), for [`WriteRules::MirrorReader`]:
766    /// `None` where the reader skipped the data. A file with no `ref_types`
767    /// attribute is refused as `write_typetree` refuses it
768    /// ([`WriteError::NoRefTypesAttribute`]), where UnityPyBoost's reader
769    /// raises `ValueError` (`TypeTreeHelper.cpp:592-598`).
770    fn ref_node_boost(&mut self, m: &'a Map) -> Result<Option<Arc<Tree>>, WriteError> {
771        match self.ref_types {
772            RefTypes::List(_) => {}
773            RefTypes::Absent => return Err(WriteError::NoRefTypesAttribute),
774            RefTypes::NoFile => return Err(WriteError::NoRefTypes),
775        }
776        let (cls, ns, asm) = self.names(m)?;
777        if py_size_field_is_zero(cls) {
778            return Ok(None);
779        }
780        self.find_ref((cls, ns, asm))
781    }
782}
783
784#[cfg(test)]
785mod tests;
786#[cfg(test)]
787mod work_tests;