rakata_formats/gff/

path.rs

//! Path-addressed reads and edits of a loaded [`GffStruct`].
//!
//! # Why this exists
//!
//! A `Gff` tree could be read and it could be written, with nothing in between.
//! The only public mutation was [`GffStruct::push_field`], which appends, so the
//! only way to change a value was to parse into a typed view, mutate that, and
//! rebuild with `to_gff()`. Rebuilding starts from an empty struct and therefore
//! drops every field the view does not model. That is right for authoring a new
//! file and it is data loss for editing one somebody else wrote.
//!
//! These operations name a field by path and leave the rest of the tree alone.
//!
//! # Replace never appends
//!
//! Appending a second copy of a label would leave the original winning on
//! lookup: the file changes, the behaviour does not, and nothing reports it.
//! [`set`] replaces in place and refuses a label that is not already there;
//! [`insert`] adds one and refuses a label that is.
//!
//! Keeping them apart is deliberate. A single upsert would turn a mistyped
//! label into a silently-created field rather than an error.
//!
//! [`set`]: GffStruct::set
//! [`insert`]: GffStruct::insert
//!
//! # A label carried twice is an error, not a first match
//!
//! A struct really can hold one label several times, and vanilla content does:
//! every `EntryList` and `ReplyList` node in a `.dlg` carries `SoundExists` six
//! times over, and nothing on record says why. Resolving that by position
//! answers a question nobody has established the answer to, so every walk here
//! reports [`AmbiguousLabel`] instead. Editing all of them is a different
//! request and needs a different call.
//!
//! [`AmbiguousLabel`]: GffPathError::AmbiguousLabel
//!
//! # What this does not do
//!
//! No validation. Whether a label belongs on this format, whether a value is in
//! range, whether a required field is missing: all of that is `rakata-lint`'s,
//! and the schemas it needs live above this crate.
//!
//! Struct ids on inserted list elements are the caller's to choose.
//! [`push_element`](GffStruct::push_element) takes a whole [`GffStruct`], which
//! carries its own id, because several lists have the engine skip an element
//! whose id is wrong and which value is right is per-format knowledge. See the
//! GIT and PTH pages in `docs/src/formats/gff/` for the ones that matter.
//!
//! # A list element cannot be inserted at an index, on purpose
//!
//! Appending is the only way to add a list element here. Inserting into the
//! middle would shift every later index, and DLG links address their targets by
//! index, so a mid-list insertion silently breaks every link past the insertion
//! point. Nothing else wants it either: GIT lists are typed by struct id rather
//! than ordered, and inventory order is cosmetic.
//!
//! So the omission is a decision. Adding it later as an obvious convenience
//! would be adding a footgun.
//!
//! A struct's *fields* are the opposite case, which is why
//! [`insert_at_position`] exists beside this. Nothing addresses a field by its
//! position, so putting one back where it was breaks nothing, and the writer
//! emits fields in the order the struct holds them: restoring a removed field
//! on the end rewrites the file from the hole onwards for no reason.
//!
//! [`insert_at_position`]: GffStruct::insert_at_position
//!
//! # Every walker here is private, and that is load-bearing
//!
//! The general shape this could have taken is a `struct_at_mut(path)` handing
//! back a `&mut GffStruct`, and it is the wrong one. A caller holding a mutable
//! struct can reach [`GffStruct::push_field`] and append over a label that is
//! already there, which is the silent-inert-edit this whole module exists to
//! prevent. Every operation is narrow so that the only ways in are ones that
//! cannot produce a duplicate label.

use std::fmt;
use std::str::FromStr;

use thiserror::Error;

use super::label::{GffLabel, GffLabelError};
use super::{GffField, GffStruct, GffValue};
use crate::schema::gff_value_type;

/// One step of a [`GffPath`].
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum GffPathSegment {
    /// Name a field of the struct currently in hand.
    Field(GffLabel),
    /// Take an element of the list currently in hand.
    Index(usize),
}

