From ec4c930bfcf5da675e058e5227b4462997c54aa5 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sat, 13 Dec 2025 19:49:21 +0100 Subject: [PATCH] Adds documentation, updates the CI --- .ignore | 1 + Jenkinsfile | 11 +- README.md | 124 ++++++++++++------ bin_efo/src/commands.rs | 2 +- .../commands/{chr.rs => entity_generic.rs} | 65 ++++++++- bin_efo/src/commands/epoch.rs | 49 ++++++- bin_efo/src/commands/generate.rs | 91 ++++++++++++- bin_efo/src/commands/init.rs | 23 +++- bin_efo/src/main.rs | 54 ++++---- lib_efo/src/entity/implementations.rs | 2 +- lib_efo/src/epoch.rs | 2 +- lib_efo/src/epoch/epoch_config.rs | 8 +- lib_efo/src/epoch/epoch_info.rs | 2 +- lib_efo/src/error.rs | 4 +- lib_efo/src/lib.rs | 11 -- lib_efo/src/stats.rs | 8 +- 16 files changed, 360 insertions(+), 97 deletions(-) create mode 100644 .ignore rename bin_efo/src/commands/{chr.rs => entity_generic.rs} (83%) diff --git a/.ignore b/.ignore new file mode 100644 index 0000000..bd01d04 --- /dev/null +++ b/.ignore @@ -0,0 +1 @@ +snapshots diff --git a/Jenkinsfile b/Jenkinsfile index 6d40fcd..bf197c1 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -7,7 +7,8 @@ pipeline { ================== */ environment { - DEPLOY_DIR = "/mnt/books/" // Important, all books are in /mnt/book + DEPLOY_DIR = "/mnt/books/rust_doc/efo/" // Important, all books are in /mnt/book + MDBOOK_BUILD_DIR = "target/doc/" } stages { @@ -33,8 +34,16 @@ pipeline { script { if (env.BRANCH_NAME == 'origin/review' || env.BRANCH_NAME == 'review' || env.BRANCH_NAME == 'origin/dev-ci' || env.BRANCH_NAME == 'dev-ci') { sh 'cargo test' + sh 'cargo doc' + sh 'echo "Deploying to ${DEPLOY_DIR}"' + sh 'mkdir -p ${DEPLOY_DIR}' + sh 'rsync -a --delete ${MDBOOK_BUILD_DIR}/ ${DEPLOY_DIR}' } else if (env.BRANCH_NAME == 'origin/master' || env.BRANCH_NAME == 'master') { sh 'cargo test' + sh 'cargo doc' + sh 'echo "Deploying to ${DEPLOY_DIR}"' + sh 'mkdir -p ${DEPLOY_DIR}' + sh 'rsync -a --delete ${MDBOOK_BUILD_DIR}/ ${DEPLOY_DIR}' } else { echo "Unknown branch: ${env.BRANCH_NAME} - skipping build." } diff --git a/README.md b/README.md index 8bf7e8d..8ab393f 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,115 @@ -# 📦 Epoch Forge (`epoch_forge`) +# 📦 Epoch Forge (`epoch_forge`) – *early alpha* ![code coverage](badges/coverage.svg) ![version](badges/version.svg) ![code coverage](badges/test.svg) +![📚 Online Documentation](https://books.dandaedre.com/rust_doc/efo/bin_efo/index.html) + > **A Rust-powered CLI for managing fantasy organisations across time.** > *Think of it as a living, breathing world-state engine that lets you “rewind”, “fast-forward”, and **alter** the history of guilds, towns, wars, and characters.* -> 🚀 *Fast, type-safe, and fully testable.* +> **Epoch Forge** is a Rust‑powered command‑line tool that lets you build and manipulate a living fantasy world. +> It is **in early alpha** – the API is subject to change, some features are missing, and stability is **not guaranteed**. +> **Stats & analytics are not yet implemented** – most commands operate only on the raw data model. ## ✨ Quick start ```bash -# clone the repo +# Clone the repository git clone https://github.com/yourname/epoch_forge.git cd epoch_forge -# install the binary +# Build & install the binary cargo install --path . -# initialise an empty world (epoch 0) -efo epoch --init +# Initialise an empty world (epoch 0) +efo init -# add a guild -efo org add --name "The Iron Horde" --leader "Gorun" +# Add an organisation +efo org add "The Iron Horde" -# add a town -efo town add --name "Durn" --population 350 +# Add a town +efo town add "Durn" --stat pop:32 -# create an alliance -efo link add --type alliance --org "Iron Horde" --town "Durn" - -# advance the timeline -efo epoch --advance 3 - -# inspect the world +# Inspect the current world state +efo show > world.json cat world.json + +# Show the epoch timeline +efo epoch log + +# Create the next scheduled epoch +efo epoch next + +# Switch back to epoch 5 (if it exists) +efo epoch switch 5 + +# Tag the current epoch +efo epoch tag milestone1 + +# Add a short-lived event +efo event add "Storm" \ + --duration Duration(1) \ + --effect permanent-effect-to-apply \ + --stats damage=20 ``` -## 🏆 Project Highlights +> **Tip:** The `show` command can print JSON, which you can pipe to `jq` or any other tooling. -| Feature | What it gives you | Where it lives | -|---------|------------------|----------------| -| **Epoch management** | Switch, advance, or rewind the timeline | `core::epoch` | -| **Event handling** | Add/remove world-shaping events (storms, festivals, wars) | `core::event` | -| **Organisation CRUD** | Guilds, factions, corporations | `core::org` | -| **Character CRUD** | Heroes, villains, NPCs | `core::character` | -| **Town CRUD** | Villages, cities, trade hubs | `core::town` | +## 🏆 Project Highlights + +| Feature | Description | Where to find it | +|---------|-------------|-----------------| +| **Epoch management** | Switch, advance, or rewind the global timeline | `core::epoch` | +| **Persistence** | JSON/YAML stores, pluggable back-ends | `core::epoch` | +| **Event handling** | Add/remove world-shaping events (storms, festivals, wars) | `core::entities` | +| **Organisation CRUD** | Guilds, factions, corporations | `core::entities` | +| **Character CRUD** | Heroes, villains, NPCs | `core::entities` | +| **Town CRUD** | Villages, cities, trade hubs | `core::entities` | | **Link network** | Alliances, wars, roads, trade routes | `core::link` | -| **Persistence** | JSON/YAML stores, pluggable back-ends | `core::storage` | | **CLI** | `efo` binary with sub-commands | `efo` crate | -| **Tests** | Unit & integration coverage | `tests/` | +> *Statistics, analytics, and the `act` feature are still a work in progress.* -### 📃 Quick reference table +## Unimplemented / WIP -| Sub-command | Usage | What it changes | -|-------------|-------|-----------------| -| `epoch` | `efo epoch --init`
`efo epoch --advance N`
`efo epoch --target ID` | Creates a world; moves time forward or back. | -| `event` | `efo event add ...`
`efo event remove ...` | Adds or removes an event. | -| `org` | `efo org add ...`
`efo org remove ...` | Manages guilds/factions. | -| `chr` | `efo chr add ...`
`efo chr remove ...` | Handles characters. | -| `town` | `efo town add ...`
`efo town remove ...` | Town CRUD. | -| `link` | `efo link add ...`
`efo link remove ...` | Relations: alliances, wars, roads, trade. | +| Feature | Status | Where it lives | +|---------|--------|----------------| +| **Act** | Planned, not yet implemented | `core::act` | +| **Stats** | Missing – no aggregated data | – | + +## Quick reference table + +| Sub‑command | Usage example | What it changes | +|-------------|---------------|-----------------| +| **`init`** | `efo init`
`efo init --force` | Creates an empty epoch repository (epoch 0) in the current directory. | +| **`epoch log`** | `efo epoch log --limit 20` | Prints a chronological list of epochs up to the current one. | +| **`epoch switch`** | `efo epoch switch 5` | Sets the current epoch to the specified `` (must already exist). | +| **`epoch next`** | `efo epoch next` | Generates the next scheduled epoch and inserts it. | +| **`epoch reset`** | `efo epoch reset` | Deletes all epochs with an identifier greater than the current one. | +| **`epoch diff`** | `efo epoch diff 2 4` | *Unimplemented* – placeholder for future diffing logic. | +| **`epoch tag`** | `efo epoch tag milestone1` | Adds a unique tag to the current epoch, updating the global tag map. | +| **`epoch fsck`** | `efo epoch fsck` | *Unimplemented* – intended to run a consistency check. | +| **`epoch summary`** | `efo epoch summary "Reached the new frontier"` | Replaces the `summary` field of the current epoch with ``. | +| **`show`** | `efo show` | Prints the current world state (JSON). | +| **`gen`** | `efo gen character -n 5 --short`
`efo gen town -n 2`
`efo gen event -n 3 --name` | Prints generated names/ideas; useful for scripting. | +| **`chr add`** | `efo chr add "Aria" --pos 5,12 --stats strength=12 agility=9` | Creates a new entity (character, town, event, etc.) and writes the epoch. | +| **`chr del`** | `efo chr del "Aria"` | Removes the matching entity from the epoch. | +| **`chr edit`** | `efo chr edit "Storm" --duration Duration(2)` | Modifies an existing entity’s stats, position, duration, etc. | +| **`chr find`** | `efo chr find "Aria"` | Prints full details of a single entity. | +| **`chr show`** | `efo chr show` | Lists all entities, or `efo chr show "Aria"` shows one in full detail. | +| **`chr diff`** | `efo chr diff "Aria"` | Prints the difference between the current and previous epoch for that entity. | +| **`event add` / `event remove`** | `efo event add ...`
`efo event remove ...` | Adds or removes an event. | +| **`org add` / `org remove`** | `efo org add ...`
`efo org remove ...` | Manages organisations (guilds, factions). | +| **`town add` / `town remove`** | `efo town add ...`
`efo town remove ...` | CRUD for towns. | +| **`monster add` / `monster remove`** | `efo monster add ...`
`efo monster remove ...` | CRUD for monsters. | +| **`act`** | *Not yet implemented* | Planned for future action handling. | + +> All changes are persisted immediately to the epoch file after the command finishes. + +## Contributions & Feedback + +Because the project is in early alpha, any feedback, bug reports, or pull requests are welcome. +Please remember that **stability is not guaranteed**, so use it in a versionned environnement. + +Happy forging! ✨ -Happy forging! 🔨✨ diff --git a/bin_efo/src/commands.rs b/bin_efo/src/commands.rs index 2786614..bfdc0da 100644 --- a/bin_efo/src/commands.rs +++ b/bin_efo/src/commands.rs @@ -8,7 +8,7 @@ #![warn(missing_docs, clippy::missing_docs_in_private_items)] -pub mod chr; +pub mod entity_generic; pub mod epoch; pub mod generate; pub mod init; diff --git a/bin_efo/src/commands/chr.rs b/bin_efo/src/commands/entity_generic.rs similarity index 83% rename from bin_efo/src/commands/chr.rs rename to bin_efo/src/commands/entity_generic.rs index d34e841..6f4dcfe 100644 --- a/bin_efo/src/commands/chr.rs +++ b/bin_efo/src/commands/entity_generic.rs @@ -1,4 +1,66 @@ -//! Module handling the creation of characters +//! ## 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** | ` add [OPTIONS] [IDENTIFIER]` | Creates a new ``, pushes it to the epoch’s list, and writes the epoch. | +//! | **del** | ` del ` | Removes the matching `` from the list and writes the epoch. | +//! | **edit** | ` edit [OPTIONS]` | Modifies the stats/position/duration/effect/bounds of the chosen `` and writes the epoch. | +//! | **find** | ` find ` | Prints full details of a single ``. | +//! | **show** | ` show []` | Lists all entities on one line, or shows one `` in full detail. | +//! | **diff** | ` diff ` | Prints the difference between the current and previous epoch for that ``. | +//! +//! *`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 ` | How to fill unspecified stats.
Possible values: `zero`, `low`, `med`, `high`, `legendary`, `mixed`, `flawed`. Default: `zero`. | +//! | `--pos-exact ` / `--pos ` | Place the new entity at a specific `x,y` coordinate (the epoch must be in a map context). | +//! | `--duration ` | Lifespan of the entity (e.g. `Permanent`, `Temporary`, `Duration(1)` for a one‑turn event). | +//! | `--bounds ` | Effect limits, given as `min,max` (e.g. `10,80`). | +//! | `--effect ` | How the effect is applied:
`recurring`, `when-present`, `permanent-effect-to-apply`, `permanent-effect-applied`. | +//! | `-s, --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** – ` 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}; @@ -80,6 +142,7 @@ pub struct EntityArgs { pub effect: Option, /// All stats pairs involved + #[arg(short, long)] pub stats: Vec, } diff --git a/bin_efo/src/commands/epoch.rs b/bin_efo/src/commands/epoch.rs index b426aea..ed7937c 100644 --- a/bin_efo/src/commands/epoch.rs +++ b/bin_efo/src/commands/epoch.rs @@ -1,7 +1,50 @@ //! # `epoch` sub-command //! -//! Handles all epoch-related logic - logging, switching, computing the -//! next epoch, and resetting future events. +//! The `epoch` sub‑command is the single entry point for all epoch‑related +//! operations in **efo**. +//! An *epoch* represents a point in the simulated world’s history. +//! The command lets you inspect, advance, modify and sanity‑check the epoch +//! timeline. +//! +//! ### Usage +//! +//! ```bash +//! # Show log of epochs (last 20 by default) +//! efo epoch log --limit 20 +//! +//! # Switch to an existing epoch +//! efo epoch switch 5 +//! +//! # Create the next epoch if none exist in the future +//! efo epoch next +//! +//! # Delete all future epochs, returning to the present +//! efo epoch reset +//! +//! # Add a unique tag to the current epoch +//! efo epoch tag milestone1 +//! +//! # Replace the current epoch’s summary +//! efo epoch summary "Reached the new frontier" +//! +//! # (Future) Check consistency +//! efo epoch fsck +//! ``` +//! +//! ### Summary +//! +//! | Sub‑command | Usage | What it changes | +//! |-------------|-------|-----------------| +//! | `log` | `efo epoch log [--limit N]` | Prints the chronological list of epochs up to the current one. | +//! | `switch` | `efo epoch switch ` | Sets the current epoch to the specified `` (must already exist). | +//! | `next` | `efo epoch next` | Generates the next scheduled epoch and inserts it. | +//! | `reset` | `efo epoch reset` | Deletes all epochs with an identifier greater than the current one. | +//! | `diff` | `efo epoch diff ` | *Unimplemented* – placeholder for future diffing logic. | +//! | `tag` | `efo epoch tag ` | Adds a unique tag to the current epoch, updating the global tag map. | +//! | `fsck` | `efo epoch fsck` | *Unimplemented* – intended to run a consistency check. | +//! | `summary` | `efo epoch summary ` | Replaces the `summary` field of the current epoch with ``. | +//! + #![warn(missing_docs, clippy::missing_docs_in_private_items)] use crate::{ @@ -40,7 +83,7 @@ pub mod cli_epoch; /// reported via the returned `Result`. pub fn handle_cmd(cmd: &cli_epoch::EpochCmd) -> Result<(), AppError> { let mut main_epoch = EpochConfig::new_from_path(None)?; - // // TODO[2]: Remove this debug + // TODO(2): Remove this debug debug!("The main epoch befor any action is {:#?}", main_epoch); match cmd { cli_epoch::EpochCmd::Log(args) => handle_log(args, &mut main_epoch), diff --git a/bin_efo/src/commands/generate.rs b/bin_efo/src/commands/generate.rs index dc37aee..a9046e5 100644 --- a/bin_efo/src/commands/generate.rs +++ b/bin_efo/src/commands/generate.rs @@ -1,20 +1,65 @@ //! # Generation Sub-command //! //! This module implements the `gen` sub-command used to quickly produce -//! sample data for the various generators in *lib_efo*. The command has no +//! sample data for the various generators in *lib_efo*. The command has no //! side-effects beyond printing the generated data; it is intended for //! interactive use or for embedding in scripts. //! //! ## Available sub-commands //! -//! * `character` - Generate character names (long or short). -//! * `event` - Generate event ideas. -//! * `town` - Generate town names. -//! * `exotic` - Generate exotic character names. +//! | Sub‑command | What it prints | Typical output | +//! |-------------|----------------|----------------| +//! | `character` | Character names (short or long) | `Eldric the Bold` | +//! | `event` | Random event ideas | `A mysterious fog descends over the town` | +//! | `town` | Town names | `Glimmerdale` | +//! | `exotic` | Exotic character names | `Zar‑nith the Wanderer` | +//! | `calamity` | Calamity names | `Great Plague of 1743` | +//! | `blocker` | Blocker names | `Stone Wall of the North` | //! -//! Each sub-command accepts a set of common options (see [`Qty`]) that -//! control how many items are produced and how they are displayed. +//! All sub‑commands share the same options: //! +//! * `-n / --number` – how many items to generate (default = 1) +//! * `--short` – print the short form when applicable (ignored for `event`, `exotic`, +//! `calamity`, `blocker`) +//! * `--name` – output only the name string, no extra formatting (good for scripting) +//! +//! # Usage +//! ```bash +//! # 3 long character names +//! gen character -n 3 +//! +//! # 1 short town name +//! gen town -n 1 --short +//! +//! # 5 event ideas, only the names +//! gen event -n 5 --name +//! +//! # A single exotic character name +//! gen exotic -n 1 +//! +//! # 2 calamity names +//! gen calamity -n 2 +//! +//! # 4 blocker names, short form +//! gen blocker -n 4 --short +//! ``` +//! +//! > **Tip** – redirect or pipe the output: +//! > `gen character -n 10 > chars.txt` +//! +//! --- +//! +//! # Summary +//! | Sub‑command | Usage example | What it does | +//! |-------------|---------------|-----------------| +//! | `character` | `gen character -n 5 --short` | Prints 5 short (or long if `--short` omitted) character names | +//! | `event` | `gen event -n 3 --name` | Prints 3 event names only | +//! | `town` | `gen town -n 2` | Prints 2 town names (short form by default) | +//! | `exotic` | `gen exotic -n 1` | Prints 1 exotic character name | +//! | `calamity` | `gen calamity -n 2` | Prints 2 calamity names | +//! | `blocker` | `gen blocker -n 4 --short` | Prints 4 blocker names (short form) | +//! +//! *All sub‑commands simply output the generated data; they do not alter any files or state.* use clap::{Args, Subcommand}; use lib_efo::{Displayable, error::EpochError, naming::NAMING}; @@ -33,6 +78,10 @@ pub enum GenCmd { Town(Qty), /// Exotic name Exotic(Qty), + /// Calamity + Calamity(Qty), + /// Blocker + Blocker(Qty), } #[derive(Args, Debug)] @@ -74,6 +123,34 @@ pub fn gen_handler(cmd: &GenCmd) -> Result<(), AppError> { GenCmd::Event(args) => handle_event(args)?, GenCmd::Town(args) => handle_town(args)?, GenCmd::Exotic(args) => handle_exotic(args)?, + GenCmd::Calamity(args) => handle_calamity(args)?, + GenCmd::Blocker(args) => handle_blocker(args)?, + } + Ok(()) +} + +/// Print a calamity name +fn handle_calamity(args: &Qty) -> Result<(), EpochError> { + for _ in 0..args.number { + let name = NAMING.generate_calamity_name(); + if args.name_only { + println!("{}", name); + } else { + unimplemented!("DEPENS ON : CHARACTER CREATION") + } + } + Ok(()) +} + +/// Print a blocker name +fn handle_blocker(args: &Qty) -> Result<(), EpochError> { + for _ in 0..args.number { + let name = NAMING.generate_blocker_name(); + if args.name_only { + println!("{}", name); + } else { + unimplemented!("DEPENS ON : CHARACTER CREATION") + } } Ok(()) } diff --git a/bin_efo/src/commands/init.rs b/bin_efo/src/commands/init.rs index f6bea46..2f9d759 100644 --- a/bin_efo/src/commands/init.rs +++ b/bin_efo/src/commands/init.rs @@ -8,6 +8,27 @@ //! The main public API consists of: //! //! * `InitCmd` - a struct containing the command-line arguments. +//! +//! ## Guide +//! +//! The `init` sub‑command bootstraps a new epoch repository: +//! +//! * It creates the default `.epoch` configuration file in the current directory. +//! * It creates an empty **epoch 0** folder (with its metadata file). +//! * It refuses to run if the target directory already contains files unless the user supplies `--force`. +//! +//! ### How to use +//! +//! ```bash +//! epoch init # normal init – directory must be empty +//! epoch init --force # skip the empty‑folder check +//! ``` +//! +//! ### Table Entry +//! +//! | Sub‑command | Usage | What it changes | +//! |-------------|-------|-----------------| +//! | `init` | `epoch init [--force]` | Initialize the current folder as an epoch folder | #![warn(missing_docs, clippy::missing_docs_in_private_items)] @@ -39,7 +60,7 @@ pub struct InitCmd { /// /// Creates the default `EpochConfig`, verifies that the target directory /// is empty, and writes the initial configuration and epoch data. -//TODO[5]: Upholster the logic behind force and empty detection +//TODO(5): Upholster the logic behind force and empty detection pub fn init(args: &InitCmd) -> Result<(), AppError> { let epoch_config = EpochConfig::default(); let root = epoch_config.save_folder(); diff --git a/bin_efo/src/main.rs b/bin_efo/src/main.rs index f656027..652a527 100644 --- a/bin_efo/src/main.rs +++ b/bin_efo/src/main.rs @@ -1,24 +1,25 @@ -//! # `efo` +//! # `epoch_forge` CLI //! -//! The **command-line interface** for `epoch_forge`. It exposes a single -//! binary `efo` that supports the following sub-commands: +//! The **command‑line interface** for `epoch_forge`. It exposes a single +//! binary `efo` that supports the following sub‑commands: //! -//! - `epoch` - switch / advance time -//! - `event` - add / remove events -//! - `org` - add / remove organisations -//! - `chr` - add / remove characters -//! - `town` - add / remove towns -//! - `link` - add / remove links (alliances, wars, roads, etc.) +//! ## Sub‑modules //! -//! Each sub-command is implemented in its own module under `commands/`. +//! * [`epoch`](crate::commands::epoch) - switch / advance time +//! * [`event`](crate::commands::entity_generic) - add / remove events +//! * [`org`](crate::commands::entity_generic) - add / remove organisations +//! * [`chr`](crate::commands::entity_generic) - add / remove characters +//! * [`town`](crate::commands::entity_generic) - add / remove towns +//! * [`blocker`](crate::commands::entity_generic) - add / remove blockers +//! * [`calamity`](crate::commands::entity_generic) - add / remove calamities +//! * [`link`](crate::commands::link) - add / remove links (alliances, wars, roads, etc.) +//! +//! Each sub‑command is implemented in its own module under `commands/`. //! The `main.rs` file simply parses arguments with `clap` and dispatches //! to the appropriate handler. The handlers share a common `World` //! instance that they load from / persist to disk. //! -//! ## Usage -//! ```sh -//! efo epoch switch 5 -//! ``` +//! Each module exposes a `handle` function that receives the parsed arguments #![warn(missing_docs, clippy::missing_docs_in_private_items)] #![deny(clippy::unwrap_used)] @@ -29,8 +30,8 @@ use clap::{ArgAction, Parser, Subcommand}; use crate::{ commands::{ - chr::EntitySubCommands, epoch::cli_epoch::EpochCmd, generate::GenCmd, init::InitCmd, - show::ShowCmd, + entity_generic::EntitySubCommands, epoch::cli_epoch::EpochCmd, generate::GenCmd, + init::InitCmd, show::ShowCmd, }, error::AppError, }; @@ -72,9 +73,13 @@ enum TopLevelCmd { /// Handle characters #[command(subcommand)] Chr(EntitySubCommands), - // Event(commands::event::EventCmd), - // Org(commands::org::OrgCmd), - // Town(commands::town::TownCmd), + /// Handle events + #[command(subcommand)] + Event(EntitySubCommands), + // #[command(subcommand)] + // Org(commands::org::OrgCmd), + // #[command(subcommand)] + // Town(commands::town::TownCmd), // Link(commands::link::LinkCmd), /// Generate random structures and display them #[command(subcommand)] @@ -117,8 +122,13 @@ fn exec_dispatch(cli: Cli) -> Result<(), AppError> { TopLevelCmd::Epoch(cmd) => commands::epoch::handle_cmd(&cmd), TopLevelCmd::Show(cmd) => commands::show::handle_show_cmd(&cmd), TopLevelCmd::Gen(cmd) => commands::generate::gen_handler(&cmd), - TopLevelCmd::Chr(cmd) => { - commands::chr::handle_entity_commands(&cmd, &lib_efo::stats::EntityType::Character) - } + TopLevelCmd::Chr(cmd) => commands::entity_generic::handle_entity_commands( + &cmd, + &lib_efo::stats::EntityType::Character, + ), + TopLevelCmd::Event(cmd) => commands::entity_generic::handle_entity_commands( + &cmd, + &lib_efo::stats::EntityType::Event, + ), } } diff --git a/lib_efo/src/entity/implementations.rs b/lib_efo/src/entity/implementations.rs index c87d3fd..99afaa1 100644 --- a/lib_efo/src/entity/implementations.rs +++ b/lib_efo/src/entity/implementations.rs @@ -23,7 +23,7 @@ impl Displayable for Entity { } } - /// One-liner used for auto-generation of Vec displays + /// One-liner used for auto-generation of `Vec` displays fn oneline_display(&self) -> String { let capital = self .metadata diff --git a/lib_efo/src/epoch.rs b/lib_efo/src/epoch.rs index d18f433..404bae4 100644 --- a/lib_efo/src/epoch.rs +++ b/lib_efo/src/epoch.rs @@ -35,7 +35,7 @@ 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 +// 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 diff --git a/lib_efo/src/epoch/epoch_config.rs b/lib_efo/src/epoch/epoch_config.rs index 8ffe7ab..5836979 100644 --- a/lib_efo/src/epoch/epoch_config.rs +++ b/lib_efo/src/epoch/epoch_config.rs @@ -45,7 +45,7 @@ pub struct EpochConfig { /// Optional human-friendly tags (e.g. `"winter-B"`, `"post-war"`). pub tags: HashMap, - // TODO[6]: Can become important + // TODO(6): Can become important // #[serde(skip)] // /// Absolute path to `epoch//`. // pub path: PathBuf, @@ -71,7 +71,7 @@ impl EpochConfig { let path = Path::new(MAIN_NAME); if path.is_file() { - // TODO[6]: write a trait for this + // TODO(6): write a trait for this let config: EpochConfig = serde_json::from_str(&io_err_with_help!( read_to_string(path), "Reading config from path {:?}", @@ -279,7 +279,7 @@ impl EpochConfig { /// The function removes the directory, deletes all references to the /// epoch from `list_existing_epochs` and `tags`, and then writes the /// updated configuration to disk. - // TODO[9]: Create a delete_ids taking an iterator for added performance on huge deletions + // TODO(9): Create a delete_ids taking an iterator for added performance on huge deletions pub fn delete_id(&mut self, id: EpochId) -> Result<(), EpochError> { if !self.list_existing_epochs.contains_key(&id) { warn!( @@ -306,7 +306,7 @@ impl EpochConfig { /// is deferred to the `EpochInfo -> World` subsystem. pub fn compute_next(&mut self) -> Result { // unimplemented!() - // TODO[1]: Implement this + // TODO(1): Implement this warn!("DEBUG LINE: COMPUTING NEXT EPOCH"); // New fake epoch let mut new_epoch = self.try_load_current()?.clone(); diff --git a/lib_efo/src/epoch/epoch_info.rs b/lib_efo/src/epoch/epoch_info.rs index cdbe376..bd37874 100644 --- a/lib_efo/src/epoch/epoch_info.rs +++ b/lib_efo/src/epoch/epoch_info.rs @@ -53,7 +53,7 @@ pub struct EpochInfo { /// Human-readable description or summary, useful for the `log` command. #[table(title = "Summary")] pub summary: String, - // TODO[9]: Store world separately + // TODO(9): Store world separately #[table(skip)] /// The list of events currently in progress pub events: Vec, diff --git a/lib_efo/src/error.rs b/lib_efo/src/error.rs index 440e444..fa0e869 100644 --- a/lib_efo/src/error.rs +++ b/lib_efo/src/error.rs @@ -22,7 +22,7 @@ use miette::Diagnostic; /// /// The variants are intentionally small - each one carries all the /// information required to surface a helpful message to the user. -// TODO[2]: Remove or rethink these errors +// TODO(2): Remove or rethink these errors #[derive(Debug, Error, Diagnostic)] pub enum StorageError { /// Problems with serialisation / deserialisation. @@ -47,7 +47,7 @@ pub enum StorageError { /// The enum is deliberately _small_ - each variant is self-contained and /// carries the information you need to surface a friendly message /// to the user (and to the test-suite). -// TODO[2]: Split effectively user errors to avoid the usage of advice and such +// TODO(2): Split effectively user errors to avoid the usage of advice and such #[derive(Error, Debug, Diagnostic)] #[allow(dead_code, unused_assignments)] pub enum EpochError { diff --git a/lib_efo/src/lib.rs b/lib_efo/src/lib.rs index 12aa6d0..4551e92 100644 --- a/lib_efo/src/lib.rs +++ b/lib_efo/src/lib.rs @@ -2,17 +2,6 @@ //! //! The **engine** that drives *Epoch Forge*. It contains a pure, representation of a fantasy world and all the logic needed to manipulate it. //! -//! The crate is split into the following domains, each exposed as a public module: -//! - TODO[1]: `world` - holds the global state (`World`) and a lightweight snapshot (`Context`). -//! - TODO[0]: `epoch` - manages the passage of time and epoch switching. -//! - TODO[1]: `event` - CRUD and evaluation of events that affect the world. -//! - TODO[4]: `org` - organisations, guilds, factions and their history. -//! - TODO[2]: `character` - individual characters, traits and lineage. -//! - TODO[1]: `town` - towns, cities, trade hubs and their populations. -//! - TODO[2]: `link` - relations such as wars, alliances, roads, commerce. -//! - TODO[3]: `storage` - generic persistence layer (`Store`) with JSON/YAML back-ends. -//! - TODO[4]: `util` - small helpers, ID generation, error types, etc. -//! //! All public types implement `serde::Serialize / Deserialize` so that they can //! be persisted easily. The `World` struct also offers a convenient //! `World::load()` / `World::save()` API that uses the default JSON file diff --git a/lib_efo/src/stats.rs b/lib_efo/src/stats.rs index 8b830f1..b1a5ee0 100644 --- a/lib_efo/src/stats.rs +++ b/lib_efo/src/stats.rs @@ -252,7 +252,7 @@ fn color_cell_categories(cell: CellStruct, value: &GenericStat) -> CellStruct { impl OverallStats { /// Create Stats with a given rng distribution - // TODO[6]: Use an iterator over the stat enum + // TODO(6): Use an iterator over the stat enum pub(crate) fn create_rng( rng: &RngLevel, mut rng_t: &mut ThreadRng, @@ -425,7 +425,7 @@ pub struct StatPair { pub struct Position(isize, isize); /// The grid size, as a static like a degenerate -// TODO[9]: Change to be at least initialized with the world ? +// TODO(9): Change to be at least initialized with the world ? const GRID_SIZE: (i32, i32) = (1920, 1080); /// The size the map is divided into const CHUNK_SIZE: isize = 200; @@ -443,7 +443,7 @@ impl Position { /// Create a random position /// None that there is no concept to either city or continent making this position rather unrelyable - // TODO[2]: Make a create_rng_from_town & create_rng_from_continents + // TODO(2): Make a create_rng_from_town & create_rng_from_continents pub fn create_rng(r: &mut ThreadRng) -> Result { let x = r.random_range(0..GRID_SIZE.0); let y = r.random_range(0..GRID_SIZE.1); @@ -551,7 +551,7 @@ thin_newtype!(FactionId, usize); /// 10-point range for “roll & UI” logic. The trait also exposes the /// underlying raw value and its visibility. /// -// TODO[7]: Change this with Deref+From +// TODO(7): Change this with Deref+From pub trait GameStat { /// Convert the raw integer to a 50-point scale. fn to_100(&self) -> isize {