rakata_formats/schema/

route.rs

//! One address for a field of a view, from the view's root.
//!
//! # What wanted this
//!
//! Four things need to name the same place and none of them could. A tree
//! showing a raw GFF needs "reveal this node" from a typed panel. A panel
//! showing a creature's hit points needs somewhere to write back to, because
//! a typed view hands over a value and not an address. A change-review row
//! needs a key that two runs agree on. A lint finding needs to anchor to the
//! field it is about.
//!
//! [`GffPath`] already addresses a node in a tree, and a schema already
//! describes what a view holds. What was missing is the join: the route from a
//! view's root to one of its fields, which is a property of the schema rather
//! than of any one file.
//!
//! # A route is not a path
//!
//! A [`GffPath`] names one node in one file: `Creature List[3].HitPoints`. A
//! [`FieldRoute`] names the same field in every file: `Creature List[].HitPoints`.
//! The bracket is empty because which element is a fact about the file, and
//! the route is a fact about the format.
//!
//! So the two are used at different moments. A lint rule anchors on the route,
//! because the rule is about the field wherever it occurs. A diff row and a
//! write-back use [`FieldRoute::at`] with the indices in hand, which produces
//! a path and from there [`GffDocument::get`](crate::GffDocument::get) and
//! [`set`](crate::GffDocument::set) take over.
//!
//! # Resolution is what makes an anchor real
//!
//! A route is a claim that a view has a field there, and
//! [`FieldRoute::field_in`] checks it against the schema. Without that a typo
//! makes an anchor that names nothing, points at no node, and reports no
//! error: the failure [`GffLabel`] exists to stop one layer down, at the layer
//! above it. A consumer holding a resolved route holds the field's whole
//! entry, which is how a panel knows what it is allowed to write.
//!
//! # Two kinds of ambiguity, and they are unrelated
//!
//! **Schema-side**: one location, two declarations. Both arms of a split can
//! declare a label, as `List[].TemplateResRef` is declared by the templated
//! arm and by the saved one with different write rules.
//! [`FieldRoute::entries_in`] hands back both and
//! [`FieldRoute::field_in`] narrows to one. This is a fact about the
//! declarations.
//!
//! **File-side**: one label, two fields in an actual struct. Every `.dlg`
//! node carries `SoundExists` six times and nothing on record says why, so
//! `GffStruct::set` refuses the path outright. This is a fact about one file.
//!
//! Neither implies the other. A route resolving to two entries says nothing
//! about whether `set` will refuse the path it produces, and a struct
//! carrying a label twice says nothing about how many entries declare it. The
//! two are checked in different places against different things, and folding
//! them together would make each answer a question it cannot see.
//!
//! # This layer knows about schemas and [`GffPath`] does not
//!
//! Deliberately, and the split is the same one `set` already draws.
//! `GffStruct::set` refuses a type change and an ambiguous label and asks no
//! schema, so it edits a file nobody has modelled. Resolution belongs here
//! instead, where a caller opts into it by naming a view.
//!
//! The rule, so it survives a tidy-up: **schema-free addressing below,
//! schema-aware routing above.** Anything needing a schema to resolve cannot
//! live beside `set`, which is why this is not in `gff`.

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

use thiserror::Error;

use super::{Field, HasSchema, Shape};
use crate::gff::{GffLabel, GffLabelError, GffPath, GffPathSegment};

/// One step of a [`FieldRoute`].
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum RouteStep {
    /// Descend into the field carrying this label.
    Field(GffLabel),
    /// Take an element of the list in hand.
    ///
    /// Which element is not part of the route. A caller supplies one index per
    /// `Element` when it turns the route into a path.
    Element,
}

/// Where a field sits, from the root of the view that declares it.
///
/// Ordered and hashable, so a set of findings or changed locations can be
/// keyed on one without a string in the middle.
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Default)]
pub struct FieldRoute {
    steps: Vec<RouteStep>,
}