/// An address into a GFF tree, such as `ClassList[0].Class`.
///
/// Rendering gives the same dot notation `rakata-lint` already prints in
/// `LintDiagnostic.fields`, so a consumer wanting to navigate to a finding
/// rather than display it has one address type to use for both.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct GffPath {
    segments: Vec<GffPathSegment>,
}

impl GffPath {
    /// Creates a path from its segments.
    pub fn new(segments: Vec<GffPathSegment>) -> Self {
        Self { segments }
    }

    /// The steps this path takes, in order.
    pub fn segments(&self) -> &[GffPathSegment] {
        &self.segments
    }

    /// Whether this path names nothing.
    pub fn is_empty(&self) -> bool {
        self.segments.is_empty()
    }

    /// This path with its last step dropped, or `None` when it has none.
    ///
    /// What a list mutation records against: appending to or removing from a
    /// list changes the list, and the index the caller named is not where the
    /// change is once the siblings have shifted.
    pub fn parent(&self) -> Option<Self> {
        let (_, rest) = self.segments.split_last()?;
        Some(Self {
            segments: rest.to_vec(),
        })
    }

    /// Extends this path by one step, which is how a walk builds one.
    pub fn then(&self, segment: GffPathSegment) -> Self {
        let mut segments = self.segments.clone();
        segments.push(segment);
        Self { segments }
    }

    /// Whether `prefix` names this node or one of its ancestors.
    ///
    /// Segment by segment rather than over the rendered text, and that is the
    /// whole reason this is a method. `"ItemList".starts_with("ItemLis")` is
    /// true and `ItemList` is not under `ItemLis`, so a prefix test written on
    /// the strings answers yes for a sibling whose label merely begins the same
    /// way. Comparing segments cannot make that mistake, because a label is
    /// matched whole.
    ///
    /// Reflexive, matching the slice method it is built on: a path starts with
    /// itself. Callers wanting proper descendants exclude equality themselves,
    /// which is what the tree does when deciding whether a collapsed node hides
    /// a row, since a collapsed node has to keep drawing itself.
    ///
    /// Ordering makes this cheap to use over a set. [`GffPath`] sorts by
    /// segments, so every descendant of a path sorts contiguously after it with
    /// nothing able to sort between; a `BTreeMap` of changes answers "anything
    /// under here" with one `range` and this test on the first entry.
    pub fn starts_with(&self, prefix: &Self) -> bool {
        self.segments.starts_with(&prefix.segments)
    }

    /// Renders the path up to and including `upto` segments.
    ///
    /// Used so an error names where the walk stopped rather than the whole
    /// path, which is what tells a caller which step was wrong.
    fn prefix(&self, upto: usize) -> String {
        GffPath::new(self.segments[..upto.min(self.segments.len())].to_vec()).to_string()
    }
}

impl fmt::Display for GffPath {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut first = true;
        for segment in &self.segments {
            match segment {
                GffPathSegment::Field(label) => {
                    if !first {
                        write!(f, ".")?;
                    }
                    write!(f, "{label}")?;
                }
                GffPathSegment::Index(index) => write!(f, "[{index}]")?,
            }
            first = false;
        }
        Ok(())
    }
}

/// A path string that does not describe an address.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum GffPathParseError {
    /// The text between separators was empty.
    #[error("empty path segment in `{path}`")]
    EmptySegment {
        /// The path as supplied.
        path: String,
    },
    /// A `[...]` did not hold a number.
    #[error("`{index}` in `{path}` is not a list index")]
    BadIndex {
        /// The path as supplied.
        path: String,
        /// The text found between the brackets.
        index: String,
    },
    /// A `[` was never closed.
    #[error("unclosed `[` in `{path}`")]
    UnclosedIndex {
        /// The path as supplied.
        path: String,
    },
    /// A segment is not usable as a GFF label.
    #[error("`{segment}` in `{path}` is not a valid label: {source}")]
    BadLabel {
        /// The path as supplied.
        path: String,
        /// The offending segment.
        segment: String,
        /// Why the label was rejected.
        source: GffLabelError,
    },
}

