bin_efo/commands/

entity_generic.rs

//! ## Guide
//!
//! The **entity** command manipulates the lists of game objects that live inside an *epoch*.  
//! An *epoch* is a snapshot of the game state that can be written to disk or rolled back to an earlier one.  
//! Every entity type (`character`, `town`, `event`, …) has the same set of operations:
//!
//! ## Summary
//!
//! | Sub‑command | Usage | What it changes |
//! |-------------|-------|-----------------|
//! | **add** | `<entity> add [OPTIONS] [IDENTIFIER]` | Creates a new `<entity>`, pushes it to the epoch’s list, and writes the epoch. |
//! | **del** | `<entity> del <IDENTIFIER>` | Removes the matching `<entity>` from the list and writes the epoch. |
//! | **edit** | `<entity> edit <IDENTIFIER> [OPTIONS]` | Modifies the stats/position/duration/effect/bounds of the chosen `<entity>` and writes the epoch. |
//! | **find** | `<entity> find <IDENTIFIER>` | Prints full details of a single `<entity>`. |
//! | **show** | `<entity> show [<IDENTIFIER>]` | Lists all entities on one line, or shows one `<entity>` in full detail. |
//! | **diff** | `<entity> diff <IDENTIFIER>` | Prints the difference between the current and previous epoch for that `<entity>`. |
//!
//! *`IDENTIFIER`* is either a **name** or a **@tag** (`@1234`).  
//! If omitted, a random name is generated for the type you are working on.
//!
//! ### Options
//!
//! | Flag | Description |
//! |------|-------------|
//! | `-d, --delta` | Apply a delta to the supplied stats (add or subtract) instead of overwriting them. |
//! | `-v, --verbose…` | Increase output verbosity. |
//! | `--rng <RNG>` | How to fill unspecified stats. <br>Possible values: `zero`, `low`, `med`, `high`, `legendary`, `mixed`, `flawed`. Default: `zero`. |
//! | `--pos-exact <POS>` / `--pos <POS>` | Place the new entity at a specific `x,y` coordinate (the epoch must be in a map context). |
//! | `--duration <DURATION>` | Lifespan of the entity (e.g. `Permanent`, `Temporary`, `Duration(1)` for a one‑turn event). |
//! | `--bounds <BOUNDS>` | Effect limits, given as `min,max` (e.g. `10,80`). |
//! | `--effect <EFFECT>` | How the effect is applied:<br>`recurring`, `when-present`, `permanent-effect-to-apply`, `permanent-effect-applied`. |
//! | `-s, --stats <STATS>` | One or more `key:value` pairs, e.g. `fod,10 military:8`. |
//!
//! ## Usage
//! All the following example use `chr` as a choice of entity but can be safely substitued to any entity: `event`, `town`, `blocker` etc...
//!
//! ```bash
//! # Create a character named “Aria”
//! chr add Aria \
//!   --stats fod:10 mil:8 \
//!   --rng mixed
//!
//! # Edit that character: bump military, shorten duration
//! chr edit Aria \
//!   --stats mil:5 \
//!   --duration Duration:5
//!
//! # Show all characters
//! chr show
//!
//! # Show one character in detail
//! chr show Aria
//!
//! # Delete a character
//! chr del Aria
//!
//! # Diff a character between two epochs
//! chr diff Aria
//! ```
//!
//! > **Tip** – `<entity> diff` automatically loads the current epoch and the previous one, so you don’t need to specify epoch numbers.
//!
//! *All changes are persisted immediately to the epoch file after the command finishes.*

use lib_efo::entity::{EffectApplication, EffectBounds, EntityDuration, EntityIdentifier};
use lib_efo::epoch::epoch_traits::{ConfigWritable, Diffable};
use lib_efo::naming::NAMING;
use lib_efo::stats::{Position, Symbols};

use clap::{Args, Subcommand};
use lib_efo::Displayable;
use lib_efo::utils::RngLevel;
use lib_efo::{
    entity::Entity,
    epoch::EpochConfig,
    error::EpochError,
    stats::{EntityType, StatPair},
};
use log::info;

