rakata_formats/schema/

mod.rs

//! What is established about one GFF field, and the vocabulary for saying it.
//!
//! The shape follows what a field *is*, rather than growing a slot per defect
//! as each is found.
//!
//! # Nine facts
//!
//! Two are about the file: the label and, inside [`Shape`], the GFF type.
//! Five are about the engine: [`Life`], [`Absent`], `required`,
//! [`Constraint`] and [`Omission`]. Two are about this crate: the
//! [`Substitute`] its reader produces where the engine's answer names no
//! value, and `modelled`, whether this layer holds a member for the label at
//! all.
//!
//! # What is deliberately not here
//!
//! **Provenance.** A citation beside an entry enforces nothing: it catches an
//! empty string and never a false one. [`Life::Unexamined`] is the structural
//! answer to a field nobody has looked at. Provenance itself lives on the
//! pages under `docs/src/formats/`, keyed by the same labels these entries
//! declare.
//!
//! **The Rust type.** A field's type decides how to read it, how to write it
//! and which GFF type it maps to. Recording that mapping makes a closed table
//! somebody has to maintain, which this layer has already grown twice. Types
//! state their own mapping through [`GffScalar`] instead.

mod scalar;

pub use scalar::GffScalar;

use crate::gff::Gff;
use crate::gff::GffLabel;
use crate::gff::GffValue;

/// One field of one GFF struct, and everything established about it.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Field {
    /// The label as it appears in the file.
    ///
    /// A built [`GffLabel`] rather than a `&str`, so a declaration naming
    /// something a GFF cannot hold fails the build at that declaration. Three
    /// of the corpus's names run past sixteen bytes and the engine truncates
    /// them; a schema that did not would name a label no file can carry, and
    /// any rule keyed on it would be silently dead.
    pub label: GffLabel,
    /// What the field holds, and for a container what its elements hold.
    pub shape: Shape,
    /// Whether the engine reads this label at this path.
    pub life: Life,
    /// What happens when the label is missing.
    pub absent: Absent,
    /// Whether absence aborts the containing structure rather than defaulting.
    pub required: bool,
    /// Whether the engine clamps or truncates the value it reads.
    pub constraint: Option<Constraint>,
    /// Whether the engine's own writer leaves this label out at some value.
    pub omission: Option<Omission>,
    /// Whether this layer holds a member for the label.
    ///
    /// `false` for a label the schema declares and the view has no slot for,
    /// which is what `gff_entry` means. Those paths are real engine facts a
    /// reader cannot observe: whatever the engine substitutes for the absent
    /// label has nowhere to arrive, so a consumer asking "does the fallback
    /// matter here" gets a different answer than at a modelled path, and the
    /// difference is not visible from the other seven.
    pub modelled: bool,
}

impl Field {
    /// Whether the writer may leave this label out when it holds `value`.
    ///
    /// The engine's own writer omits some labels at some values, and matching
    /// it is what lets an authored file round-trip against one it wrote. A
    /// field declaring no omission answers `false`, so a missing opt-in costs
    /// a redundant label rather than a dropped value.
    ///
    /// [`OmitWhen::Matches`] always answers `false`. Its test is the resolved
    /// value of a sibling, which is not reachable from one entry, and the
    /// engine-side rule for it has not been traced; the fail-safe direction is
    /// to write the label.
    pub fn may_omit(&self, value: &GffValue) -> bool {
        let Some(omission) = self.omission else {
            return false;
        };
        match omission.when {
            OmitWhen::AuditedConstant => match self.absent {
                Absent::Resolves(_, default, _) => same_value(&default.get(), value),
                // No audited constant to compare against, which the derive
                // rejects at the declaration. Reachable only from a schema
                // written by hand.
                Absent::Silent(..) => false,
            },
            OmitWhen::Empty => matches!(value, GffValue::List(items) if items.is_empty()),
            // Neither decides whether to write the label. `Matches` chains off
            // a sibling this cannot resolve, and `Elements` is about what goes
            // in the list rather than whether the list is written.
            OmitWhen::Matches(_) | OmitWhen::Elements(_) => false,
        }
    }
}