/// Why a route could not be used.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum RouteError {
    /// The route wants a different number of indices than it was given.
    #[error("`{route}` takes {wanted} list index/indices, and {given} were given")]
    IndexCount {
        /// The route.
        route: String,
        /// How many `Element` steps it has.
        wanted: usize,
        /// How many indices arrived.
        given: usize,
    },
    /// The schema has no such field at that point in the route.
    #[error("`{route}` names `{label}` at `{at}`, which the schema does not declare")]
    NoSuchField {
        /// The route.
        route: String,
        /// The label that was not found.
        label: String,
        /// How far the walk got.
        at: String,
    },
    /// The route indexes something that is not a list.
    #[error("`{route}` indexes `{at}`, which is not a list")]
    NotAList {
        /// The route.
        route: String,
        /// How far the walk got.
        at: String,
    },
    /// The route descends into something with no fields under it.
    #[error("`{route}` descends past `{at}`, which holds a single value")]
    NotAStruct {
        /// The route.
        route: String,
        /// How far the walk got.
        at: String,
    },
    /// The route ends without naming a field.
    ///
    /// An empty route, or one ending at a list element rather than at
    /// something the element holds.
    #[error("`{route}` names no field")]
    NamesNoField {
        /// The route.
        route: String,
    },
    /// The label is declared more than once at that point, so no single entry
    /// describes it.
    ///
    /// Not a defect on its own. Both arms of a split may declare a label with
    /// different write rules, and which applies depends on the selector's
    /// value in one file. The address is the same either way, so a caller that
    /// wants the location rather than the entry uses
    /// [`FieldRoute::entries_in`] and gets both.
    #[error("`{route}` names `{label}` at `{at}`, which carries {count} declarations")]
    AmbiguousArm {
        /// How many entries declare it.
        count: usize,
        /// The route.
        route: String,
        /// The label declared twice.
        label: String,
        /// How far the walk got.
        at: String,
    },
}

impl FieldRoute {
    /// Builds a route from its steps.
    pub fn new(steps: Vec<RouteStep>) -> Self {
        Self { steps }
    }

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

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

    /// How many list indices [`Self::at`] wants.
    pub fn holes(&self) -> usize {
        self.steps
            .iter()
            .filter(|step| matches!(step, RouteStep::Element))
            .count()
    }

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

    /// Turns this route into an address in one file.
    ///
    /// `indices` supplies one element index per [`RouteStep::Element`], in the
    /// order they appear. A route through no list takes an empty slice.
    ///
    /// # Errors
    ///
    /// [`RouteError::IndexCount`] when the count does not match. Taking a
    /// slice rather than one index is what lets a route through two nested
    /// lists work, and mismatching the count is the mistake that makes.
    pub fn at(&self, indices: &[usize]) -> Result<GffPath, RouteError> {
        let wanted = self.holes();
        if wanted != indices.len() {
            return Err(RouteError::IndexCount {
                route: self.to_string(),
                wanted,
                given: indices.len(),
            });
        }
        let mut supplied = indices.iter();
        let segments = self
            .steps
            .iter()
            .map(|step| match step {
                RouteStep::Field(label) => GffPathSegment::Field(*label),
                RouteStep::Element => GffPathSegment::Index(
                    *supplied
                        .next()
                        .expect("the count was checked against `holes` above"),
                ),
            })
            .collect();
        Ok(GffPath::new(segments))
    }