use crate::error::AppError;
use crate::success::display_success;

/// Commands that operate on an entity.
///
/// Each variant represents a different operation that can be performed on an
/// entity. The variant holds the arguments that are common to all operations.
#[derive(Subcommand, Debug)]
pub enum EntitySubCommands {
    /// Add an entity
    Add(EntityArgs),
    /// Delete an entity
    Del(EntityArgs),
    /// Edit an existing entity
    Edit(EntityArgs),
    /// Find an entity by its identifier
    Find(EntityArgs),
    /// Show the details of an entity
    Show(EntityArgs),
    /// Show differences between two entities
    Diff(EntityArgs),
}

/// Arguments required for any entity operation.
///
/// All fields are required. The `rng` field determines how unspecified stat
/// values are handled when an entity is created or edited.
#[derive(Args, Debug)]
pub struct EntityArgs {
    /// The identifier either a name or a @tag
    pub identifier: Option<EntityIdentifier>,

    // /// A name to change to
    // #[arg(long, group = "identifier")]
    // pub new_name: Option<String>,
    /// Applies a delta to stats instead of setting the values
    #[arg(long, short, action = clap::ArgAction::SetTrue, default_value_t = false)]
    pub delta: bool,

    /// Non specified stat Repartition
    #[arg(value_enum, long, default_value_t = RngLevel::Zero)]
    pub rng: RngLevel,

    /// Adds at a specific position
    #[arg(long, group = "position")]
    pub pos_exact: Option<Position>,

    /// Adds at a specific position
    #[arg(long, group = "position")]
    pub pos: Option<Position>,

    /// The duration of the entity
    #[arg(long)]
    pub duration: Option<EntityDuration>,

    /// The bounds of the effect of the entity
    #[arg(long)]
    pub bounds: Option<EffectBounds>,

    /// How is the effect of the entity applied
    #[arg(long)]
    pub effect: Option<EffectApplication>,

    /// All stats pairs involved
    #[arg(short, long)]
    pub stats: Vec<StatPair>,
}

/// Handles an entity subcommand.
///
/// This function loads the main epoch configuration, then dispatches the
/// provided subcommand to the appropriate handler. It returns an
/// `AppError` if any operation fails.
///
/// # Arguments
/// * `entity_sub_commands` - The subcommand chosen by the user.
/// * `e_type` - The type of entity to operate on.
///
/// # Returns
/// A `Result` indicating success (`Ok(())`) or the encountered `AppError`.
pub fn handle_entity_commands(
    entity_sub_commands: &EntitySubCommands,
    e_type: &EntityType,
) -> Result<(), AppError> {
    let mut main_epoch = EpochConfig::new_from_path(None)?;
    match entity_sub_commands {
        EntitySubCommands::Add(entity_args) => {
            handle_create_entity(entity_args, e_type, &mut main_epoch)
        }
        EntitySubCommands::Del(entity_args) => {
            handle_delete_entity(entity_args, e_type, &mut main_epoch)
        }
        EntitySubCommands::Edit(entity_args) => {
            handle_edit_entity(entity_args, e_type, &mut main_epoch)
        }
        EntitySubCommands::Find(entity_args) => {
            handle_find_entity(entity_args, e_type, &mut main_epoch)
        }
        EntitySubCommands::Show(entity_args) => {
            handle_show_entity(entity_args, e_type, &mut main_epoch)
        }
        EntitySubCommands::Diff(entity_args) => {
            handle_diff_entity(entity_args, e_type, &mut main_epoch)
        }
    }?;
    Ok(())
}