impl FromStr for GffPath {
    type Err = GffPathParseError;

    /// Parses dot notation with bracketed list indices.
    ///
    /// `PropertiesList[0].PropertyName` is three segments: a field, an index,
    /// and a field.
    fn from_str(text: &str) -> Result<Self, Self::Err> {
        let path = || text.to_owned();
        let mut segments = Vec::new();

        for part in text.split('.') {
            let (name, mut rest) = match part.find('[') {
                Some(at) => (&part[..at], &part[at..]),
                None => (part, ""),
            };
            if name.is_empty() {
                return Err(GffPathParseError::EmptySegment { path: path() });
            }
            segments.push(GffPathSegment::Field(GffLabel::new(name).map_err(
                |source| GffPathParseError::BadLabel {
                    path: path(),
                    segment: name.to_owned(),
                    source,
                },
            )?));

            while !rest.is_empty() {
                let end = rest
                    .find(']')
                    .ok_or_else(|| GffPathParseError::UnclosedIndex { path: path() })?;
                let digits = &rest[1..end];
                let index = digits
                    .parse::<usize>()
                    .map_err(|_| GffPathParseError::BadIndex {
                        path: path(),
                        index: digits.to_owned(),
                    })?;
                segments.push(GffPathSegment::Index(index));
                rest = &rest[end + 1..];
            }
        }

        Ok(Self { segments })
    }
}

/// A path that does not resolve, or an edit the tree will not take.
///
/// A `Result` rather than a hit-plus-diagnostics pair. A tier walk can half
/// succeed, answering from a lower tier while a higher one was unreadable, and
/// both halves matter. Addressing a path cannot: it arrives or it does not, for
/// one reason.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum GffPathError {
    /// A path with no segments names nothing to act on.
    #[error("an empty path names no field")]
    EmptyPath,
    /// A path started by indexing, with no list yet in hand.
    #[error("`{path}` starts with a list index, but the root is a struct")]
    IndexAtRoot {
        /// The path as supplied.
        path: String,
    },
    /// The struct has no field under that label.
    #[error("no field `{label}` at `{at}`")]
    NoSuchField {
        /// Where the walk had reached.
        at: String,
        /// The label looked for.
        label: String,
    },
    /// The struct carries that label more than once.
    ///
    /// Which copy the caller meant is not recoverable from the path, and the
    /// copies are not known to agree on anything but their value today.
    #[error("`{at}` carries `{label}` {count} times, so the path names no single field")]
    AmbiguousLabel {
        /// Where the walk had reached.
        at: String,
        /// The label looked for.
        label: String,
        /// How many fields carry it.
        count: usize,
    },
    /// The list is shorter than the index.
    #[error("`{at}` has {len} element(s), so index {index} is out of range")]
    IndexOutOfRange {
        /// Where the walk had reached.
        at: String,
        /// The index asked for.
        index: usize,
        /// How many elements the list holds.
        len: usize,
    },
    /// A field was indexed and is not a list.
    #[error("`{at}` is {actual}, which cannot be indexed")]
    NotAList {
        /// Where the walk had reached.
        at: String,
        /// The type actually found.
        actual: &'static str,
    },
    /// A field was descended into and is not a struct.
    #[error("`{at}` is {actual}, which has no fields")]
    NotAStruct {
        /// Where the walk had reached.
        at: String,
        /// The type actually found.
        actual: &'static str,
    },
    /// The replacement is a different type from what the field holds.
    ///
    /// The existing field's type is the only oracle available here. The
    /// per-format schemas that could answer "what *should* this label be" live
    /// in `rakata-generics`, above this crate, and asking that question is
    /// validation, which belongs to lint.
    #[error("`{at}` holds {existing} and the replacement is {replacement}; use `insert` after `remove` to change a field's type deliberately")]
    TypeMismatch {
        /// The field being replaced.
        at: String,
        /// The type currently stored.
        existing: &'static str,
        /// The type offered.
        replacement: &'static str,
    },
    /// `insert` was given a label the struct already carries.
    #[error("`{at}` already exists; `set` replaces a field and `insert` adds one")]
    AlreadyExists {
        /// The field that is already present.
        at: String,
    },
    /// A field operation ended at a list index, or the reverse.
    #[error("`{operation}` needs a path ending in {expected}, and `{at}` does not")]
    WrongSegmentKind {
        /// The path as supplied.
        at: String,
        /// The operation that could not use it.
        operation: &'static str,
        /// The kind of last segment the operation needs.
        expected: &'static str,
    },
}

