From 32fb29c2ce97002715383492295959ad0b7dc8e2 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Fri, 27 Aug 2021 10:00:14 +0200 Subject: Add documentation to repository::fs module Signed-off-by: Matthias Beyer --- src/repository/fs.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/src/repository/fs.rs b/src/repository/fs.rs index ce5531c..df3ade8 100644 --- a/src/repository/fs.rs +++ b/src/repository/fs.rs @@ -17,6 +17,10 @@ use resiter::Filter; use resiter::Map; use resiter::AndThen; +/// A type representing the filesystem +/// +/// This type can be used to load pkg.toml files from the filesystem. As soon as this object is +/// loaded, all filesystem access is done and postprocessing of the loaded data can happen #[derive(Debug, getset::Getters)] pub struct FileSystemRepresentation { #[getset(get = "pub")] @@ -28,6 +32,9 @@ pub struct FileSystemRepresentation { elements: HashMap, } +/// One element in the tree inside FileSystemRepresentation +/// +/// This is either a File, or a Directory that contains more (Files or Directories). #[derive(Debug)] enum Element { File(String), @@ -35,6 +42,7 @@ enum Element { } impl Element { + /// Helper fn to get the directory contents of the element, if the element is an Element::Dir fn get_map_mut(&mut self) -> Option<&mut HashMap> { match self { Element::File(_) => None, @@ -43,6 +51,18 @@ impl Element { } } +/// Helper type for filtering for pathes we need or dont need +/// +/// We either have a directory, which has a name, or we have a pkg.toml file, which is of interest. +/// All other files can be ignored and thus are not represented by this type. +/// +/// The PathComponent::DirName(_) represents a _part_ of a Path. Something like +/// +/// ```ignore +/// let p = PathBuf::from("foo/bar/baz") +/// p.components().map(PathComponent::DirName) // does not actually work because of types +/// ``` +/// #[derive(Debug, Clone, PartialEq, Eq, Hash)] enum PathComponent { PkgToml, @@ -71,10 +91,13 @@ impl TryFrom<&std::path::Component<'_>> for PathComponent { } impl PathComponent { + /// Helper fn whether this PathComponent is a PathComponent::PkgToml fn is_pkg_toml(&self) -> bool { std::matches!(self, PathComponent::PkgToml) } + /// Helper fn to get the directory name of this PathComponent if it is a PathComponent::DirName + /// or None if it is not. fn dir_name(&self) -> Option<&str> { match self { PathComponent::PkgToml => None, @@ -85,6 +108,7 @@ impl PathComponent { impl FileSystemRepresentation { + /// Load the FileSystemRepresentation object starting a `root`. pub fn load(root: PathBuf) -> Result { let mut fsr = FileSystemRepresentation { root: root.clone(), @@ -92,6 +116,7 @@ impl FileSystemRepresentation { files: vec![], }; + // get the number of maximum files open (ulimit -n on linux) let max_files_open = { let (soft, _hard) = rlimit::getrlimit(rlimit::Resource::NOFILE)?; @@ -144,9 +169,23 @@ impl FileSystemRepresentation { Ok(fsr) } + /// Check the tree whether a `Path` points to a file in a directory that does not contain more + /// directories containing pkg.toml files. + /// + /// # Example + /// + /// / + /// /foo/ + /// /foo/pkg.toml <-- is leaf + /// /bar/ + /// /bar/pkg.toml <-- is not a leaf + /// /bar/baz/pkg.toml <-- is a leaf + /// + /// pub fn is_leaf_file(&self, path: &Path) -> Result { let mut curr_hm = &self.elements; + // Helper to check whether a tree contains pkg.toml files, recursively fn toml_files_in_tree(hm: &HashMap) -> bool { for value in hm.values() { match value { @@ -179,6 +218,17 @@ impl FileSystemRepresentation { Ok(false) } + /// Get a Vec<(PathBuf, &String)> for the `path` + /// + /// The result of this function is the trail of pkg.toml files from `self.root` to `path`, + /// whereas the PathBuf is the actual path to the file and the `&String` is the content of the + /// individual file. + /// + /// Merging all Strings in the returned Vec as Config objects should produce a Package. to + /// `path`, whereas the PathBuf is the actual path to the file and the `&String` is the content + /// of the individual file. + /// + /// Merging all Strings in the returned Vec as Config objects should produce a Package. pub fn get_files_for<'a>(&'a self, path: &Path) -> Result> { let mut res = Vec::with_capacity(10); // good enough @@ -209,21 +259,25 @@ impl FileSystemRepresentation { } } +/// Helper to check whether a DirEntry points to a hidden file fn is_hidden(entry: &DirEntry) -> bool { log::trace!("Check {:?} is hidden", entry); entry.file_name().to_str().map(|s| s.starts_with(".")).unwrap_or(false) } +/// Helper to check whether a DirEntry points to a directory fn is_dir(entry: &DirEntry) -> bool { log::trace!("Check {:?} is directory", entry); entry.file_type().is_dir() } +/// Helper to check whether a DirEntry points to a pkg.toml file fn is_pkgtoml(entry: &DirEntry) -> bool { log::trace!("Check {:?} == 'pkg.toml'", entry); entry.file_name().to_str().map(|s| s == "pkg.toml").unwrap_or(false) } +/// Helper fn to load a Path into memory as String fn load_file(path: &Path) -> Result { log::trace!("Reading {}", path.display()); std::fs::read_to_string(path) -- cgit v1.2.3