/// Function handler for the create subcommand
fn handle_create_entity(
    entity_args: &EntityArgs,
    e_type: &EntityType,
    main_epoch: &mut EpochConfig,
) -> Result<(), EpochError> {
    let epoch_info = main_epoch.try_load_current_as_mut()?;

    if find_entity(entity_args, e_type, epoch_info).is_ok() {
        Err(EpochError::EntityAlreadyExist(
            entity_args.identifier.clone(),
        ))?;
    };

    let vec_entities: &mut Vec<Entity> = vec_entities_mut(e_type, epoch_info);

    let mut entity = Entity::create_rng(e_type, &entity_args.rng)?;
    update_stats(entity_args, &mut entity);
    // Specifying a name means the name needs to be changed
    // Specifying an id however means nothing and should be ignored

    update_defaults(entity_args, &mut entity);

    info!("Created character: {:#?}", entity);
    entity.print_full();
    let message = &crate::success::SuccessMessages::CreatedEntity(
        entity.name.clone(),
        entity.entity_type.to_shortest(),
        entity.id.to_string(),
    );
    vec_entities.push(entity);

    // No need to change main epoch that didn't change a serialized field
    epoch_info.save_with_context("Created entity", &lib_efo::epoch::SaveMode::Erase)?;
    display_success(message);

    Ok(())
}

/// Function handler for the delete subcommand
fn handle_delete_entity(
    entity_args: &EntityArgs,
    e_type: &EntityType,
    main_epoch: &mut EpochConfig,
) -> Result<(), EpochError> {
    let epoch_info = main_epoch.try_load_current_as_mut()?;

    let vec_entities: &mut Vec<Entity> = vec_entities_mut(e_type, epoch_info);
    let index = vec_entities
        .iter()
        .position(|e| find_by_args(e, entity_args))
        .ok_or(EpochError::EntityNotFound(
            e_type.clone(),
            entity_args.identifier.clone(),
        ))?;

    let entity = vec_entities.swap_remove(index);

    epoch_info.save_with_context("Deleted entity", &lib_efo::epoch::SaveMode::Erase)?;
    display_success(&crate::success::SuccessMessages::DeletedEntity(
        entity.name,
        entity.entity_type.to_shortest(),
        entity.id.to_string(),
    ));
    Ok(())
}

/// Function handler for the diff subcommand
fn handle_diff_entity(
    entity_args: &EntityArgs,
    e_type: &EntityType,
    main_epoch: &mut EpochConfig,
) -> Result<(), EpochError> {
    // Load the epochs to diff
    let id = main_epoch.epoch_id;
    let id2 = main_epoch.epoch_id.add_to_epoch(-1);
    main_epoch.try_load(&id)?;
    main_epoch.try_load(&id2)?;

    let epoch_current = unsafe { main_epoch.try_load_id(id) }?;
    let epoch_past = unsafe { main_epoch.try_load_id(id2) }?;
    let current_entity = find_entity(entity_args, e_type, epoch_current)?;
    let past_entity = find_entity(entity_args, e_type, epoch_past)?;

    let diff = current_entity.delta(past_entity);
    display_success(&crate::success::SuccessMessages::DiffBetweenEpoch(id, id2));
    diff.print_full();

    Ok(())
}

/// Function handler for the show subcommand
// TODO: Add filters else this will become very clustered
fn handle_show_entity(
    entity_args: &EntityArgs,
    e_type: &EntityType,
    main_epoch: &mut EpochConfig,
) -> Result<(), EpochError> {
    let epoch_info = main_epoch.try_load_current()?;
    if entity_args.identifier.is_none() {
        for entity in vec_entities(e_type, epoch_info) {
            entity.print_oneline();
        }
    } else {
        let entity = find_entity(entity_args, e_type, epoch_info)?;
        entity.print_full();
    }
    Ok(())
}

/// Function handler for the find subcommand
fn handle_find_entity(
    entity_args: &EntityArgs,
    e_type: &EntityType,
    main_epoch: &mut EpochConfig,
) -> Result<(), EpochError> {
    handle_show_entity(entity_args, e_type, main_epoch)
}

