From 18cc6cd48e946ba99d2a9156bc71a924ae082977 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Fri, 3 May 2024 15:06:30 +0200 Subject: [PATCH] Adds Documentation --- src/main.rs | 11 +++++++++++ src/tablegen.rs | 45 +++++++++++++++++++++++++++++++++++++-------- 2 files changed, 48 insertions(+), 8 deletions(-) diff --git a/src/main.rs b/src/main.rs index 2378a37..f3e5b67 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,10 @@ +//! The `ravenous-tool` command-line tool. +//! +//! This program is meant as a helper for the ravenous project. +//! + +#![warn(missing_docs)] +#![warn(clippy::missing_docs_in_private_items)] mod tablegen; use clap::{Parser, Subcommand}; use tablegen::{table_gen, TableArgs}; @@ -5,13 +12,17 @@ use tablegen::{table_gen, TableArgs}; #[derive(Parser, Debug)] #[command(version, about)] #[command(propagate_version = true)] +/// The list of commands to run struct Arguments { + /// The subcommand to run. #[command(subcommand)] command: Commands, } #[derive(Subcommand, Debug)] +/// Enum representing the available commands. enum Commands { + /// Generate a table from input data using the provided arguments. Tablegen(TableArgs), } diff --git a/src/tablegen.rs b/src/tablegen.rs index 274246c..b5a381b 100644 --- a/src/tablegen.rs +++ b/src/tablegen.rs @@ -2,24 +2,38 @@ use clap::Args; use serde::Deserialize; use std::io::{Error, Write}; +use std::path::Path; use std::{cell::RefCell, fmt, fs::File, io::BufWriter}; +/// Configuration options for processing CSV files and generating LaTeX tables. #[derive(Debug, Args)] pub struct TableArgs { + /// A boolean indicating whether to generate LaTeX code and write it to an output file + /// (if true) or just print the generated code to stdout #[arg(short)] export: bool, - // #[arg(short)] + + // #[arg(shorl, long)] + // type: + /// A vector of strings representing the names of CSV files to process. filenames: Vec, } #[derive(Debug, Deserialize)] #[serde(rename_all = "PascalCase")] +/// A single row in a martial class csv file struct Record { + /// The name of a technique. technique: String, + /// The level or rank of a technique niveau: String, + /// The type of technique, such as Actif or Exclusif. technique_type: String, + /// The blood cost for this technique. cout_blood: CleanString, + /// The gauge cost for this technique. cout_jauge: CleanString, + /// A brief description of the effect or outcome of using this technique. effet: CleanString, } @@ -33,6 +47,11 @@ pub fn table_gen(args: &TableArgs) { } } } +/// Converts a CSV file to LaTeX code. +/// +/// This function reads in a CSV file, processes its contents according to the provided configuration, +/// and writes out the resulting LaTeX code as a string. If an error occurs during processing or writing, +/// it will be returned as part of the result. pub fn convert_file(f: &String, args: &TableArgs) -> Result<(), Error> { let csv = read_csv(f)?; let converted = records_to_string(csv)?; @@ -48,6 +67,7 @@ pub fn convert_file(f: &String, args: &TableArgs) -> Result<(), Error> { Ok(()) } +/// This type is used to represent strings in LaTeX tables, where certain characters need to be escaped or replaced with special commands. #[derive(Deserialize)] struct CleanString(String); @@ -57,14 +77,16 @@ impl fmt::Debug for CleanString { ::fmt(&self.0, f) } } + impl fmt::Display for CleanString { #[inline] fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - f.write_str(&replace_all(&self.0)) + f.write_str(&make_latex_string(&self.0)) } } -fn replace_all(arg: &str) -> String { +/// Replace all instances of unrepresentable utf8 or non escaped characters with latex ones +fn make_latex_string(arg: &str) -> String { use regex::{Captures, Regex}; let re = Regex::new(r"★+").unwrap(); @@ -79,7 +101,14 @@ fn replace_all(arg: &str) -> String { res.to_string() } -fn read_csv(filename: &String) -> Result>, Error> { +/// Reads a CSV file into a table. +/// +/// This function reads in a comma-separated values (CSV) file and returns it as a Table object, +/// which can be used to generate LaTeX code or perform other operations on the data. +fn read_csv(filename: &T) -> Result>, Error> +where + T: AsRef, +{ let file = File::open(filename)?; let mut rdr = csv::ReaderBuilder::new() .has_headers(false) @@ -108,11 +137,11 @@ fn read_csv(filename: &String) -> Result>, Error> { Ok(levels) } +/// Converts a table of data into a string representation. +/// +/// This function takes in a Table object and returns its contents as a formatted string, +/// which can be used to generate LaTeX code or perform other operations on the data. fn records_to_string(csv: Vec>) -> Result { - // FUREUR SANGUINAIRE & 1 & Actif, (Guivre) & 6\blood & Sacrifiez 3 points de vie dans toutes les localités, vous gagnez l'altération Rage, vos attaques infligent une réussite supplémentaire tant que vous êtes enragé.\\ - // FUREUR SANGUINAIRE & 2 & Actif, Exclusif, (Guivre) & 5\blood 1\gauge & Sacrifiez 4 points de vie a la place, vous gagnez 2 dégâts supplémentaires sur chaque attaque tant que vous êtes enragé. Lorsque vous perdez l'altération d'état enragé, regagnez 1\gauge.\\ - // EXSANGUINATION PROGRESSIVE & 1 & Actif, (Béhémoth) & 3\blood\vfill 1\gauge & Votre prochaine attaque marque la cible en son point d'impact, toutes les attaques ciblant cette marque ignorent jusqu'à 4 points d'armure ce tour-ci.\\ - // EXSANGUINATION PROGRESSIVE & 1 & Actif, (Béhémoth) & 4\blood\vfill 1\gauge & Ces attaques infligent aussi un saignement de 1 dégât sur 4 tours (chaque attaque viens ajouter un point au saignement total).\\ let mut buffer = BufWriter::new(Vec::new()); for (lvl, tier) in csv.iter().skip(1).enumerate() { write!(buffer, "\\subsubsection{{Tier {}}}", lvl + 1)?;