epoch_forge/lib_efo/src/epoch.rs

161 lines
4.6 KiB
Rust

//! # 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;
pub mod epoch_traits;
// 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),
))
}
}
}