/// Function handler for the edit subcommand
fn handle_edit_entity(
    entity_args: &EntityArgs,
    e_type: &EntityType,
    main_epoch: &mut EpochConfig,
) -> Result<(), EpochError> {
    let epoch_info = main_epoch.try_load_current_as_mut()?;
    let vec_entities = vec_entities_mut(e_type, epoch_info);
    let entity = vec_entities
        .iter_mut()
        .find(|e| find_by_args(e, entity_args))
        .ok_or(EpochError::EntityNotFound(
            e_type.clone(),
            entity_args.identifier.clone(),
        ))?;

    for stat in &entity_args.stats {
        entity.change_stat(stat.clone());
    }
    if let Some(duration) = &entity_args.duration {
        entity.modify_duration(duration.clone());
    }
    // // Only update the name if an id was given
    // if entity_args.id.is_some()
    //     && let Some(name) = &entity_args.name
    // {
    //     entity.name = name.clone();
    // }
    if let Some(effect) = &entity_args.effect {
        entity.modify_effect_application(effect.clone());
    }
    if let Some(bounds) = &entity_args.bounds {
        entity.modify_effect_bounds(bounds.clone());
    }

    entity.print_full();
    let message = &crate::success::SuccessMessages::EditedEntity(
        entity.name.clone(),
        entity.entity_type.to_shortest(),
        entity.id.to_string(),
    );
    epoch_info.save_with_context("Deleted entity", &lib_efo::epoch::SaveMode::Erase)?;

    display_success(message);
    Ok(())
}

/// Update the given stats with the given argumenbts
/// Note that this function will not change name & id due to the usage variance between caller
fn update_stats(entity_args: &EntityArgs, e: &mut Entity) {
    if entity_args.delta {
        for stat in &entity_args.stats {
            e.delta_stat(stat.clone());
        }
    } else {
        for stat in &entity_args.stats {
            e.change_stat(stat.clone());
        }
    }
}

/// Looks up an entity inside the given `epoch_info` according to the
/// supplied arguments.
///
/// The function returns a reference to the matching entity or an
/// `EpochError::EntityNotFound` if no entity matches.
///
/// # Arguments
/// * `entity_args` - The arguments that identify the entity.
/// * `e_type` - The type of entity to look for.
/// * `epoch_info` - The epoch that contains all entities.
///
/// # Returns
/// * `Ok(&Entity)` - The entity that matches the arguments.
/// * `Err(EpochError::EntityNotFound)` - No matching entity was found.
fn find_entity<'a>(
    entity_args: &'a EntityArgs,
    e_type: &'a EntityType,
    epoch_info: &'a lib_efo::epoch::EpochInfo,
) -> Result<&'a Entity, EpochError> {
    vec_entities(e_type, epoch_info)
        .iter()
        .find(|&e| find_by_args(e, entity_args))
        .ok_or(EpochError::EntityNotFound(
            e_type.clone(),
            entity_args.identifier.clone(),
        ))
}

/// Returns a slice over the entities of the requested type from the given `EpochInfo`.
///
/// The function matches the supplied `e_type` to the appropriate collection
/// inside `epoch_info`. For unimplemented entity types the call will panic
/// because of the `todo!()` placeholder.
///
/// # Arguments
/// * `e_type` - The type of entities to retrieve.
/// * `epoch_info` - The epoch information containing the collections.
///
/// # Returns
/// A reference to the vector containing the requested entities.  
/// The lifetime of the returned slice is tied to that of `epoch_info`.
#[inline]
fn vec_entities<'a>(
    e_type: &'a EntityType,
    epoch_info: &'a lib_efo::epoch::EpochInfo,
) -> &'a Vec<Entity> {
    match e_type {
        EntityType::Character => &epoch_info.characters,
        EntityType::Player => todo!(),
        EntityType::Town => &epoch_info.towns,
        EntityType::Monster => &epoch_info.calamities,
        EntityType::Blocker => &epoch_info.blockers,
        EntityType::Event => &epoch_info.events,
    }
}