/// Where a partial walk of a path has arrived.
enum Cursor<'a> {
    Struct(&'a mut GffStruct),
    Value(&'a mut GffValue),
}

impl GffStruct {
    /// Reads the value a path names.
    ///
    /// The read counterpart to [`Self::set`], and the way to do a
    /// read-modify-write over a large file without building a typed view per
    /// field.
    ///
    /// # Errors
    ///
    /// Every operation here walks the path the same way and can fail the same
    /// way partway along it: [`GffPathError::EmptyPath`] for a path with no
    /// segments, [`GffPathError::IndexAtRoot`] for one starting with an index,
    /// [`GffPathError::NotAStruct`] or [`GffPathError::NotAList`] when a
    /// segment's value is not the kind the next segment needs,
    /// [`GffPathError::IndexOutOfRange`] when a list is shorter than the index,
    /// [`GffPathError::NoSuchField`] when a struct does not carry the label,
    /// and [`GffPathError::AmbiguousLabel`] when it carries it more than once.
    /// That last one is a refusal rather than a first match; see the module
    /// docs.
    ///
    /// On top of those, [`GffPathError::WrongSegmentKind`] when `path` ends in
    /// an index. That lands on a bare [`GffStruct`], which is not a
    /// [`GffValue`]; [`Self::struct_id`] is the call that takes such a path.
    pub fn get(&self, path: &GffPath) -> Result<&GffValue, GffPathError> {
        let segments = path.segments();
        if segments.is_empty() {
            return Err(GffPathError::EmptyPath);
        }

        let mut current: Option<&GffValue> = None;
        let mut structure: &GffStruct = self;

        for (depth, segment) in segments.iter().enumerate() {
            match segment {
                GffPathSegment::Field(label) => {
                    if let Some(value) = current {
                        structure = as_struct(value, path, depth)?;
                    }
                    let at = sole_position(&structure.fields, label, path, depth)?;
                    current = Some(&structure.fields[at].value);
                }
                GffPathSegment::Index(index) => {
                    let Some(value) = current else {
                        return Err(GffPathError::IndexAtRoot {
                            path: path.to_string(),
                        });
                    };
                    let list = as_list(value, path, depth)?;
                    structure = list
                        .get(*index)
                        .ok_or_else(|| GffPathError::IndexOutOfRange {
                            at: path.prefix(depth),
                            index: *index,
                            len: list.len(),
                        })?;
                    current = None;
                }
            }
        }

        // A path ending in an index names a struct, which is not a field value.
        current.ok_or_else(|| GffPathError::WrongSegmentKind {
            at: path.to_string(),
            operation: "get",
            expected: "a field label",
        })
    }

    /// Replaces the value a path names, returning what was there.
    ///
    /// Refuses a label the struct does not already carry, and refuses a
    /// replacement of a different type from the one stored. Both refusals exist
    /// because the alternative is a file that looks edited and is not: an
    /// appended duplicate loses to the original on lookup, and a widened
    /// integer shifts every byte after it.
    ///
    /// To change a field's type on purpose, [`remove`](Self::remove) it and
    /// [`insert`](Self::insert) it back.
    ///
    /// # Errors
    ///
    /// The walk failures [`Self::get`] lists, plus
    /// [`GffPathError::TypeMismatch`] when `value` is not the type the field
    /// already holds. [`GffPathError::NoSuchField`] is the ordinary way a
    /// mistyped label arrives here rather than becoming a new field.
    pub fn set(&mut self, path: &GffPath, value: GffValue) -> Result<GffValue, GffPathError> {
        let depth = path.segments().len() - 1;
        let (structure, label) = self.field_parent_mut(path, "set")?;
        let at = sole_position(&structure.fields, &label, path, depth)?;
        let existing = &mut structure.fields[at];

        let stored = gff_value_type(&existing.value);
        let offered = gff_value_type(&value);
        if stored != offered {
            return Err(GffPathError::TypeMismatch {
                at: path.to_string(),
                existing: stored.name(),
                replacement: offered.name(),
            });
        }

        Ok(std::mem::replace(&mut existing.value, value))
    }

    /// Adds a field a path names, which must not already be there.
    ///
    /// The value's own type decides the field's type, there being nothing to
    /// preserve.
    ///
    /// On disk a struct holding one field stores that field's index directly
    /// and a struct holding more stores an offset into the shared index array,
    /// so adding a second field to a one-field struct changes the struct's
    /// encoded shape. Nothing here has to arrange that: the writer picks the
    /// shape from the field count when it encodes.
    ///
    /// # Errors
    ///
    /// The walk failures [`Self::get`] lists for the path's parent, plus
    /// [`GffPathError::AlreadyExists`] when the struct already carries that
    /// label. Adding a second copy is refused rather than done, because the
    /// original would go on winning every lookup.
    pub fn insert(&mut self, path: &GffPath, value: GffValue) -> Result<(), GffPathError> {
        self.insert_at_position(path, value, usize::MAX)
    }

    /// Adds a field among its siblings rather than after them.
    ///
    /// `position` is clamped to the end, so `usize::MAX` appends and a position
    /// from a struct that has since lost fields still lands somewhere valid.
    ///
    /// This exists because putting a field back is not the same operation as
    /// adding one. A GFF struct stores its fields in order and the writer emits
    /// them in that order, so restoring a removed field by appending produces a
    /// file that differs from the original everywhere after the hole, which is
    /// what an undo of a deletion did before.
    ///
    /// # Errors
    ///
    /// The same as [`Self::insert`]. `position` is clamped rather than
    /// checked, so it is never the reason this fails.
    pub fn insert_at_position(
        &mut self,
        path: &GffPath,
        value: GffValue,
        position: usize,
    ) -> Result<(), GffPathError> {
        let (structure, label) = self.field_parent_mut(path, "insert")?;
        if structure.fields.iter().any(|field| field.label == label) {
            return Err(GffPathError::AlreadyExists {
                at: path.to_string(),
            });
        }
        let position = position.min(structure.fields.len());
        structure.fields.insert(position, GffField { label, value });
        Ok(())
    }

    /// Where the field `path` names sits among its siblings.
    ///
    /// `None` when the parent does not resolve, the path does not end in a
    /// label, or no such field is there.
    pub fn position(&self, path: &GffPath) -> Option<usize> {
        let segments = path.segments();
        let GffPathSegment::Field(label) = segments.last()? else {
            return None;
        };
        let structure = if segments.len() == 1 {
            // A one-segment path names a field of this struct itself, and
            // there is no parent address to resolve.
            self
        } else {
            let parent = GffPath::new(segments[..segments.len() - 1].to_vec());
            match self.get(&parent) {
                Ok(GffValue::Struct(nested)) => nested.as_ref(),
                _ => return None,
            }
        };
        structure
            .fields
            .iter()
            .position(|field| field.label == *label)
    }

    /// Removes what a path names, returning it.
    ///
    /// A path ending in a label removes that field. A path ending in an index
    /// removes that list element and returns it wrapped in a
    /// [`GffValue::Struct`].
    ///
    /// Removing an element does not renumber its siblings. No list in the
    /// engine reads an element's struct id as a position, so the ids that
    /// remain still mean what they meant.
    ///
    /// # Errors
    ///
    /// The walk failures [`Self::get`] lists. Nothing is removed when any of
    /// them fires, so a failed remove leaves the tree as it was.
    pub fn remove(&mut self, path: &GffPath) -> Result<GffValue, GffPathError> {
        let segments = path.segments();
        let Some(last) = segments.last() else {
            return Err(GffPathError::EmptyPath);
        };

        match last {
            GffPathSegment::Field(label) => {
                let depth = segments.len() - 1;
                let structure = self.walk_to_struct(path, depth)?;
                let at = sole_position(&structure.fields, label, path, depth)?;
                Ok(structure.fields.remove(at).value)
            }
            GffPathSegment::Index(index) => {
                let list = self.walk_to_list(path, segments.len() - 1)?;
                if *index >= list.len() {
                    return Err(GffPathError::IndexOutOfRange {
                        at: path.prefix(segments.len() - 1),
                        index: *index,
                        len: list.len(),
                    });
                }
                Ok(GffValue::Struct(Box::new(list.remove(*index))))
            }
        }
    }

    /// Appends `element` to the list a path names, returning its index.
    ///
    /// The element carries its own `struct_id`, and choosing it is the caller's
    /// job. Several lists have the engine compare that id against a per-list
    /// constant and silently skip an element that does not match, and which
    /// constant belongs to which list is per-format knowledge that lives above
    /// this crate.
    ///
    /// # Errors
    ///
    /// The walk failures [`Self::get`] lists, with
    /// [`GffPathError::NotAList`] the one that means `path` named a field
    /// that is not a list. The element's `struct_id` is not checked against
    /// anything, since nothing here knows which list wants which id.
    pub fn push_element(
        &mut self,
        path: &GffPath,
        element: GffStruct,
    ) -> Result<usize, GffPathError> {
        let list = self.walk_to_list(path, path.segments().len())?;
        list.push(element);
        Ok(list.len() - 1)
    }

    /// Reads the struct id of the list element a path names.
    ///
    /// An element's id is not a field and not a [`GffValue`], so [`get`] cannot
    /// reach it: a path ending in an index lands on a bare [`GffStruct`]. A
    /// nested struct *field* needs nothing special, since `get` hands back the
    /// [`GffValue::Struct`] and the id is on the struct inside it.
    ///
    /// Some formats carry meaning there. A UTC's equipment slot **is** its
    /// `Equip_ItemList` element's struct id and appears in no field, so reading
    /// which slot an item occupies is exactly this call.
    ///
    /// [`get`]: Self::get
    ///
    /// # Errors
    ///
    /// The walk failures [`Self::get`] lists, plus
    /// [`GffPathError::WrongSegmentKind`] when `path` ends in a label rather
    /// than an index. That is the mirror of `get`'s refusal: this call takes
    /// exactly the paths that one will not.
    pub fn struct_id(&self, path: &GffPath) -> Result<i32, GffPathError> {
        let (list, index) = self.element_parent(path)?;
        list.get(index)
            .map(|element| element.struct_id)
            .ok_or_else(|| GffPathError::IndexOutOfRange {
                at: path.prefix(path.segments().len() - 1),
                index,
                len: list.len(),
            })
    }

    /// Sets the struct id of the list element a path names, returning the old.
    ///
    /// The counterpart to [`struct_id`](Self::struct_id), and the way to move a
    /// UTC equipment item between slots: the slot is the id, so re-equipping is
    /// a change to an existing element rather than a removal and an append.
    ///
    /// Which ids a list accepts is the caller's to know. Several lists have the
    /// engine compare the id against a per-list constant and silently skip an
    /// element that does not match, and that mapping is per-format knowledge
    /// living above this crate.
    ///
    /// # Errors
    ///
    /// The same as [`Self::struct_id`]. `struct_id` itself is not validated,
    /// so an id no list accepts is written without complaint.
    pub fn set_struct_id(&mut self, path: &GffPath, struct_id: i32) -> Result<i32, GffPathError> {
        let index = self.element_index(path)?;
        let at = path.prefix(path.segments().len() - 1);
        let list = self.walk_to_list(path, path.segments().len() - 1)?;
        let len = list.len();
        let element =
            list.get_mut(index)
                .ok_or(GffPathError::IndexOutOfRange { at, index, len })?;
        Ok(std::mem::replace(&mut element.struct_id, struct_id))
    }

    /// The index a struct-id path ends with, refusing one that ends elsewhere.
    fn element_index(&self, path: &GffPath) -> Result<usize, GffPathError> {
        let segments = path.segments();
        let Some(last) = segments.last() else {
            return Err(GffPathError::EmptyPath);
        };
        match last {
            GffPathSegment::Index(index) => Ok(*index),
            GffPathSegment::Field(_) => Err(GffPathError::WrongSegmentKind {
                at: path.to_string(),
                operation: "struct_id",
                expected: "a list index",
            }),
        }
    }

    /// Resolves a struct-id path to the list holding the element, and its index.
    fn element_parent(&self, path: &GffPath) -> Result<(&Vec<GffStruct>, usize), GffPathError> {
        let index = self.element_index(path)?;
        let segments = path.segments();

        // A path that is only an index has no list in front of it, which the
        // parent walk below would report as an empty path rather than as the
        // root not being a list.
        if segments.len() == 1 {
            return Err(GffPathError::IndexAtRoot {
                path: path.to_string(),
            });
        }

        let parent = GffPath::new(segments[..segments.len() - 1].to_vec());
        match self.get(&parent)? {
            GffValue::List(list) => Ok((list, index)),
            other => Err(GffPathError::NotAList {
                at: parent.to_string(),
                actual: gff_value_type(other).name(),
            }),
        }
    }

    /// Splits a path into the struct holding its last field and that label.
    fn field_parent_mut(
        &mut self,
        path: &GffPath,
        operation: &'static str,
    ) -> Result<(&mut GffStruct, GffLabel), GffPathError> {
        let segments = path.segments();
        let Some(last) = segments.last() else {
            return Err(GffPathError::EmptyPath);
        };
        let GffPathSegment::Field(label) = last else {
            return Err(GffPathError::WrongSegmentKind {
                at: path.to_string(),
                operation,
                expected: "a field label",
            });
        };
        let label = *label;
        Ok((self.walk_to_struct(path, segments.len() - 1)?, label))
    }

    /// Walks the first `depth` segments and requires a struct at the end.
    fn walk_to_struct(
        &mut self,
        path: &GffPath,
        depth: usize,
    ) -> Result<&mut GffStruct, GffPathError> {
        match self.descend_to(path, depth)? {
            Cursor::Struct(structure) => Ok(structure),
            Cursor::Value(value) => {
                let actual = gff_value_type(value).name();
                match value {
                    GffValue::Struct(inner) => Ok(inner.as_mut()),
                    _ => Err(GffPathError::NotAStruct {
                        at: path.prefix(depth),
                        actual,
                    }),
                }
            }
        }
    }

    /// Walks the first `depth` segments and requires a list at the end.
    fn walk_to_list(
        &mut self,
        path: &GffPath,
        depth: usize,
    ) -> Result<&mut Vec<GffStruct>, GffPathError> {
        match self.descend_to(path, depth)? {
            Cursor::Struct(_) => Err(GffPathError::NotAList {
                at: path.prefix(depth),
                actual: "a struct",
            }),
            Cursor::Value(value) => {
                let actual = gff_value_type(value).name();
                match value {
                    GffValue::List(list) => Ok(list),
                    _ => Err(GffPathError::NotAList {
                        at: path.prefix(depth),
                        actual,
                    }),
                }
            }
        }
    }

    /// Descends the first `depth` segments of `path`.
    ///
    /// Not to be confused with [`walk`](Self::walk), which is the public
    /// traversal of a whole tree. This positions a cursor for one edit.
    fn descend_to(&mut self, path: &GffPath, depth: usize) -> Result<Cursor<'_>, GffPathError> {
        let mut cursor = Cursor::Struct(self);

        for (at, segment) in path.segments().iter().take(depth).enumerate() {
            cursor = match segment {
                GffPathSegment::Field(label) => {
                    let structure = match cursor {
                        Cursor::Struct(structure) => structure,
                        Cursor::Value(value) => {
                            let actual = gff_value_type(value).name();
                            match value {
                                GffValue::Struct(inner) => inner.as_mut(),
                                _ => {
                                    return Err(GffPathError::NotAStruct {
                                        at: path.prefix(at),
                                        actual,
                                    })
                                }
                            }
                        }
                    };
                    let found = sole_position(&structure.fields, label, path, at)?;
                    Cursor::Value(&mut structure.fields[found].value)
                }
                GffPathSegment::Index(index) => {
                    let Cursor::Value(value) = cursor else {
                        return Err(GffPathError::IndexAtRoot {
                            path: path.to_string(),
                        });
                    };
                    let actual = gff_value_type(value).name();
                    let GffValue::List(list) = value else {
                        return Err(GffPathError::NotAList {
                            at: path.prefix(at),
                            actual,
                        });
                    };
                    let len = list.len();
                    Cursor::Struct(list.get_mut(*index).ok_or(GffPathError::IndexOutOfRange {
                        at: path.prefix(at),
                        index: *index,
                        len,
                    })?)
                }
            };
        }

        Ok(cursor)
    }
}

