lib_efo/epoch/

epoch_traits.rs

//! epoch_traits.rs
//!
//! All traits used by the `lib_efo` library.
//! These traits are marker traits that describe behaviour
//! common to many of the library's element types.
#![warn(clippy::missing_docs_in_private_items)]

use cli_table::{Style, Table, WithTitle};
use serde::Serialize;
use std::{fmt::Display, fs::File, io::Write};
use uuid::Uuid;

use crate::{epoch::SaveMode, error::EpochError, items_table};

/// Elements that can be compared with another instance to produce a diff.
pub trait Diffable {
    /// Compare self with another struct of the same type and return a new instance containing the difference
    fn delta(&self, other: &Self) -> Self;
}

/// Elements that can be applied to the current world state.
pub trait Applyable {}

/// Elements that can advance to a next state over time.
///
/// Implementors usually provide a `.next()` method that returns the
/// element's state after a time step (e.g., fading or diminishing).
pub trait Nextable {}

/// Elements that can be rendered into a pretty, human-readable form.
pub trait Prettiable: Display {
    /// Shows many items as a table.
    fn as_table(list: Vec<&Self>) -> std::result::Result<cli_table::TableDisplay, EpochError>
    where
        for<'a> Vec<&'a Self>: Table + WithTitle,
    {
        items_table!(list, "Converting to table".to_string(), Uuid::nil())
    }

    /// Displays the struct as a log entry by printing the output of
    /// `as_log()` to stdout.
    fn show_as_log(&self) {
        println!("{}", self.as_log())
    }

    /// Converts the struct into a pretty log string.
    fn as_log(&self) -> String {
        format!("{}", self)
    }
}

/// Trait representing a serialisable / writable config
pub trait ConfigWritable: Serialize {
    /// The full path indicating where to save the config
    fn save_path(&self) -> String;

    /// The folder where to save the file to save the config
    fn save_folder(&self) -> String;

    /// Serialises the config into a pretty JSON string.
    ///
    /// # Arguments
    /// * `action` - A description of the action for error reporting.
    ///
    /// # Returns
    /// * `Ok(String)` containing the pretty-printed JSON.
    /// * `Err(EpochError::Serde)` if serialisation fails.
    fn as_json(&self, action: String) -> Result<String, EpochError> {
        serde_json::to_string_pretty(self).map_err(|e| EpochError::Serde {
            source: e,
            file_name: action,
            version: format!("Current Version:{}", env!("EFO_SHORT_VERSION")),
        })
    }

    /// Saves the config into its nominal path.
    ///
    /// Existing subdirectories are not created.
    /// If `do_not_erase` is `SaveMode::Erase`, an existing file is overwritten.
    /// If `do_not_erase` is `SaveMode::DoNotErase`, an error is returned when the
    /// file already exists.
    ///
    /// # Arguments
    /// * `action_description` - A human-readable description used in error messages.
    /// * `do_not_erase` - Determines whether to overwrite an existing file.
    ///
    /// # Returns
    /// * `Ok(())` on success.
    /// * `Err(EpochError::ConfigWrite)` on any serialization error.
    /// * `Err(EpochError::ConfigCreation)` on any I/O error.
    fn save_with_context(
        &self,
        // Very unsure about this versus a macro
        action_description: &str,
        do_not_erase: &SaveMode,
        // advice: Option<String>,
    ) -> Result<(), EpochError> {
        let mut f = match *do_not_erase {
            SaveMode::Erase => File::create(self.save_path()),
            SaveMode::DoNotErase => File::create_new(self.save_path()),
        }
        .map_err(|e| EpochError::ConfigCreation(self.save_path(), e))?;
        write!(f, "{}", self.as_json(action_description.to_owned())?)
            .map_err(EpochError::ConfigWrite)?;
        Ok(())
    }
}

#[allow(clippy::unwrap_used)]
#[cfg(test)]
mod tests {
    use super::*;
    use derive_more::Display;
    use insta::assert_snapshot;
    use tempfile::tempdir;

    /// A tiny helper struct that implements every trait you defined.
    #[derive(Debug, Clone, PartialEq, Serialize, Table, Display)]
    #[display("{id}:{value}")]
    struct DummyItem {
        id: Uuid,
        value: i32,
        #[serde(skip)]
        #[table(skip)]
        save: String,
    }

    impl DummyItem {
        fn new(value: i32) -> Self {
            Self {
                id: Uuid::nil(),
                value,
                save: tempdir()
                    .expect("Tempdir")
                    .path()
                    .join("dummy.json")
                    .to_string_lossy()
                    .into(),
            }
        }
    }

    impl Diffable for DummyItem {
        fn delta(&self, other: &Self) -> Self {
            Self {
                id: self.id, // keep the same id
                value: self.value - other.value,
                save: self.save.clone(),
            }
        }
    }

    // impl Applyable for DummyItem {}
    // impl Nextable for DummyItem {}
    impl Prettiable for DummyItem {}

    /* -------------------  ConfigWritable  ------------------- */
    impl ConfigWritable for DummyItem {
        fn save_path(&self) -> String {
            self.save.clone()
        }

        fn save_folder(&self) -> String {
            String::new()
        }
    }

    #[test]
    fn test_prettiable_as_table() {
        let item = DummyItem::new(42);
        let table = DummyItem::as_table(vec![&item]).expect("Dummytable");
        assert_snapshot!(format!("{}", table));
    }

    #[test]
    fn test_prettiable_show_as_log() {
        DummyItem::new(7).show_as_log();
    }

    #[test]
    fn test_config_writable_as_json() {
        let item = DummyItem::new(123);
        let json = item.as_json("test action".into()).unwrap();
        assert_snapshot!(json);
    }

    // fn dummy_with_tempfile(value: i32) -> (DummyItem, std::path::PathBuf) {
    //     let dummy = DummyItem::new(value);
    //     (dummy.clone(), dummy.save.clone().into())
    // }
    // #[test]
    // fn test_config_writable_save_with_context_erase() {
    //     let (item, path) = dummy_with_tempfile(10);
    //     // Erase: we expect a file to be created (or overwritten)
    //     item.save_with_context("Erase test", &SaveMode::DoNotErase)
    //         .unwrap();

    //     // Verify file contents
    //     let mut file = File::open(&path).unwrap();
    //     let mut contents = String::new();
    //     file.read_to_string(&mut contents).unwrap();

    //     assert_snapshot!(contents);
    // }

    // #[test]
    // fn test_config_writable_save_with_context_donot_erase() {
    //     let (item, _path) = dummy_with_tempfile(20);

    //     // First write - must succeed
    //     item.save_with_context("DoNotErase test 1", &SaveMode::DoNotErase)
    //         .unwrap();

    //     // Second write - should fail with `ConfigCreation` because the file
    //     // already exists.
    //     let err = item
    //         .save_with_context("DoNotErase test 2", &SaveMode::DoNotErase)
    //         .unwrap_err();

    //     assert_snapshot!(format!("{}", err));
    // }

    #[test]
    fn test_diffable_delta() {
        let a = DummyItem::new(30);
        let b = DummyItem::new(15);
        let diff = a.delta(&b);
        assert_eq!(diff.value, 15);
        assert_eq!(diff.id, a.id); // same id
    }
}