diff --git a/src/dialogs.rs b/src/dialogs.rs index 4f4d7b2..ce18102 100644 --- a/src/dialogs.rs +++ b/src/dialogs.rs @@ -12,15 +12,22 @@ use crate::utils::colors; /// Represents a confirmation dialog pub struct Confirmation<'a> { + /// Represents the message to the displayed + /// e.g.: "Do you want to overwrite 'FILE'?" pub prompt: &'a str, + + /// Represents a placeholder to be changed at runtime + /// e.g.: Some("FILE") pub placeholder: Option<&'a str>, } impl<'a> Confirmation<'a> { + /// New Confirmation pub const fn new(prompt: &'a str, pattern: Option<&'a str>) -> Self { Self { prompt, placeholder: pattern } } + /// Creates user message and receives a boolean input to be used on the program pub fn ask(&self, substitute: Option<&'a str>) -> crate::Result { let message = match (self.placeholder, substitute) { (None, _) => Cow::Borrowed(self.prompt), diff --git a/src/extension.rs b/src/extension.rs index b1828f0..8ef479c 100644 --- a/src/extension.rs +++ b/src/extension.rs @@ -4,6 +4,7 @@ use std::{ffi::OsStr, fmt, path::Path}; use self::CompressionFormat::*; +#[allow(missing_docs)] #[derive(Clone, PartialEq, Eq, Debug)] /// Accepted extensions for input and output pub enum CompressionFormat { @@ -40,6 +41,19 @@ impl fmt::Display for CompressionFormat { } } +// use crate::extension::CompressionFormat::*; +// + +/// Extracts extensions from a path, +/// return both the remaining path and the list of extension objects +/// +/// ```rust +/// use ouch::extension::{separate_known_extensions_from_name, CompressionFormat}; +/// use std::path::Path; +/// +/// let mut path = Path::new("bolovo.tar.gz"); +/// assert_eq!(separate_known_extensions_from_name(&path), (Path::new("bolovo"), vec![CompressionFormat::Tar, CompressionFormat::Gzip])); +/// ``` pub fn separate_known_extensions_from_name(mut path: &Path) -> (&Path, Vec) { // // TODO: check for file names with the name of an extension // // TODO2: warn the user that currently .tar.gz is a .gz file named .tar @@ -76,6 +90,15 @@ pub fn separate_known_extensions_from_name(mut path: &Path) -> (&Path, Vec Vec { let (_, extensions) = separate_known_extensions_from_name(path); extensions diff --git a/src/lib.rs b/src/lib.rs index 3edee45..24394b2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -10,13 +10,11 @@ pub mod archive; pub mod cli; pub mod commands; - -// Private modules -mod dialogs; -mod error; -mod extension; -mod macros; -mod utils; +pub mod dialogs; +pub mod error; +pub mod extension; +pub mod macros; +pub mod utils; pub use error::{Error, Result}; diff --git a/src/macros.rs b/src/macros.rs index c570831..4a16e8c 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -1,3 +1,5 @@ +//! Macros used on ouch. + #[macro_export] /// Macro that prints message in INFO mode macro_rules! info { @@ -7,6 +9,7 @@ macro_rules! info { }; } +/// Prints the `[Info]` tag pub fn _info_helper() { use crate::utils::colors::{RESET, YELLOW}; diff --git a/src/utils.rs b/src/utils.rs index 7c3a0e7..d407533 100644 --- a/src/utils.rs +++ b/src/utils.rs @@ -1,3 +1,5 @@ +//! Utils used on ouch. + use std::{ cmp, env, ffi::OsStr, @@ -15,6 +17,7 @@ pub fn dir_is_empty(dir_path: &Path) -> bool { dir_path.read_dir().map(is_empty).unwrap_or_default() } +/// Creates the dir if non existent. pub fn create_dir_if_non_existent(path: &Path) -> crate::Result<()> { if !path.exists() { fs::create_dir_all(path)?; @@ -23,6 +26,9 @@ pub fn create_dir_if_non_existent(path: &Path) -> crate::Result<()> { Ok(()) } +/// Removes the current dir from the beginning of a path +/// normally used for presentation sake. +/// If this function fails, it will return source path as a PathBuf. pub fn strip_cur_dir(source_path: &Path) -> PathBuf { source_path .strip_prefix(Component::CurDir) @@ -43,6 +49,8 @@ pub fn cd_into_same_dir_as(filename: &Path) -> crate::Result { Ok(previous_location) } +/// Centralizes the decision of overwriting a file or not, +/// whether the user has already passed a question_policy or not. pub fn user_wants_to_overwrite(path: &Path, question_policy: QuestionPolicy) -> crate::Result { match question_policy { QuestionPolicy::AlwaysYes => Ok(true), @@ -56,11 +64,13 @@ pub fn user_wants_to_overwrite(path: &Path, question_policy: QuestionPolicy) -> } } +/// Converts an OsStr to utf8. pub fn to_utf(os_str: impl AsRef) -> String { let text = format!("{:?}", os_str.as_ref()); text.trim_matches('"').to_string() } +/// Treats weird paths for better user messages. pub fn nice_directory_display(os_str: impl AsRef) -> String { let text = to_utf(os_str); if text == "." { @@ -70,6 +80,7 @@ pub fn nice_directory_display(os_str: impl AsRef) -> String { } } +/// Struct used to overload functionality onto Byte presentation. pub struct Bytes { bytes: f64, } @@ -86,6 +97,7 @@ pub mod colors { macro_rules! color { ($name:ident = $value:literal) => { #[cfg(target_family = "unix")] + /// Inserts color onto text based on configuration pub static $name: Lazy<&str> = Lazy::new(|| if *DISABLE_COLORED_TEXT { "" } else { $value }); #[cfg(not(target_family = "unix"))] pub static $name: &&str = &""; @@ -106,6 +118,7 @@ pub mod colors { impl Bytes { const UNIT_PREFIXES: [&'static str; 6] = ["", "k", "M", "G", "T", "P"]; + /// New Byte structure pub fn new(bytes: u64) -> Self { Self { bytes: bytes as f64 } } @@ -129,7 +142,7 @@ impl std::fmt::Display for Bytes { #[derive(Debug, PartialEq, Clone, Copy)] /// How overwrite questions should be handled pub enum QuestionPolicy { - /// Ask ever time + /// Ask everytime Ask, /// Skip overwrite questions positively AlwaysYes,