/// Value equality with floats compared bit for bit.
///
/// `-0.0 == 0.0` under `PartialEq`, so a writer using it drops a label whose
/// bits differ from the default and the file stops round-tripping.
fn same_value(a: &GffValue, b: &GffValue) -> bool {
    match (a, b) {
        (GffValue::Single(x), GffValue::Single(y)) => x.to_bits() == y.to_bits(),
        (GffValue::Double(x), GffValue::Double(y)) => x.to_bits() == y.to_bits(),
        (GffValue::Vector3(x), GffValue::Vector3(y)) => {
            x.iter().zip(y).all(|(p, q)| p.to_bits() == q.to_bits())
        }
        (GffValue::Vector4(x), GffValue::Vector4(y)) => {
            x.iter().zip(y).all(|(p, q)| p.to_bits() == q.to_bits())
        }
        // Every remaining variant holds either an integer, a byte string or a
        // composite of those, and their `PartialEq` is exact.
        _ => a == b,
    }
}

/// What a field holds.
///
/// One fact rather than the old split across an expected type and a separate
/// child list, which had nowhere to put a list's element struct id and no way
/// at all to describe a field whose element schema is chosen at run time.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Shape {
    /// A single value of this GFF type.
    Scalar(GffType),
    /// A nested struct with its own fields.
    Struct {
        /// The child schema, in parts.
        ///
        /// A sequence rather than one slice so a type can be its own fields
        /// plus a flattened child's without copying either. Copying would make
        /// each shared field two declarations where the audit records one.
        fields: &'static [&'static [Field]],
    },
    /// A list of structs, all carrying `element`, some carrying more.
    List {
        /// What every element carries, whichever form it takes, in parts.
        ///
        /// Two lists whose elements differ by one label point the shared part
        /// at one array and add their own: an entry node's links are
        /// `RepliesList` and a reply node's are `EntriesList`, and the
        /// twenty-eight they share stay twenty-eight declarations.
        element: &'static [&'static [Field]],
        /// The struct id vanilla writes on each element.
        element_id: ElementId,
        /// `None` for an ordinary list.
        split: Option<Split>,
    },
}

/// A list whose elements carry extra fields chosen by a sibling of the list.
///
/// An addition to a list rather than a kind of list, which is what the GIT
/// case turned out to need. `UseTemplates` sits at the root beside every
/// object list and decides, for all of them at once, whether an element points
/// at a blueprint or carries the object whole. The selector is a sibling, so
/// resolving a shape needs only the struct the list was found on, and its own
/// entry says what its absence means rather than this restating it.
///
/// Two whole schemas was the first shape and it did not survive contact with
/// the corpus: a `Creature List` element carries one label in the templated
/// form only, 106 in the saved form only, and five in both. Those five would
/// have been restated in each arm, with their own liveness and absent-value,
/// on every object list using the shape. As an addition they are simply the
/// element schema, declared once.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Split {
    /// Label of the sibling that decides which extras apply.
    pub selector: GffLabel,
    /// Extra fields where the selector is set, in parts.
    ///
    /// Parts rather than one slice, for the reason every other container
    /// takes parts: an arm that flattens a block would otherwise lose it, and
    /// GIT's saved arms flatten four apiece. The arm contributes its whole
    /// schema here, so the element it shares with the other arm is held as a
    /// plain member and written by the arm's own codec rather than flattened,
    /// which is what keeps the common block one declaration.
    pub when_set: &'static [&'static [Field]],
    /// Extra fields where it is clear or absent, in parts.
    pub when_clear: &'static [&'static [Field]],
}