    /// The field this route names in `T`'s schema.
    ///
    /// What turns a route from a claim into an anchor. A route naming a label
    /// no view declares is a typo that would otherwise point at nothing and
    /// say nothing, and the field it hands back carries the entry a caller
    /// needs anyway: what the field holds, whether the engine reads it, and
    /// what its absence means.
    ///
    /// # Errors
    ///
    /// [`RouteError`] naming how far the walk got, so a long route says which
    /// step was wrong rather than that the whole thing was.
    pub fn field_in<T: HasSchema>(&self) -> Result<&'static Field, RouteError> {
        let entries = self.entries_in::<T>()?;
        match entries.as_slice() {
            [only] => Ok(only),
            _ => Err(RouteError::AmbiguousArm {
                route: self.to_string(),
                label: match self.steps.last() {
                    Some(RouteStep::Field(label)) => label.to_string(),
                    _ => self.to_string(),
                },
                at: self.to_string(),
                count: entries.len(),
            }),
        }
    }

    /// Every entry declared for the field this route names.
    ///
    /// One, ordinarily. Two when the route ends inside a split and both arms
    /// declare the label: `List[].TemplateResRef` is declared by the templated
    /// arm and by the saved one, with different write rules, and which applies
    /// depends on the selector's value in a given file. The address is the
    /// same either way, so a tree, a diff row and a write-back can use the
    /// route while only a consumer wanting the entry has to choose.
    ///
    /// # Errors
    ///
    /// [`RouteError`] naming how far the walk got.
    pub fn entries_in<T: HasSchema>(&self) -> Result<Vec<&'static Field>, RouteError> {
        self.field_under(T::parts())
    }

    /// The field this route names under an explicit set of schema parts.
    ///
    /// Parts rather than one slice throughout, because that is how a schema
    /// holds a type that flattens a shared block: the block stays one
    /// declaration and the container points at it.
    ///
    /// A list's elements are looked up across the element schema and both
    /// arms of a [`Split`](super::Split) together. Which arm a file takes
    /// depends on a sibling's value, which a route does not carry, so a label
    /// declared by one arm resolves and one declared by both is refused.
    ///
    /// # Errors
    ///
    /// [`RouteError::NoSuchField`] when `parts` declares no such label at that
    /// point, [`RouteError::NotAList`] when the route indexes something that
    /// is not one, [`RouteError::NotAStruct`] when it descends into something
    /// with no fields under it, and [`RouteError::NamesNoField`] when the
    /// route ends at a list element rather than at something the element
    /// holds. An empty route is that last one.
    ///
    /// [`RouteError::AmbiguousArm`] when both arms of a [`Split`](super::Split)
    /// declare the label. Which arm a file takes turns on a sibling's value,
    /// which a route does not carry, so this is refused rather than guessed.
    ///
    /// [`RouteError::IndexCount`] when the route's index count does not match
    /// what its steps need. That is a malformed route rather than a schema
    /// that disagrees with it.
    pub fn field_under(
        &self,
        parts: &[&'static [Field]],
    ) -> Result<Vec<&'static Field>, RouteError> {
        // Two states, alternating. Either the walk is standing on a set of
        // parts with a label to find, or it is holding the entries it just
        // named and the next step says what to do with them.
        let mut here: Vec<&'static [Field]> = parts.to_vec();
        let mut found: Option<Vec<&'static Field>> = None;

        for (depth, step) in self.steps.iter().enumerate() {
            match step {
                RouteStep::Field(label) => {
                    if let Some(previous) = found.take() {
                        let Shape::Struct { fields } = self.descend(&previous, depth)?.shape else {
                            // A list and a scalar both need something before a
                            // label can be named under them: an index, or
                            // nothing at all.
                            return Err(RouteError::NotAStruct {
                                route: self.to_string(),
                                at: self.upto(depth),
                            });
                        };
                        here = fields.to_vec();
                    }
                    found = Some(self.look_up(&here, label, depth)?);
                }
                RouteStep::Element => {
                    let entries = found.take().ok_or_else(|| RouteError::NotAList {
                        route: self.to_string(),
                        at: self.upto(depth),
                    })?;
                    let Shape::List { element, split, .. } = self.descend(&entries, depth)?.shape
                    else {
                        return Err(RouteError::NotAList {
                            route: self.to_string(),
                            at: self.upto(depth),
                        });
                    };
                    // Both arms are in scope at once. Which one a file takes is
                    // decided by a sibling's value, and a route addresses the
                    // field in every file rather than in one.
                    here = element.to_vec();
                    if let Some(split) = split {
                        here.extend_from_slice(split.when_clear);
                        here.extend_from_slice(split.when_set);
                    }
                }
            }
        }

        found.ok_or_else(|| RouteError::NamesNoField {
            route: self.to_string(),
        })
    }

    /// The entry a walk descends through, when the candidates agree on where
    /// they lead.
    ///
    /// Both arms of a split can declare the same container: a trigger's
    /// `Geometry` is declared by the templated arm and the saved one, with the
    /// same element schema under it, so continuing through either reaches the
    /// same place and the route is not ambiguous at all. What cannot be
    /// descended is a label whose entries name different shapes, because then
    /// picking one guesses which file the route is about.
    fn descend(&self, hits: &[&'static Field], depth: usize) -> Result<&'static Field, RouteError> {
        match hits {
            [only] => Ok(only),
            [first, rest @ ..] if rest.iter().all(|other| other.shape == first.shape) => Ok(first),
            _ => Err(RouteError::AmbiguousArm {
                route: self.to_string(),
                label: hits
                    .first()
                    .map_or_else(String::new, |f| f.label.to_string()),
                at: self.upto(depth),
                count: hits.len(),
            }),
        }
    }

    /// Every field carrying `label` across `parts`, which for a list's
    /// elements includes both arms of its split.
    fn look_up(
        &self,
        parts: &[&'static [Field]],
        label: &GffLabel,
        depth: usize,
    ) -> Result<Vec<&'static Field>, RouteError> {
        let hits: Vec<&'static Field> = parts
            .iter()
            .flat_map(|part| part.iter())
            .filter(|field| field.label == *label)
            .collect();
        if hits.is_empty() {
            return Err(RouteError::NoSuchField {
                route: self.to_string(),
                label: label.to_string(),
                at: self.upto(depth),
            });
        }
        Ok(hits)
    }

    /// The route rendered up to `upto` steps, so an error says where it broke.
    fn upto(&self, upto: usize) -> String {
        FieldRoute::new(self.steps[..upto.min(self.steps.len())].to_vec()).to_string()
    }
}

/// Every route a view declares, with the field each one names.
///
/// The other direction from [`FieldRoute::field_in`]: that one checks a route
/// somebody wrote, this one produces the set. A tree wanting to label its
/// nodes with what the schema says about them, or a lint pass wanting to visit
/// every modelled field, reads this rather than growing its own walk.
///
/// Depth-first in declaration order, so two runs agree and a diff between two
/// views lines up.
pub fn routes_in<T: HasSchema>() -> Vec<(FieldRoute, &'static Field)> {
    routes_under(T::parts())
}

/// Every route under an explicit set of schema parts.
///
/// A schema that reached itself would enumerate forever, so a part already on
/// the current path is not descended into again. Nothing in the fourteen views
/// does that today; the guard is here because a walk that hangs reports
/// nothing at all, which is the failure that looks like no failure.
pub fn routes_under(parts: &[&'static [Field]]) -> Vec<(FieldRoute, &'static Field)> {
    let mut out = Vec::new();
    let mut seen = Vec::new();
    walk(parts, &FieldRoute::default(), &mut seen, &mut out);
    out
}

fn walk(
    parts: &[&'static [Field]],
    prefix: &FieldRoute,
    seen: &mut Vec<*const Field>,
    out: &mut Vec<(FieldRoute, &'static Field)>,
) {
    for part in parts {
        let identity = part.as_ptr();
        if seen.contains(&identity) {
            continue;
        }
        seen.push(identity);
        for field in *part {
            let route = prefix.then(RouteStep::Field(field.label));
            out.push((route.clone(), field));
            match field.shape {
                Shape::Scalar(_) => {}
                Shape::Struct { fields } => walk(fields, &route, seen, out),
                Shape::List { element, split, .. } => {
                    let inside = route.then(RouteStep::Element);
                    walk(element, &inside, seen, out);
                    if let Some(split) = split {
                        walk(split.when_clear, &inside, seen, out);
                        walk(split.when_set, &inside, seen, out);
                    }
                }
            }
        }
        seen.pop();
    }
}

impl From<&GffPath> for FieldRoute {
    /// The route a path in one file takes through every file.
    ///
    /// The inverse of [`FieldRoute::at`], and lossy in the direction it has to
    /// be: `Creature List[3].HitPoints` becomes `Creature List[].HitPoints`,
    /// because which element was in hand is a fact about the file and a route
    /// carries only facts about the format.
    ///
    /// Total, and there is nothing here that could fail. Every segment maps to
    /// exactly one step, so a path that addresses nothing at all still projects
    /// to the route it would have taken. Whether the schema declares anything
    /// there is the separate question [`FieldRoute::field_in`] answers, and
    /// keeping the two apart is what lets a caller ask about a node the file
    /// carries and no view models.
    fn from(path: &GffPath) -> Self {
        Self::new(
            path.segments()
                .iter()
                .map(|segment| match segment {
                    GffPathSegment::Field(label) => RouteStep::Field(*label),
                    GffPathSegment::Index(_) => RouteStep::Element,
                })
                .collect(),
        )
    }
}

impl fmt::Display for FieldRoute {
    /// Dot notation with empty brackets: `Creature List[].HitPoints`.
    ///
    /// The empty bracket is the point. A reader seeing `[0]` would take it for
    /// one element rather than every one.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut first = true;
        for step in &self.steps {
            match step {
                RouteStep::Field(label) => {
                    if !first {
                        write!(f, ".")?;
                    }
                    write!(f, "{label}")?;
                }
                RouteStep::Element => write!(f, "[]")?,
            }
            first = false;
        }
        Ok(())
    }
}

/// Why a rendered route would not parse back.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum RouteParseError {
    /// A step between the dots is not a label a GFF can carry.
    #[error("`{segment}` is not a usable label: {source}")]
    Label {
        /// The offending text.
        segment: String,
        /// What the label rejected it for.
        source: GffLabelError,
    },
    /// A bracket carries something, and a route's brackets are always empty.
    #[error("`[{inside}]` carries an index, and a route addresses every element")]
    IndexedBracket {
        /// What was between the brackets.
        inside: String,
    },
    /// A bracket was opened and not closed.
    #[error("`{route}` opens a bracket it does not close")]
    UnclosedBracket {
        /// The input.
        route: String,
    },
}

impl FromStr for FieldRoute {
    type Err = RouteParseError;

    /// Parses what [`Display`](fmt::Display) renders.
    ///
    /// A bracket has to be empty. `Creature List[0].HitPoints` is a
    /// [`GffPath`] and naming one element is what a route does not do, so it
    /// is refused rather than read as if the index were decoration.
    fn from_str(route: &str) -> Result<Self, Self::Err> {
        let mut steps = Vec::new();
        for piece in route.split('.') {
            let (name, mut rest) = match piece.find('[') {
                Some(at) => (&piece[..at], &piece[at..]),
                None => (piece, ""),
            };
            if !name.is_empty() {
                steps.push(RouteStep::Field(GffLabel::new(name).map_err(|source| {
                    RouteParseError::Label {
                        segment: name.to_owned(),
                        source,
                    }
                })?));
            }
            while !rest.is_empty() {
                let close = rest
                    .find(']')
                    .ok_or_else(|| RouteParseError::UnclosedBracket {
                        route: route.to_owned(),
                    })?;
                let inside = &rest[1..close];
                if !inside.is_empty() {
                    return Err(RouteParseError::IndexedBracket {
                        inside: inside.to_owned(),
                    });
                }
                steps.push(RouteStep::Element);
                rest = &rest[close + 1..];
            }
        }
        Ok(Self::new(steps))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::gff_label;

    fn route(text: &str) -> FieldRoute {
        text.parse().expect("the test's own route parses")
    }

    #[test]
    fn a_route_renders_its_list_levels_as_empty_brackets() {
        let route = FieldRoute::new(vec![
            RouteStep::Field(gff_label!("Creature List")),
            RouteStep::Element,
            RouteStep::Field(gff_label!("HitPoints")),
        ]);
        assert_eq!(route.to_string(), "Creature List[].HitPoints");
        assert_eq!(route.holes(), 1);
    }

    #[test]
    fn rendering_and_parsing_are_the_same_shape() {
        for text in [
            "HitPoints",
            "Creature List[].HitPoints",
            "AreaProperties.AmbientSndDay",
            "EntryList[].RepliesList[].Active",
        ] {
            assert_eq!(route(text).to_string(), text);
        }
    }

    /// Projecting a path keeps its labels and drops which element was in hand.
    #[test]
    fn a_path_projects_to_the_route_it_took() {
        let path: GffPath = "Creature List[3].HitPoints"
            .parse()
            .expect("the test's own address parses");
        assert_eq!(
            FieldRoute::from(&path),
            route("Creature List[].HitPoints"),
            "an index survived the projection"
        );
    }

    /// `at` and the projection are inverses, which is the pair's whole claim.
    ///
    /// One direction only: supplying indices and taking them away again is the
    /// identity, while going the other way cannot be, since the indices are
    /// gone by then.
    #[test]
    fn supplying_indices_and_projecting_them_back_off_is_the_identity() {
        for (text, indices) in [
            ("HitPoints", &[][..]),
            ("Creature List[].HitPoints", &[3][..]),
            ("EntryList[].RepliesList[].Active", &[0, 7][..]),
        ] {
            let route = route(text);
            let path = route.at(indices).expect("the index count is the route's");
            assert_eq!(FieldRoute::from(&path), route, "`{text}` did not survive");
        }
    }

    /// Projection is not the string round trip, and could not be.
    ///
    /// A rendered path with an index in it is refused by the route parser on
    /// purpose, so a caller holding a path has no way through text and the
    /// conversion is the only door.
    #[test]
    fn a_path_projects_even_though_its_text_will_not_parse_as_a_route() {
        let path: GffPath = "Creature List[3].HitPoints"
            .parse()
            .expect("the test's own address parses");
        assert!(path.to_string().parse::<FieldRoute>().is_err());
        assert_eq!(FieldRoute::from(&path).holes(), 1);
    }

    /// A route addresses the field in every file, so a bracket carrying an
    /// index is a [`GffPath`] rather than a route and is refused instead of
    /// being read with the index thrown away.
    #[test]
    fn a_bracket_with_an_index_in_it_is_not_a_route() {
        assert!(matches!(
            "Creature List[3].HitPoints".parse::<FieldRoute>(),
            Err(RouteParseError::IndexedBracket { .. })
        ));
        assert!(matches!(
            "Creature List[.HitPoints".parse::<FieldRoute>(),
            Err(RouteParseError::UnclosedBracket { .. })
        ));
    }

    #[test]
    fn supplying_the_indices_turns_a_route_into_a_path() {
        let path = route("Creature List[].HitPoints")
            .at(&[3])
            .expect("one index for one list level");
        assert_eq!(path.to_string(), "Creature List[3].HitPoints");

        let nested = route("EntryList[].RepliesList[].Active")
            .at(&[2, 7])
            .expect("two indices for two list levels");
        assert_eq!(nested.to_string(), "EntryList[2].RepliesList[7].Active");
    }

    /// The count is the mistake a two-list route makes, so it is an error
    /// rather than a silent truncation or a zero.
    #[test]
    fn the_wrong_number_of_indices_is_refused_in_both_directions() {
        let one = route("Creature List[].HitPoints");
        assert!(matches!(
            one.at(&[]),
            Err(RouteError::IndexCount {
                wanted: 1,
                given: 0,
                ..
            })
        ));
        assert!(matches!(
            one.at(&[1, 2]),
            Err(RouteError::IndexCount {
                wanted: 1,
                given: 2,
                ..
            })
        ));
        assert!(route("HitPoints").at(&[]).is_ok());
    }
}