refactoring tmc-langs-util

Author: Heliozoa

tmc-langs-core/README.md

@@ -0,0 +1 @@
+Used for communicating with the TMC server.

tmc-langs-core/src/error.rs

@@ -49,14 +49,14 @@ pub enum CoreError {
     #[error("Failed to find cache directory")]
     CacheDir,
 
-    #[error(transparent)]
-    TmcLangs(#[from] tmc_langs_util::TmcError),
     #[error(transparent)]
     Response(#[from] response::ResponseError),
     #[error(transparent)]
     ResponseErrors(#[from] response::ResponseErrors),
     #[error(transparent)]
     WalkDir(#[from] walkdir::Error),
+    #[error(transparent)]
+    Tmc(#[from] tmc_langs_util::error::UtilError),
 }
 
 impl From<TokenError> for CoreError {

tmc-langs-framework/src/domain.rs

@@ -2,12 +2,13 @@
 
 pub mod meta_syntax;
 
-use super::{Result, TmcError};
+use super::Result;
+use crate::io::file_util;
+
 use log::debug;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use std::collections::{HashMap, HashSet};
-use std::fs::File;
 use std::path::{Path, PathBuf};
 
 /// A description of an exercise's test case.
@@ -157,7 +158,7 @@ impl TmcProjectYml {
             return Ok(Self::default());
         }
         debug!("reading .tmcproject.yml from {}", config_path.display());
-        let file = File::open(&config_path).map_err(|e| TmcError::OpenFile(config_path, e))?;
+        let file = file_util::open_file(&config_path)?;
         Ok(serde_yaml::from_reader(file)?)
     }
 }

tmc-langs-framework/src/domain/meta_syntax.rs

@@ -1,13 +1,12 @@
-//! Contains utilities for parsing text files, separating lines into
-//! strings, stubs and solutions so that they can be more easily filtered accordingly
+//! Contains utilities for parsing annotated exercise source files, separating lines into
+//! strings, stubs and solutions so that they can be more easily filtered later.
 
 use crate::{Result, TmcError};
 use lazy_static::lazy_static;
-use log::debug;
 use regex::{Captures, Regex};
 use std::io::{BufRead, BufReader, Read};
 
-// Meta syntaxes for each comment syntax
+// rules for finding comments in various languages
 lazy_static! {
     static ref META_SYNTAXES_C: [MetaSyntax; 2] = [
         MetaSyntax::new("//", None),
@@ -17,7 +16,7 @@ lazy_static! {
     static ref META_SYNTAXES_PY: [MetaSyntax; 1] = [MetaSyntax::new("#", None)];
 }
 
-// Used to classify lines of code based on the annotations in the file
+/// Used to classify lines of code based on the annotations in the file.
 #[derive(Debug, PartialEq, Eq)]
 pub enum MetaString {
     String(String),
@@ -26,7 +25,6 @@ pub enum MetaString {
 }
 
 impl MetaString {
-    // Borrows the underlying line of text
     pub fn as_str(&self) -> &str {
         match self {
             Self::String(s) => &s,
@@ -36,7 +34,7 @@ impl MetaString {
     }
 }
 
-// Contains the needed regexes for a given comment syntax
+/// Contains the needed regexes for a given comment syntax.
 #[derive(Debug)]
 struct MetaSyntax {
     solution_file: Regex,
@@ -48,11 +46,14 @@ struct MetaSyntax {
 
 impl MetaSyntax {
     fn new(comment_start: &'static str, comment_end: Option<&'static str>) -> Self {
+        // comment patterns
         let comment_start_pattern = format!("^(\\s*){}\\s*", comment_start);
         let comment_end_pattern = match comment_end {
             Some(s) => format!("(.*){}\\s*", s),
             None => "(.*)".to_string(),
         };
+
+        // annotation patterns
         let solution_file = Regex::new(&format!(
             "{}SOLUTION\\s+FILE{}",
             comment_start_pattern, comment_end_pattern
@@ -81,7 +82,7 @@ impl MetaSyntax {
     }
 }
 
-/// Parses a given text file into an iterator of `MetaString`s
+/// Parses a given text file into an iterator of `MetaString`s.
 #[derive(Debug)]
 pub struct MetaSyntaxParser<B: BufRead> {
     meta_syntaxes: &'static [MetaSyntax],
@@ -95,13 +96,14 @@ pub struct MetaSyntaxParser<B: BufRead> {
 impl<R: Read> MetaSyntaxParser<BufReader<R>> {
     pub fn new(target: R, target_extension: &str) -> Self {
         let reader = BufReader::new(target);
-        // Assigns each supported file extension with the proper comment syntax
+        // assigns each supported file extension with the proper comment syntax
         let meta_syntaxes: &[MetaSyntax] = match target_extension {
             "java" | "c" | "cpp" | "h" | "hpp" | "js" | "css" | "rs" | "qml" => &*META_SYNTAXES_C,
             "xml" | "http" | "html" | "qrc" => &*META_SYNTAXES_HTML,
             "properties" | "py" | "R" | "pro" => &*META_SYNTAXES_PY,
             _ => &[],
         };
+
         Self {
             meta_syntaxes,
             reader,
@@ -125,37 +127,39 @@ impl<B: BufRead> Iterator for MetaSyntaxParser<B> {
                 for meta_syntax in self.meta_syntaxes {
                     // check for stub
                     if self.in_stub.is_none() && meta_syntax.stub_begin.is_match(&s) {
-                        debug!("stub start: '{}'", s);
+                        log::debug!("stub start: '{}'", s);
                         // save the syntax that started the current stub
                         self.in_stub = Some(meta_syntax);
                         // remove stub start
                         s = meta_syntax
                             .stub_begin
                             .replace(&s, |caps: &Captures| caps[1].to_string())
                             .to_string();
-                        debug!("parsed: '{}'", s);
+                        log::debug!("parsed: '{}'", s);
                         if s.trim().is_empty() {
                             // only metadata, skip
                             return self.next();
                         }
                     }
                     // if the line matches stub_end and the saved syntax matches
-                    // the start of the current meta syntax
+                    // the start of the current meta syntax, return stub contents if any
                     if meta_syntax.stub_end.is_match(&s)
                         && self.in_stub.map(|r| r.stub_begin.as_str())
                             == Some(meta_syntax.stub_begin.as_str())
                     {
-                        debug!("stub end: '{}'", s);
+                        log::debug!("stub end: '{}'", s);
                         self.in_stub = None;
+                        // remove stub end
                         s = meta_syntax
                             .stub_end
                             .replace(&s, |caps: &Captures| caps[1].to_string())
                             .to_string();
-                        debug!("parsed: '{}'", s);
+                        log::debug!("parsed: '{}'", s);
                         if s.trim().is_empty() {
                             // only metadata, skip
                             return self.next();
                         }
+                        // return the stub contents
                         return Some(Ok(MetaString::Stub(s)));
                     }
 
@@ -173,13 +177,13 @@ impl<B: BufRead> Iterator for MetaSyntaxParser<B> {
                 // after processing the line with each meta syntax,
                 // parse the current line accordingly
                 if self.in_solution {
-                    debug!("solution: '{}'", s);
+                    log::debug!("solution: '{}'", s);
                     Some(Ok(MetaString::Solution(s)))
                 } else if self.in_stub.is_some() {
-                    debug!("stub: '{}'", s);
+                    log::debug!("stub: '{}'", s);
                     Some(Ok(MetaString::Stub(s)))
                 } else {
-                    debug!("string: '{}'", s);
+                    log::debug!("string: '{}'", s);
                     Some(Ok(MetaString::String(s)))
                 }
             }

tmc-langs-framework/src/error.rs

@@ -7,36 +7,22 @@ use thiserror::Error;
 #[derive(Error, Debug)]
 pub enum TmcError {
     // IO
-    #[error("Failed to open file at {0}")]
-    OpenFile(PathBuf, #[source] std::io::Error),
-    #[error("Failed to create file at {0}")]
-    CreateFile(PathBuf, #[source] std::io::Error),
-    #[error("Failed to remove file at {0}")]
-    RemoveFile(PathBuf, #[source] std::io::Error),
-    #[error("Failed to create dir(s) at {0}")]
-    CreateDir(PathBuf, #[source] std::io::Error),
-    #[error("Failed to remove dir at {0}")]
-    RemoveDir(PathBuf, #[source] std::io::Error),
-    #[error("Failed to create temporary directory")]
-    TempDir(#[source] std::io::Error),
-    #[error("Failed to rename {0} to {1}")]
-    Rename(PathBuf, PathBuf, #[source] std::io::Error),
-    #[error("Failed to write to {0}")]
-    Write(PathBuf, #[source] std::io::Error),
-    #[error("Failed to read zip archive at {0}")]
+    #[error("File IO error")]
+    FileIo(#[from] FileIo),
+    #[error("{0} exists and is not a directory")]
+    UnexpectedFile(PathBuf),
+
+    #[error("Failed to read file inside zip archive with path {0}")]
     ZipRead(PathBuf, #[source] std::io::Error),
+    #[error("Failed to write file at {0} to zip archive")]
+    ZipWrite(PathBuf, #[source] std::io::Error),
+
     #[error("Error appending to tar")]
     TarAppend(#[source] std::io::Error),
     #[error("Error finishing tar")]
     TarFinish(#[source] std::io::Error),
     #[error("Failed to read line")]
     ReadLine(#[source] std::io::Error),
-    #[error("Failed to copy file from {0} to {1}")]
-    FileCopy(PathBuf, PathBuf, #[source] std::io::Error),
-    #[error("Failed to open file at {0}")]
-    FileOpen(PathBuf, #[source] std::io::Error),
-    #[error("Failed to read file at {0}")]
-    FileRead(PathBuf, #[source] std::io::Error),
     #[error("Failed to canonicalize path {0}")]
     Canonicalize(PathBuf, #[source] std::io::Error),
     #[error("Error occurred in a child process")]
@@ -80,10 +66,53 @@ pub enum TmcError {
 }
 
 // == Collection of errors likely to be useful in multiple plugins which can be special cased without needing a plugin's specific error type ==
+/// An error caused by a failed attempt to execute an external command.
 #[derive(Error, Debug)]
 #[error("The executable for \"{name}\" could not be found ({path}). Please make sure you have installed it correctly.")]
 pub struct CommandNotFound {
     pub name: &'static str,
     pub path: PathBuf,
     pub source: std::io::Error,
 }
+
+#[derive(Error, Debug)]
+pub enum FileIo {
+    #[error("Failed to open file at {0}")]
+    FileOpen(PathBuf, #[source] std::io::Error),
+    #[error("Failed to read file at {0}")]
+    FileRead(PathBuf, #[source] std::io::Error),
+    #[error("Failed to write file at {0}")]
+    FileWrite(PathBuf, #[source] std::io::Error),
+    #[error("Failed to create file at {0}")]
+    FileCreate(PathBuf, #[source] std::io::Error),
+    #[error("Failed to remove file at {0}")]
+    FileRemove(PathBuf, #[source] std::io::Error),
+    #[error("Failed to copy file from {from} to {to}")]
+    FileCopy {
+        from: PathBuf,
+        to: PathBuf,
+        source: std::io::Error,
+    },
+    #[error("Failed to move file from {from} to {to}")]
+    FileMove {
+        from: PathBuf,
+        to: PathBuf,
+        source: std::io::Error,
+    },
+
+    #[error("Failed to open directory at {0}")]
+    DirOpen(PathBuf, #[source] std::io::Error),
+    #[error("Failed to read directory at {0}")]
+    DirRead(PathBuf, #[source] std::io::Error),
+    #[error("Failed to create directory at {0}")]
+    DirCreate(PathBuf, #[source] std::io::Error),
+    #[error("Failed to remove directory at {0}")]
+    DirRemove(PathBuf, #[source] std::io::Error),
+
+    #[error("Failed to rename file {from} to {to}")]
+    Rename {
+        from: PathBuf,
+        to: PathBuf,
+        source: std::io::Error,
+    },
+}