/// The struct id the engine's own writer puts on a list's elements.
///
/// An enum rather than an optional number, because a positional id is a rule
/// the engine follows rather than the absence of one. Spelling it as `None`
/// would make absence carry an answer, which is the shape a whole liveness
/// axis was rebuilt to stop, and it would leave a list whose id nobody
/// established with no spelling of its own.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ElementId {
    /// Nobody has established what an element carries here.
    ///
    /// What an entry declaring a label and modelling no element behind it gets.
    /// There is no element schema to hang an id on and this layer writes no
    /// element there, so an id would be a claim about an untouched list.
    ///
    /// The default, so that an axis with no way of saying this cannot silently
    /// answer [`Positional`] for every such entry. A modelled list has to
    /// declare an id and the derive refuses it otherwise, so this variant
    /// means the entry models nothing rather than that somebody forgot.
    ///
    /// [`Positional`]: Self::Positional
    Unexamined,
    /// Every element carries this id.
    Fixed(i32),
    /// Each element carries its own index in the list.
    Positional,
    /// The id is data: the engine reads the element's struct id off the header
    /// rather than any field, so a writer has to preserve it and the model has
    /// to carry it somewhere.
    ///
    /// `Equip_ItemList` is the case. Its id is the equipment slot, which no
    /// label repeats, so an element written with the wrong one equips into the
    /// wrong slot with nothing in the file to say so.
    Meaningful,
    /// A value every writer puts there and no loader tests.
    ///
    /// Distinct from [`Fixed`](Self::Fixed), which is what a loader *demands*.
    /// Where nothing checks, two writers can disagree without either being
    /// wrong, and a corpus that shows them disagreeing is reporting the engine
    /// rather than a defect. Saying `Fixed` there would claim an enforcement
    /// nothing performs.
    ///
    /// The reason is carried rather than described elsewhere, so a list cannot
    /// be marked unenforced without saying what was checked.
    Unenforced {
        /// The value to write, since something has to be written.
        writes: i32,
        /// Why nothing rejects a file that writes something else. Reads on
        /// from "nothing rejects a file writing something else, because".
        why: &'static str,
    },
}

/// Whether the engine reads a label at a path, and if not, why saying so helps.
///
/// A schema answers "what may a legitimate file contain", which is wider than
/// "what does the engine read": labels the engine ignores still appear in
/// files the toolset wrote, so leaving them out would make an
/// unrecognized-field check fire once per shipped resource. Keeping them
/// without marking them is not much better, because then a diagnostic can only
/// say a field is unrecognized when the useful message is that setting it does
/// nothing and here is what the engine reads instead.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Life {
    /// The engine reads this label at this path.
    Live,
    /// Legitimate file content the engine never reads, with why.
    ///
    /// The payload finishes the sentence "setting it has no effect, because
    /// ...". A payload rather than an optional note, so no marking can exist
    /// without one.
    ReadOnlyDead(&'static str),
    /// The engine writes it and never reads it back.
    WriteOnlyDead(&'static str),
    /// Nobody has looked.
    ///
    /// The default, and countable. This is the state the old axis lacked, and
    /// lacking it is what let a thousand entries claim the engine reads a
    /// field when all anyone knew was that the field existed.
    Unexamined,
}

/// What the engine does when the label is missing.
///
/// The engine's finding and this crate's substitute are facts about different
/// actors, and one slot cannot hold both without one standing in for the
/// other. Splitting them is also what makes a substitute unrepresentable where
/// the engine already has a value: [`Absent::Resolves`] has no room for one.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Absent {
    /// The engine resolves the missing label to a value.
    ///
    /// [`Taken`] says whether this crate's reader takes it. There is no slot
    /// for a value of its own: a reader either takes the engine's or keeps the
    /// absence, so a third answer stays unrepresentable.
    Resolves(Resolution, Produced, Taken),
    /// The engine's answer names no value, so the reader decides for itself.
    Silent(Silence, Substitute),
}

/// What this crate's reader does with a value the engine resolves.
///
/// Holds no value of its own, which is what keeps the axis closed: a consumer
/// can read that the reader declined the engine's answer, never an alternative
/// number in its place.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Taken {
    /// The reader hands back the engine's value.
    Same,
    /// The model holds the absence instead, because absence and the engine's
    /// value are both real in the corpus and collapsing them would lose one.
    PresenceKept,
}

