app(doc): well... write the docs

This commit is contained in:
Schrottkatze 2024-01-19 09:51:48 +01:00
parent 7f935c0baa
commit f65ae990d7
Signed by: schrottkatze
GPG key ID: DFD0FD205943C14A
5 changed files with 25 additions and 6 deletions

View file

@ -14,6 +14,7 @@ pub struct Config {
} }
impl Config { impl Config {
/// Get the configs from all possible places (args, file, env...)
pub fn read() -> Self { pub fn read() -> Self {
let args = Args::parse(); let args = Args::parse();
let config_path = if let Some(config_path) = args.config_path { let config_path = if let Some(config_path) = args.config_path {
@ -22,6 +23,7 @@ impl Config {
find_config_file() find_config_file()
}; };
// try to read a maybe existing config file
let file_config = if let Ok(config_path) = config_path { let file_config = if let Ok(config_path) = config_path {
let file_config = Configs::read(config_path); let file_config = Configs::read(config_path);
@ -52,13 +54,22 @@ impl Config {
} }
pub mod error { pub mod error {
/// Errors that can occur when reading configs
#[derive(Debug)] #[derive(Debug)]
pub enum ConfigError { pub enum ConfigError {
/// The config dir doesn't exist
NoConfigDir, NoConfigDir,
/// We didn't find a config file in the config dir
NoConfigFileFound, NoConfigFileFound,
/// An io error happened while reading/opening it!
IoError(std::io::Error), IoError(std::io::Error),
/// The given extension (via an argument) isn't known.
///
/// Occurs if the extension is neither `.json` nor `.ron` (including if there is no extension, in which case this will be `None`).
UnknownExtension(Option<String>), UnknownExtension(Option<String>),
/// Wrapper around an `Error` from `serde_json`
SerdeJsonError(serde_json::Error), SerdeJsonError(serde_json::Error),
/// Wrapper around a `SpannedError` from `ron`
SerdeRonError(ron::error::SpannedError), SerdeRonError(ron::error::SpannedError),
} }

View file

@ -7,6 +7,9 @@ pub(crate) struct Args {
/// Read this config file. /// Read this config file.
#[arg(short, long)] #[arg(short, long)]
pub config_path: Option<PathBuf>, pub config_path: Option<PathBuf>,
/// Turn off the startup message.
///
/// The startup message is not constant and depends on the time.
#[arg(long, env = "NO_STARTUP_MESSAGE", default_value = "false")] #[arg(long, env = "NO_STARTUP_MESSAGE", default_value = "false")]
pub no_startup_message: bool, pub no_startup_message: bool,
} }

View file

@ -11,7 +11,7 @@ use super::error::ConfigError;
pub struct Configs { pub struct Configs {
#[serde(default = "default_example_value")] #[serde(default = "default_example_value")]
pub example_value: i32, pub example_value: i32,
#[serde(default = "default_no_startup_msg")] #[serde(default)]
pub no_startup_message: bool, pub no_startup_message: bool,
} }
@ -20,10 +20,7 @@ fn default_example_value() -> i32 {
43 43
} }
fn default_no_startup_msg() -> bool { /// Find the location of a config file and check if there is, in fact, a file
false
}
pub(super) fn find_config_file() -> Result<PathBuf, ConfigError> { pub(super) fn find_config_file() -> Result<PathBuf, ConfigError> {
let Some(config_path) = dirs::config_dir() else { let Some(config_path) = dirs::config_dir() else {
return Err(ConfigError::NoConfigDir); return Err(ConfigError::NoConfigDir);

View file

@ -2,16 +2,19 @@ use std::process;
use ron::error::Position; use ron::error::Position;
/// Report an `Error` from the `serde_json` crate
pub fn report_serde_json_err(src: &str, err: serde_json::Error) -> ! { pub fn report_serde_json_err(src: &str, err: serde_json::Error) -> ! {
report_serde_err(src, err.line(), err.column(), err.to_string()) report_serde_err(src, err.line(), err.column(), err.to_string())
} }
/// Report a `SpannedError` from the `ron` crate
pub fn report_serde_ron_err(src: &str, err: ron::error::SpannedError) -> ! { pub fn report_serde_ron_err(src: &str, err: ron::error::SpannedError) -> ! {
let Position { line, col } = err.position; let Position { line, col } = err.position;
report_serde_err(src, line, col, err.to_string()) report_serde_err(src, line, col, err.to_string())
} }
pub fn report_serde_err(src: &str, line: usize, col: usize, msg: String) -> ! { /// Basic function for reporting serde type of errors
fn report_serde_err(src: &str, line: usize, col: usize, msg: String) -> ! {
use ariadne::{Label, Report, Source}; use ariadne::{Label, Report, Source};
let offset = try_reconstruct_loc(src, line, col); let offset = try_reconstruct_loc(src, line, col);
@ -24,6 +27,8 @@ pub fn report_serde_err(src: &str, line: usize, col: usize, msg: String) -> ! {
.unwrap(); .unwrap();
process::exit(1); process::exit(1);
} }
/// Reconstruct a byte offset from the line + column numbers typical from serde crates
fn try_reconstruct_loc(src: &str, line_nr: usize, col_nr: usize) -> usize { fn try_reconstruct_loc(src: &str, line_nr: usize, col_nr: usize) -> usize {
let (line_nr, col_nr) = (line_nr - 1, col_nr - 1); let (line_nr, col_nr) = (line_nr - 1, col_nr - 1);

View file

@ -1,11 +1,14 @@
use time::{Month, OffsetDateTime}; use time::{Month, OffsetDateTime};
/// Print the startup message which changes depending on system time.
pub fn print_startup_msg() { pub fn print_startup_msg() {
// now or fallback to utc // now or fallback to utc
let now = OffsetDateTime::now_local().unwrap_or_else(|_| OffsetDateTime::now_utc()); let now = OffsetDateTime::now_local().unwrap_or_else(|_| OffsetDateTime::now_utc());
if now.month() == Month::June { if now.month() == Month::June {
// pride startup message
println!("Hello, thanks for using iOwO and happy pride month!"); println!("Hello, thanks for using iOwO and happy pride month!");
// TODO: proper link with explaination
println!("Why pride month is important in {}", now.year()); println!("Why pride month is important in {}", now.year());
} else { } else {
println!("Hello, thanks for using iOwO! :3"); println!("Hello, thanks for using iOwO! :3");