Skip to main content

nwnrs_resman/
lib.rs

1#![forbid(unsafe_code)]
2#![doc = "# nwnrs-resman\n\n`nwnrs-resman` defines the central resource-resolution model used by the rest\nof the workspace.\n\n## Scope\n\n- model a single payload as [`Res`]\n- model a source of payloads as [`ResContainer`]\n- resolve multiple containers in precedence order through [`ResMan`]\n- provide optional weighted caching for repeated lookups\n\nThis crate is intentionally abstract. The container crates supply concrete\nbackends; `nwnrs-resman` supplies the common lookup algebra.\n\n## Example\n\n```rust\nuse nwnrs_resman::ResMan;\n\nlet resman = ResMan::new(64);\nassert!(resman.contents().is_empty());\n```\n\n## Public Surface\n\n### Core aliases and constants\n\n- `MEMORY_CACHE_THRESHOLD`\n- `ReadSeek`\n- `SharedReadSeek`\n- `ResIoSpawner`\n\n### Cache behavior\n\n- `CachePolicy`\n\n### Error and result vocabulary\n\n- `ResManError`\n- `ResManResult`\n\n### Resource identity and provenance\n\n- `ResOrigin`\n- `new_res_origin`\n- `shared_stream`\n\n### Resource payload model\n\n- `Res`\n\n### Container abstraction\n\n- `ResContainer`\n\n### Manager\n\n- `ResMan`\n\n### Important `ResMan` operations\n\n- `ResMan::new`\n- `ResMan::contains`\n- `ResMan::demand`\n- `ResMan::contents`\n- `ResMan::get_resolved`\n- `ResMan::get`\n- `ResMan::add`\n- `ResMan::containers`\n- `ResMan::remove`\n- `ResMan::remove_at`\n- `ResMan::cache`\n\n## Logical Edges\n\n- precedence order is front-to-back; newly added containers shadow older ones\n- `contains` and `demand` can consult or bypass the manager cache according to\n  `CachePolicy`\n- `Res` is lazy and owns decompression metadata as part of the resource model\n- small decoded payloads may be memoized inside `Res::read_all`\n- `ResOrigin` is provenance for diagnostics, not identity\n- the `ResContainer` trait is intentionally abstract so different storage forms\n  can plug into the same lookup model\n\n## Why This Crate Exists\n\nThis crate is the core of install-backed and archive-backed tooling. Without it,\nevery workflow would need to hard-code its own precedence policy across\ndirectories, KEY/BIF sets, ERFs, and manifests.\n\n## See also\n\n- [`nwnrs-resdir`](https://docs.rs/nwnrs-resdir), the directory-backed\n  `ResContainer` implementation\n- [`nwnrs-resfile`](https://docs.rs/nwnrs-resfile), the single-file\n  `ResContainer` implementation\n- [`nwnrs-resmemfile`](https://docs.rs/nwnrs-resmemfile), the in-memory\n  `ResContainer` implementation\n- [`nwnrs-resnwsync`](https://docs.rs/nwnrs-resnwsync), the `NWSync`-backed\n  `ResContainer` implementation\n- [`nwnrs-install`](https://docs.rs/nwnrs-install), which assembles a\n  conventional install-backed manager\n"include_str!("../README.md")]
3
4mod manager;
5mod types;
6
7pub use manager::*;
8pub use types::*;
9
10/// Common imports for consumers of this crate.
11pub mod prelude {
12    pub use crate::{
13        CachePolicy, MEMORY_CACHE_THRESHOLD, ReadSeek, Res, ResContainer, ResIoSpawner, ResMan,
14        ResManError, ResManResult, ResOrigin, SharedReadSeek, new_res_origin, shared_stream,
15    };
16}