rakata_formats/

content_source.rs

//! What a reader is allowed to ask the outside world for.
//!
//! Turning engine integers into typed semantics means reaching things that
//! live outside the file being read: a 2DA row, a line of display text,
//! whether a referenced resource is actually there. Taking a concrete
//! resource-mounting type instead would drag that whole layer into every
//! crate that only wanted to parse and resolve bytes.
//!
//! [`ContentSource`] is that seam. It lives in `rakata-formats` because it
//! returns a [`TwoDa`], and formats is the lowest crate that can name one.
//!
//! ## Nothing consumes it today
//!
//! The decoded views were its caller and they have been removed, pending a
//! consumer that can state requirements. What keeps the seam here rather
//! than deleting it with them is the ruling it was built for: "no install"
//! is a source that answers nothing, not a second code path through every
//! reader. If the decoded layer has not been rebuilt by the time the write
//! path lands, this goes then.
//!
//! ## Capability is opt-in
//!
//! Every method has a default body, so an implementor writes only the
//! capabilities it has. A decode test hands in a map of tables and
//! implements one method; an install-backed source implements all of them.
//! A capability added here later breaks no implementor and no call site.
//!
//! **The defaults answer "I did not look", never "no".** That distinction is
//! the reason [`ContentSource::resource_exists`] returns `Option<bool>`
//! rather than a `bool`: a source with no install behind it saying `false`
//! is a negative claim from something that never went looking, and a caller
//! cannot tell that apart from a real absence.
//!
//! ## Shape
//!
//! Every method takes `&mut self`, including the read-only ones. Mixing
//! `&self` in buys nothing, because the borrow conflict callers hit comes
//! from holding a returned table, and that blocks a shared borrow exactly as
//! hard as a mutable one. Uniform `&mut self` leaves every capability free
//! to populate itself lazily, which is what an install-backed talk table
//! needs.
//!
//! Only the table is returned borrowed. It is large and a resolver reads
//! several cells out of one row, so the borrow earns itself. Strings are
//! small and read once, and a second borrowing accessor would multiply the
//! inner-block dance `Uti`'s magnitude resolution already needs across every
//! view.
//!
//! The trait is not object-safe, since the table lookup takes
//! `impl AsRef<str>`. Call sites take `&mut impl ContentSource`, so nothing
//! needs it to be.

use rakata_core::{ResRef, ResourceTypeCode, StrRef};

use crate::twoda::TwoDa;

/// Something a reader can resolve external references against.
///
/// See the [module docs](self) for why every method is defaulted and why
/// the defaults are non-answers rather than falsy values.
pub trait ContentSource {
    /// Returns the named table, or `None` if it cannot be produced.
    ///
    /// `name` is a bare table name with no `.2da` extension, so both a
    /// `&str` literal and a `TwoDaName` constant work at the call site.
    ///
    /// The `None` case merges "no such table" with "the table would not
    /// parse". A decoder falls back to raw values either way, and a caller
    /// that needs to tell the two apart should ask the implementation
    /// directly rather than route that through resolution.
    fn twoda(&mut self, name: impl AsRef<str>) -> Option<&TwoDa> {
        let _ = name;
        None
    }

    /// Returns the display text a `StrRef` names.
    ///
    /// `None` covers a source with no talk table behind it as well as a
    /// `StrRef` that names no entry. A caller that got `None` displays the
    /// raw `StrRef`.
    fn text(&mut self, strref: StrRef) -> Option<String> {
        let _ = strref;
        None
    }

    /// Returns the voiceover resource a `StrRef`'s entry names.
    ///
    /// Talk table entries carry a VO resref alongside their text, so this is
    /// a second read of the same entry rather than a separate lookup.
    fn voiceover(&mut self, strref: StrRef) -> Option<ResRef> {
        let _ = strref;
        None
    }

    /// Returns whether the named resource resolves.
    ///
    /// `None` means this source cannot answer, which is not the same as
    /// `Some(false)`: a decoded view flagging a broken reference must not
    /// treat "nobody looked" as "the resource is missing".
    fn resource_exists(
        &mut self,
        resref: &ResRef,
        resource_type: ResourceTypeCode,
    ) -> Option<bool> {
        let _ = (resref, resource_type);
        None
    }
}

/// A source that answers nothing.
///
/// This is what a caller with no install behind it hands in, and it matters
/// more than a convenience type would. Without it a CLI inspecting a loose
/// file would stop at a projection while a GUI with an install reached a
/// resolved view, and the two could not share display code. With it there is
/// one resolved type everywhere, and having no install is a source that
/// declines every question rather than a separate path through the program.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
pub struct NoSource;

impl ContentSource for NoSource {}

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

    /// The shape a decode test double takes: one capability, three defaults.
    #[derive(Default)]
    struct TablesOnly(Option<TwoDa>);

    impl ContentSource for TablesOnly {
        fn twoda(&mut self, _name: impl AsRef<str>) -> Option<&TwoDa> {
            self.0.as_ref()
        }
    }

    fn one_table() -> TwoDa {
        TwoDa {
            headers: vec!["label".to_string()],
            rows: vec![TwoDaRow {
                label: "0".to_string(),
                cells: vec!["alpha".to_string()],
            }],
        }
    }

    #[test]
    fn implementing_one_capability_leaves_the_others_answering_nothing() {
        // The defaults are the mechanism the whole design rests on: a double
        // that only knows tables must not start asserting things about text
        // or about what an install contains.
        let mut source = TablesOnly(Some(one_table()));

        assert!(source.twoda("anything").is_some(), "the one impl is live");
        assert_eq!(source.text(StrRef::from_raw(0)), None);
        assert_eq!(source.voiceover(StrRef::from_raw(0)), None);
        assert_eq!(
            source.resource_exists(
                &ResRef::new("nwscript").expect("valid resref"),
                ResourceTypeCode::from_raw_id(2009)
            ),
            None,
            "a source with no install must not claim the resource is absent"
        );
    }

    #[test]
    fn the_null_source_declines_every_capability_including_tables() {
        let mut source = NoSource;

        assert!(source.twoda("appearance").is_none());
        assert_eq!(source.text(StrRef::from_raw(0)), None);
        assert_eq!(source.voiceover(StrRef::from_raw(0)), None);
        assert_eq!(
            source.resource_exists(
                &ResRef::new("nwscript").expect("valid resref"),
                ResourceTypeCode::from_raw_id(2009)
            ),
            None
        );
    }
}