Expand description
Inventory serialisation and deserialisation to/from JSON files on disk.
This module provides two free functions — save_inventory and
load_inventory — that convert an crate::items::inventory::Inventory
to and from a human-readable JSON file. The format is intentionally simple
and hand-editable.
§File format
The JSON file is a single object with two top-level fields:
{
"capacity": 3,
"slots": [
null,
{ "item_byte": 2, "count": 7 },
null
]
}capacity— the maximum slot count of the original inventory.slots— one entry per slot;nullfor empty slots, or an object withitem_byte(the value returned bycrate::items::inventory::ItemType::to_byte) andcount.
§Save / load contract
save_inventoryvalidates the source and decoded byte-alias totals, creates missing parent directories, and replaces the destination with a synced sibling temporary file. Errors before replacement leave an existing save untouched.load_inventoryrestores the inventory with the samecapacityand slot layout. Zero counts and bytes decoded as default/empty becomeNoneat the same index; malformed layout or overflowing item totals are rejected.- Existing regular-file permissions are preserved. Final symlinks are followed
without replacing the link, on both save and load. Follow-through resolves
the link manually (see
resolved_link_target) instead of letting the kernel open through the reparse point: CI runners whose%TEMP%mixes the 8.3 short name (RUNNER~1) with long names returnERROR_INVALID_NAME(123) exactly when opening through a relative-target link. Dangling links, nonregular/read-only targets, and Unix multiply hard-linked targets are rejected. - Replacement provides whole-snapshot visibility, not transaction isolation between writers or universal power-cut durability. Parent directories must be trusted: hostile namespace races and preservation of existing ownership, ACLs, and extended attributes are outside this contract. New Windows files use a protected current-user-only DACL, verified before any JSON write; filesystems without persistent ACL support fail closed.
- Both functions propagate I/O and JSON errors as
Box<dyn std::error::Error>.
Functions§
- load_
inventory - Reads and deserialises an
crate::items::inventory::Inventoryfrom the JSON file atpath. - save_
inventory - Writes
inventoryto a pretty-printed JSON file atpath.