#[inline]
/// Returns a mutable slice over the entities of the requested type from the given
/// `EpochInfo`.
///
/// Like `vec_entities`, this function selects the appropriate collection
/// based on `e_type`. Unimplemented variants will panic due to the `todo!()`.
///
/// # Arguments
/// * `e_type` - The type of entities to retrieve.
/// * `epoch_info` - The epoch information containing the collections.
///
/// # Returns
/// A mutable reference to the vector containing the requested entities.  
/// The lifetime of the returned slice is tied to that of `epoch_info`.
fn vec_entities_mut<'a>(
    e_type: &'a EntityType,
    epoch_info: &'a mut lib_efo::epoch::EpochInfo,
) -> &'a mut Vec<Entity> {
    match e_type {
        EntityType::Character => &mut epoch_info.characters,
        EntityType::Player => todo!(),
        EntityType::Town => &mut epoch_info.towns,
        EntityType::Monster => &mut epoch_info.calamities,
        EntityType::Blocker => &mut epoch_info.blockers,
        EntityType::Event => &mut epoch_info.events,
    }
}

/// Helper function finding by name, note that a lot more helpers could be done to find by other criterias
fn find_by_args(entity: &Entity, entity_args: &EntityArgs) -> bool {
    match entity_args.identifier {
        Some(EntityIdentifier::Name(ref name)) => entity.name.starts_with(name),
        Some(EntityIdentifier::Id(ref id)) => entity.id.hyphenated().to_string().starts_with(id),
        None => false,
    }
}

/// Find an entity matching a tag
#[allow(dead_code)]
fn find_by_id<'a>(entities: &'a [Entity], id: &'a String) -> Option<&'a Entity> {
    entities
        .iter()
        .find(|e| e.id.hyphenated().to_string().starts_with(id))
}

/// Find an entity matching a name
#[allow(dead_code)]
fn find_by_name<'a>(entities: &'a [Entity], id: &'a String) -> Option<&'a Entity> {
    entities.iter().find(|e| e.name.starts_with(id))
}

/// Update the default values of the entity with sensible defaults
fn update_defaults(entity_args: &EntityArgs, e: &mut Entity) {
    let entity_type = &e.entity_type;

    let (duration, effect, bounds, name) = match entity_type {
        EntityType::Character => (
            lib_efo::entity::EntityDuration::Permanent,
            lib_efo::entity::EffectApplication::WhenPresent,
            EffectBounds { min: 20, max: 110 },
            NAMING.generate_character_name(),
        ),
        EntityType::Player => (
            lib_efo::entity::EntityDuration::Permanent,
            lib_efo::entity::EffectApplication::WhenPresent,
            EffectBounds { min: 0, max: 120 },
            NAMING.generate_exotic_character_name(),
        ),
        EntityType::Town => (
            lib_efo::entity::EntityDuration::Permanent,
            lib_efo::entity::EffectApplication::WhenPresent,
            EffectBounds { min: 20, max: 60 },
            NAMING.generate_town_name(),
        ),
        EntityType::Monster => (
            lib_efo::entity::EntityDuration::Permanent,
            lib_efo::entity::EffectApplication::WhenPresent,
            EffectBounds { min: 20, max: 80 },
            NAMING.generate_calamity_name(),
        ),
        EntityType::Blocker => (
            lib_efo::entity::EntityDuration::Permanent,
            lib_efo::entity::EffectApplication::WhenPresent,
            EffectBounds { min: 0, max: 120 },
            NAMING.generate_blocker_name(),
        ),
        EntityType::Event => (
            lib_efo::entity::EntityDuration::Duration(1),
            lib_efo::entity::EffectApplication::PermanentEffectToApply,
            EffectBounds { min: 10, max: 80 },
            NAMING.random_event_name(),
        ),
    };
    // This is the sensible default for all creatures & characters
    if let Some(duration) = &entity_args.duration {
        e.modify_duration(duration.clone());
    } else {
        e.modify_duration(duration);
    }

    if let Some(EntityIdentifier::Name(name)) = &entity_args.identifier {
        e.name = name.clone()
    } else {
        e.name = name
    }

    // This is the sensible default for all creatures & characters
    if let Some(effect) = &entity_args.effect {
        e.modify_effect_application(effect.clone());
    } else {
        e.modify_effect_application(effect);
    }

    // This is the sensible default for characters
    if let Some(bounds) = &entity_args.bounds {
        e.modify_effect_bounds(bounds.clone());
    } else {
        e.modify_effect_bounds(bounds);
    }
}