epoch_forge/lib_efo/src/epoch_struct.rs

160 lines
4.6 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

//! # 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/<epoch_id>/.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<String>,
}
impl TagList {
/// Create a new empty tag list
fn new() -> Self {
Self { inner: Vec::new() }
}
}
impl Deref for TagList {
type Target = Vec<String>;
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<Self, Self::Err> {
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<Self, Self::Err> {
if let Ok(num) = s.parse::<u64>() {
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),
))
}
}
}