/// How the engine's value for a missing label arises.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Resolution {
    /// A literal applied at the read site, whatever the object already held.
    Stamped,
    /// The object's own constructed value, carried over because the read's
    /// fallback argument is that member.
    Constructed,
}

/// Why the engine's answer names no value.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Silence {
    /// A mechanism rather than a constant: the value chains off a sibling, or
    /// off whatever the object held, and no literal describes it.
    NotAConstant,
    /// The object is allocated without being zeroed and nothing assigns the
    /// member, so an absent field leaves whatever the memory held.
    Undefined,
    /// Somebody looked and the page does not say.
    Unanswered,
    /// Nobody has looked.
    Unexamined,
}

/// What this crate's reader hands back where the engine's answer names no
/// value.
///
/// This crate's answer, not the engine's. Recording it stops a reader
/// inventing a number in an `unwrap_or` beside an entry that says no value is
/// known, which is how twelve non-obvious literals came to sit in readers with
/// nothing recording them.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Substitute {
    /// The field's Rust type decided, so a rebuild regenerates it.
    ///
    /// Carries the value anyway. A consumer that can name the state but not
    /// the value has only "the type decides" to print, which is a cell with
    /// nothing in it.
    TypeDefault(Produced),
    /// A specific value this layer chose. Not an engine fact.
    Ours(Produced),
    /// There is nothing to substitute: the model holds the absence itself, so
    /// a reader hands back "not there" rather than a stand-in.
    NoValue,
    /// The reader works it out from sibling fields, and this deliberately does
    /// not model how.
    ///
    /// [`Silence::NotAConstant`] refuses the same thing on the engine's side,
    /// for the same reason: encoding a derivation would put a small expression
    /// language in a static table to serve a handful of fields. Three entries
    /// need it. The derivation lives in the view's own reader, where it can be
    /// read as code.
    FromSiblings,
}

/// A value produced on demand, because a `const` cannot hold a `String`.
///
/// # Why this is a type rather than a bare `fn` pointer
///
/// Holding the default as a call is what keeps the schema a `const`, and the
/// pointer that makes that work poisons every trait that reflects over it.
/// A derived `Debug` prints an address, which changes between runs and says
/// nothing about the entry; the extraction records values through `Debug`, so
/// a raw pointer would put addresses in the audit file. A derived `PartialEq`
/// compares addresses, and identical-code folding merges two closures with the
/// same body only when optimising, so the answer depends on the build profile.
///
/// Fixing those one trait at a time lets the next one through. Wrapping the
/// pointer once fixes the class: the containing types derive normally and are
/// right by construction.
#[derive(Clone, Copy)]
pub struct Produced(fn() -> GffValue);

impl Produced {
    /// Wraps a producer. Takes a plain function pointer, so a non-capturing
    /// closure coerces at the call site.
    pub const fn new(make: fn() -> GffValue) -> Self {
        Self(make)
    }

    /// Runs the producer. A text value allocates on each call.
    pub fn get(self) -> GffValue {
        (self.0)()
    }
}

impl std::fmt::Debug for Produced {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        std::fmt::Debug::fmt(&self.get(), f)
    }
}

impl PartialEq for Produced {
    fn eq(&self, other: &Self) -> bool {
        self.get() == other.get()
    }
}

// `Hash` and `Ord` are left off deliberately. Deriving either on an entry then
// fails to build rather than hashing or ordering an address, which turns the
// next instance of this trap into a compile error instead of a wrong answer.

/// A range the engine clamps a read value into.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Constraint {
    /// Inclusive integer bounds.
    RangeInt(i64, i64),
    /// Inclusive float bounds.
    RangeFloat(f64, f64),
}

/// The engine's own writer leaves this label out at some value.
///
/// Carries the population it was measured against, because the conclusion
/// without its denominator is an assertion rather than a measurement: a row
/// means the label was looked for across that many files and appeared in none
/// of them.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Omission {
    /// The value at which the label is left out.
    pub when: OmitWhen,
    /// How many files it was looked for in.
    pub files: usize,
}

