From 5e7afce019325226c7515fe9cb462dda2685f7a3 Mon Sep 17 00:00:00 2001 From: mo8it Date: Wed, 1 May 2024 19:47:35 +0200 Subject: [PATCH] Document dev --- src/dev.rs | 3 +-- src/dev/check.rs | 15 ++++++++++----- src/dev/new.rs | 31 ++++++++++++++++--------------- src/dev/update.rs | 5 +++-- 4 files changed, 30 insertions(+), 24 deletions(-) diff --git a/src/dev.rs b/src/dev.rs index 107d4376..fada8b33 100644 --- a/src/dev.rs +++ b/src/dev.rs @@ -1,7 +1,6 @@ -use std::path::PathBuf; - use anyhow::{bail, Context, Result}; use clap::Subcommand; +use std::path::PathBuf; use crate::DEBUG_PROFILE; diff --git a/src/dev/check.rs b/src/dev/check.rs index 143037c0..81d05ce6 100644 --- a/src/dev/check.rs +++ b/src/dev/check.rs @@ -12,10 +12,12 @@ use crate::{ CURRENT_FORMAT_VERSION, DEBUG_PROFILE, }; +// Find a char that isn't allowed in the exercise's `name` or `dir`. fn forbidden_char(input: &str) -> Option { input.chars().find(|c| *c != '_' && !c.is_alphanumeric()) } +// Check the info of all exercises and return their paths in a set. fn check_info_file_exercises(info_file: &InfoFile) -> Result> { let mut names = hashbrown::HashSet::with_capacity(info_file.exercises.len()); let mut paths = hashbrown::HashSet::with_capacity(info_file.exercises.len()); @@ -72,11 +74,12 @@ fn check_info_file_exercises(info_file: &InfoFile) -> Result Error { - anyhow!("Found the file `{}`. Only `README.md` and Rust files related to an exercise in `info.toml` are allowed in the `exercises` directory", path.display()) -} +// Check the `exercises` directory for unexpected files. +fn check_unexpected_files(info_file_paths: &hashbrown::HashSet) -> Result<()> { + fn unexpected_file(path: &Path) -> Error { + anyhow!("Found the file `{}`. Only `README.md` and Rust files related to an exercise in `info.toml` are allowed in the `exercises` directory", path.display()) + } -fn check_exercise_dir_files(info_file_paths: &hashbrown::HashSet) -> Result<()> { for entry in read_dir("exercises").context("Failed to open the `exercises` directory")? { let entry = entry.context("Failed to read the `exercises` directory")?; @@ -128,11 +131,12 @@ fn check_exercises(info_file: &InfoFile) -> Result<()> { } let info_file_paths = check_info_file_exercises(info_file)?; - check_exercise_dir_files(&info_file_paths)?; + check_unexpected_files(&info_file_paths)?; Ok(()) } +// Check that the Cargo.toml file is up-to-date. fn check_cargo_toml( exercise_infos: &[ExerciseInfo], current_cargo_toml: &str, @@ -159,6 +163,7 @@ pub fn check() -> Result<()> { let info_file = InfoFile::parse()?; check_exercises(&info_file)?; + // A hack to make `cargo run -- dev check` work when developing Rustlings. if DEBUG_PROFILE { check_cargo_toml( &info_file.exercises, diff --git a/src/dev/new.rs b/src/dev/new.rs index 44487abf..fefc4fc1 100644 --- a/src/dev/new.rs +++ b/src/dev/new.rs @@ -8,6 +8,7 @@ use std::{ use crate::CURRENT_FORMAT_VERSION; +// Create a directory relative to the current directory and print its path. fn create_rel_dir(dir_name: &str, current_dir: &str) -> Result<()> { create_dir(dir_name) .with_context(|| format!("Failed to create the directory {current_dir}/{dir_name}"))?; @@ -15,6 +16,7 @@ fn create_rel_dir(dir_name: &str, current_dir: &str) -> Result<()> { Ok(()) } +// Write a file relative to the current directory and print its path. fn write_rel_file(file_name: &str, current_dir: &str, content: C) -> Result<()> where C: AsRef<[u8]>, @@ -27,13 +29,13 @@ where } pub fn new(path: &Path, no_git: bool) -> Result<()> { - let dir_name = path.to_string_lossy(); + let dir_path_str = path.to_string_lossy(); - create_dir(path).with_context(|| format!("Failed to create the directory {dir_name}"))?; - println!("Created the directory {dir_name}"); + create_dir(path).with_context(|| format!("Failed to create the directory {dir_path_str}"))?; + println!("Created the directory {dir_path_str}"); set_current_dir(path) - .with_context(|| format!("Failed to set {dir_name} as the current directory"))?; + .with_context(|| format!("Failed to set {dir_path_str} as the current directory"))?; if !no_git && !Command::new("git") @@ -42,28 +44,28 @@ pub fn new(path: &Path, no_git: bool) -> Result<()> { .context("Failed to run `git init`")? .success() { - bail!("`git init` didn't run successfully. See the error message above"); + bail!("`git init` didn't run successfully. See the possible error message above"); } - write_rel_file(".gitignore", &dir_name, GITIGNORE)?; + write_rel_file(".gitignore", &dir_path_str, GITIGNORE)?; - create_rel_dir("exercises", &dir_name)?; - create_rel_dir("solutions", &dir_name)?; + create_rel_dir("exercises", &dir_path_str)?; + create_rel_dir("solutions", &dir_path_str)?; write_rel_file( "info.toml", - &dir_name, + &dir_path_str, format!("{INFO_FILE_BEFORE_FORMAT_VERSION}{CURRENT_FORMAT_VERSION}{INFO_FILE_AFTER_FORMAT_VERSION}"), )?; - write_rel_file("Cargo.toml", &dir_name, CARGO_TOML)?; + write_rel_file("Cargo.toml", &dir_path_str, CARGO_TOML)?; - write_rel_file("README.md", &dir_name, README)?; + write_rel_file("README.md", &dir_path_str, README)?; - create_rel_dir(".vscode", &dir_name)?; + create_rel_dir(".vscode", &dir_path_str)?; write_rel_file( ".vscode/extensions.json", - &dir_name, + &dir_path_str, crate::init::VS_CODE_EXTENSIONS_JSON, )?; @@ -137,8 +139,7 @@ const README: &str = "# Rustlings 🦀 Welcome to these third-party Rustlings exercises 😃 -First, -[install Rustlings using the official instructions in the README of the Rustlings project](https://github.com/rust-lang/rustlings) ✅ +First, [install Rustlings using the official instructions in the README of the Rustlings project](https://github.com/rust-lang/rustlings) ✅ Then, open your terminal in this directory and run `rustlings` to get started with the exercises 🚀 "; diff --git a/src/dev/update.rs b/src/dev/update.rs index fe7622c0..66efe3d0 100644 --- a/src/dev/update.rs +++ b/src/dev/update.rs @@ -1,6 +1,5 @@ -use std::fs; - use anyhow::{Context, Result}; +use std::fs; use crate::{ cargo_toml::updated_cargo_toml, @@ -8,6 +7,7 @@ use crate::{ DEBUG_PROFILE, }; +// Update the `Cargo.toml` file. fn update_cargo_toml( exercise_infos: &[ExerciseInfo], current_cargo_toml: &str, @@ -26,6 +26,7 @@ fn update_cargo_toml( pub fn update() -> Result<()> { let info_file = InfoFile::parse()?; + // A hack to make `cargo run -- dev update` work when developing Rustlings. if DEBUG_PROFILE { update_cargo_toml( &info_file.exercises,