//! # Epoch configuration and state //! //! The *epoch* system is deliberately split into two tiny, serialisable //! structures so that the binary can quickly read/write its “current //! position” without pulling the whole world into memory. //! //! * `EpochConfig` – lives in `.epochconfig`. It only remembers //! which epoch folder should be considered “current” and a few //! convenience fields (tags, path). It never holds any event or //! world data. //! //! * `EpochInfo` – stored inside `epoch//.epochinfo`. //! This file contains the *metadata* for that particular epoch //! (seed, selected events, parent link, etc.). Again, it does **not** //! hold the full world; that is handled elsewhere in the engine. //! //! Keeping these two structs tiny means that switching epochs, logging, //! or resetting can be done by reading/writing a handful of JSON/YAML //! files, just like a git repository tracks its commits and //! `HEAD` pointer. #![warn(missing_docs, clippy::missing_docs_in_private_items)] use clap::error::ErrorKind; use derive_more::Display; use serde::{Deserialize, Serialize}; use std::{ ops::{Deref, DerefMut}, str::FromStr, }; use crate::error::EpochError; pub mod epoch_config; pub use epoch_config::EpochConfig; pub mod epoch_info; pub use epoch_info::EpochInfo; // TODO[5]: Try to load from a config and have it inserted as a backup /// The subfolder naming convention static SUBFOLDER_NAMING: &str = "epoch"; /// The main name of the epoch static MAIN_NAME: &str = ".epoch"; /// The subname of the epochinfo static SUB_NAME: &str = ".epochinfo"; /// A lightweight wrapper around a list of tags. /// /// The wrapper exists mainly to give the collection a semantic type /// and to hide the internal representation. #[derive(Debug, Clone, Serialize, Deserialize, Display)] #[display("{inner:?}")] pub struct TagList { /// The inner vector of tags inner: Vec, } impl TagList { /// Create a new empty tag list fn new() -> Self { Self { inner: Vec::new() } } } impl Deref for TagList { type Target = Vec; fn deref(&self) -> &Self::Target { &self.inner } } impl DerefMut for TagList { fn deref_mut(&mut self) -> &mut Self::Target { &mut self.inner } } /// Which save mode to use #[allow(missing_docs)] pub enum SaveMode { DoNotErase, Erase, } /// Thin type to handle EpochIds #[derive( Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Display, )] #[display("{id}")] pub struct EpochId { /// The underlying numeric value. pub id: u64, } impl FromStr for EpochId { type Err = EpochError; fn from_str(s: &str) -> Result { Ok(EpochId { id: s.parse()? }) } } impl EpochId { /// Creates a new `EpochId` from a numeric value. pub fn new(id: u64) -> Self { Self { id } } /// Return the next epochId pub fn next(&self) -> Self { Self { id: self.id + 1 } } } impl std::ops::Deref for EpochId { type Target = u64; fn deref(&self) -> &Self::Target { &self.id } } /// A flexible identifier for *any* epoch – the world may be /// addressed by a numeric ID or by a friendly tag (e.g. `"winter‑b"`). /// /// The enum is `untagged` so that serialising/deserialising does /// **not** add a wrapper field, e.g. `{"Tag":"foo"}`. /// Instead the JSON representation is exactly the inner value: /// * `"42"` → `EpochIdentifier::Id(EpochId::new(42))` /// * `"foo"` → `EpochIdentifier::Tag("foo".into())` #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, Hash)] #[serde(untagged)] // <‑‑ no “type” wrapper is written to JSON pub enum EpochIdentifier { /// A textual tag that maps to a numeric epoch ID in `EpochConfig::tags`. Tag(String), /// The raw numeric identifier of the epoch. Id(EpochId), } impl FromStr for EpochIdentifier { type Err = clap::Error; // any `std::error::Error` works /// Try to parse either a decimal number (-> `Id`) or any non‑empty /// string (-> `Tag`). /// /// Errors are converted to a Clap error so that the CLI shows a /// nice message. fn from_str(s: &str) -> Result { if let Ok(num) = s.parse::() { Ok(EpochIdentifier::Id(EpochId::new(num))) } else if !s.is_empty() { Ok(EpochIdentifier::Tag(s.to_owned())) } else { Err(clap::Error::raw( ErrorKind::InvalidValue, format!("{} is not a valid epoch id or tag", s), )) } } }