/// The equality test an omission is decided by.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OmitWhen {
    /// The engine's own absent-value for this field.
    AuditedConstant,
    /// An empty container.
    Empty,
    /// Elements the writer leaves out, so what it produces is a shorter list
    /// than the one it read.
    ///
    /// Distinct from [`Empty`](Self::Empty): whether to write the label at all
    /// and which elements go in it are different questions. A faction table is
    /// the case. `CFactionManager::SaveReputations` emits a `RepList` entry
    /// only for a pair that is not at the friendly baseline, and a
    /// toolset-authored `.fac` carries entries that are, so reading one and
    /// writing it back produces fewer elements without losing anything: an
    /// entry at the baseline overrides the baseline with itself.
    ///
    /// Carries the test in words rather than a predicate. The filter runs on
    /// the typed element, where the value it tests is reachable, and nothing
    /// here holds one.
    Elements(&'static str),
    /// The resolved value of the named sibling this field chains off.
    Matches(GffLabel),
}

/// Associates a schema with the type it describes.
///
/// Lets lint and the docs build take a view generically without either naming
/// the fourteen types, which is what stops a consumer growing its own list of
/// them.
pub trait HasSchema {
    /// The root field schema for this resource type.
    fn schema() -> &'static [Field];

    /// The same schema in parts, own fields first.
    ///
    /// A type that flattens a shared block holds those fields in a later part
    /// rather than in [`schema`](Self::schema), so a walk wanting everything
    /// the type declares reads this instead. No view flattens at its root
    /// today, which is why the two agree; one that did would leave a walk
    /// built on `schema` quietly short of a block, and every nested descent
    /// already goes through parts.
    fn parts() -> &'static [&'static [Field]];
}

/// Reads a typed view out of a parsed container.
///
/// The same reason as [`HasSchema`], one step over. Each view's inherent
/// `from_gff` carries its own error type, so a caller that does not already
/// know which view it wants cannot call it, and
/// [`GffDocument::view`](crate::GffDocument::view) is exactly that caller.
///
/// A view that cannot fail names [`Infallible`](std::convert::Infallible) here.
///
/// # Only a whole file implements this
///
/// [`HasSchema`] is derived onto every modelled struct, nested ones included,
/// because a schema describes a struct at any depth. This is narrower on
/// purpose: a container has a magic and a nested struct does not, so only the
/// root of a format is here. That is what makes [`MAGIC`](Self::MAGIC) a
/// question every implementor can answer.
pub trait FromGff: Sized {
    /// What reading this view out of a tree can fail with.
    type Error;

    /// The four bytes a container of this format carries.
    ///
    /// A GFF says what it is in its own first four bytes, so this is the file's
    /// claim about itself rather than anything about where it was found: it
    /// survives a rename, storage in an archive under a resref, and being
    /// carried inside a save. Extensions do not, and neither does
    /// [`ResourceType`](rakata_core::ResourceType), which has no entry at all
    /// for the `.res` a save sidecar uses.
    ///
    /// On the trait so it is declared once and read wherever it is needed:
    /// the view's own reader refuses a container carrying something else, and a
    /// caller mapping a magic back to a schema looks it up. Two spellings of
    /// one magic is how those come to disagree.
    const MAGIC: [u8; 4];

    /// Reads the view. Anything the view does not model stays in `gff`.
    ///
    /// # Errors
    ///
    /// [`Self::Error`], on terms the implementing view decides. Every view in
    /// this workspace refuses a container whose file type is not
    /// [`Self::MAGIC`], and otherwise reports only what the underlying GFF
    /// read reports: a field of an unexpected type is taken where the type
    /// tolerates it and dropped where it does not, rather than failing.
    fn from_gff(gff: &Gff) -> Result<Self, Self::Error>;
}

mod route;
pub use route::{routes_in, routes_under, FieldRoute, RouteError, RouteParseError, RouteStep};

mod wire;

/// The GFF wire types a scalar can be.
///
/// Emitted from the one declaration in [`gff`](crate::gff) that also produces
/// the wire enum, the runtime value and the serde DTO.
pub use wire::{gff_value_type, GffType};

#[cfg(test)]
mod tests;