/// The one position `label` occupies, refusing both zero copies and several.
///
/// Every field lookup in this module goes through here, so an ambiguous label
/// fails wherever it appears in a path rather than only in its last segment.
fn sole_position(
    fields: &[GffField],
    label: &GffLabel,
    path: &GffPath,
    depth: usize,
) -> Result<usize, GffPathError> {
    let mut carried = fields
        .iter()
        .enumerate()
        .filter(|(_, field)| field.label == *label)
        .map(|(index, _)| index);

    let first = carried.next().ok_or_else(|| GffPathError::NoSuchField {
        at: path.prefix(depth),
        label: label.to_string(),
    })?;

    let count = 1 + carried.count();
    if count > 1 {
        return Err(GffPathError::AmbiguousLabel {
            at: path.prefix(depth),
            label: label.to_string(),
            count,
        });
    }
    Ok(first)
}

/// Borrows a value as the struct it must be to be descended into.
fn as_struct<'a>(
    value: &'a GffValue,
    path: &GffPath,
    depth: usize,
) -> Result<&'a GffStruct, GffPathError> {
    match value {
        GffValue::Struct(inner) => Ok(inner.as_ref()),
        other => Err(GffPathError::NotAStruct {
            at: path.prefix(depth),
            actual: gff_value_type(other).name(),
        }),
    }
}

/// Borrows a value as the list it must be to be indexed.
fn as_list<'a>(
    value: &'a GffValue,
    path: &GffPath,
    depth: usize,
) -> Result<&'a Vec<GffStruct>, GffPathError> {
    match value {
        GffValue::List(list) => Ok(list),
        other => Err(GffPathError::NotAList {
            at: path.prefix(depth),
            actual: gff_value_type(other).name(),
        }),
    }
}