asp/keep
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Improve Rustdoc for compression engine, delete mode, and parser modules

Browse Source 
Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) <aider@aider.chat>
This commit is contained in:
Andrew Phillips
2025-09-10 15:40:04 -03:00
parent 6a79f0455c
commit 9f7534f0ae
4 changed files with 162 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

151
src/compression_engine.rs
View File

@@ -22,7 +22,18 @@ use crate::compression_engine::lz4::CompressionEngineLZ4;
use crate::compression_engine::none::CompressionEngineNone;
use crate::compression_engine::program::CompressionEngineProgram;
/// Enum representing different compression types supported by the system
/// Enum representing different compression types supported by the system.
///
/// This enum defines all supported compression formats that can be used for
/// storing and retrieving compressed items. Each variant corresponds to a
/// specific compression algorithm or no compression.
///
/// # Examples
///
/// ```
/// use keep::compression_engine::CompressionType;
/// assert_eq!(CompressionType::GZip.to_string(), "gzip");
/// ```
#[derive(Debug, Eq, PartialEq, Clone, strum::EnumIter, strum::Display, strum::EnumString, Enum)]
#[strum(ascii_case_insensitive)]
pub enum CompressionType {
@@ -34,49 +45,90 @@ pub enum CompressionType {
None,
}
/// Trait defining the interface for compression engines
/// Trait defining the interface for compression engines.
///
/// This trait provides a unified API for different compression implementations.
/// Implementors handle reading from and writing to compressed files, as well as
/// utility operations like copying decompressed content or calculating sizes.
///
/// # Errors
///
/// Methods may return `anyhow::Error` for I/O failures, unsupported formats,
/// or invalid file paths.
///
/// # Examples
///
/// ```
/// // Example usage would depend on a concrete implementation
/// use keep::compression_engine::CompressionEngine;
/// let engine = /* some engine */;
/// let reader = engine.open("file.gz".into()).unwrap();
/// ```
pub trait CompressionEngine {
/// Opens a compressed file for reading
/// Opens a compressed file for reading.
///
/// Creates a reader that transparently decompresses the file contents as they are read.
///
/// # Arguments
///
/// * `file_path` - Path to the compressed file
/// * `file_path` - Path to the compressed file.
///
/// # Returns
///
/// * `Result<Box<dyn Read>>` - A boxed reader that decompresses the file on read
/// * `Result<Box<dyn Read>>` - A boxed reader that decompresses the file on read,
/// or an error if the file cannot be opened or is invalid.
///
/// # Errors
///
/// Returns an error if the file does not exist, is not a valid compressed file,
/// or if decompression fails.
fn open(&self, file_path: PathBuf) -> Result<Box<dyn Read>>;
/// Creates a new compressed file for writing
/// Creates a new compressed file for writing.
///
/// Creates a writer that transparently compresses data as it is written.
///
/// # Arguments
///
/// * `file_path` - Path where the compressed file will be created
/// * `file_path` - Path where the compressed file will be created.
///
/// # Returns
///
/// * `Result<Box<dyn Write>>` - A boxed writer that compresses data on write
/// * `Result<Box<dyn Write>>` - A boxed writer that compresses data on write,
/// or an error if the file cannot be created.
///
/// # Errors
///
/// Returns an error if the path is invalid or if there are permission issues.
fn create(&self, file_path: PathBuf) -> Result<Box<dyn Write>>;
/// Checks if this compression engine is supported on the current system
/// Checks if this compression engine is supported on the current system.
///
/// Some compression types may require external programs or features to be enabled.
///
/// # Returns
///
/// * `bool` - True if supported, false otherwise
/// * `bool` - True if supported, false otherwise.
fn is_supported(&self) -> bool {
true
}
/// Copies decompressed content from a file to a writer
/// Copies decompressed content from a file to a writer.
///
/// Reads the compressed file and writes the decompressed content to the provided writer.
///
/// # Arguments
///
/// * `file_path` - Path to the compressed file
/// * `writer` - Writer to receive decompressed content
/// * `file_path` - Path to the compressed file.
/// * `writer` - Writer to receive decompressed content.
///
/// # Returns
///
/// * `Result<()>` - Success or error
/// * `Result<()>` - Success if the copy completes, or an error.
///
/// # Errors
///
/// Propagates errors from opening the file or copying data.
fn copy(&self, file_path: PathBuf, writer: &mut dyn Write) -> Result<()> {
let mut reader = self.open(file_path)?;
io::copy(&mut reader, writer)?;
@@ -84,29 +136,49 @@ pub trait CompressionEngine {
Ok(())
}
/// Decompresses and outputs file content to stdout
/// Decompresses and outputs file content to stdout.
///
/// Convenience method to decompress and print the contents of a compressed file.
///
/// # Arguments
///
/// * `file_path` - Path to the compressed file
/// * `file_path` - Path to the compressed file.
///
/// # Returns
///
/// * `Result<()>` - Success or error
/// * `Result<()>` - Success if the content is output, or an error.
///
/// # Errors
///
/// Propagates errors from copying to stdout.
fn cat(&self, file_path: PathBuf) -> Result<()> {
let mut stdout = io::stdout().lock();
self.copy(file_path, &mut stdout)
}
/// Calculates the decompressed size of a file
/// Calculates the decompressed size of a file.
///
/// Reads the entire decompressed content to determine its size in bytes.
///
/// # Arguments
///
/// * `file_path` - Path to the compressed file
/// * `file_path` - Path to the compressed file.
///
/// # Returns
///
/// * `Result<usize>` - The decompressed size in bytes
/// * `Result<usize>` - The decompressed size in bytes, or an error.
///
/// # Errors
///
/// Returns an error if the file cannot be opened or read.
///
/// # Examples
///
/// ```
/// let engine = /* some engine */;
/// let size = engine.size("file.gz".into()).unwrap();
/// println!("Decompressed size: {} bytes", size);
/// ```
fn size(&self, file_path: PathBuf) -> Result<usize> {
let mut reader = self.open(file_path)?;
let mut buffer = [0; libc::BUFSIZ as usize];
@@ -159,15 +231,32 @@ lazy_static! {
};
}
/// Gets a compression engine for the specified compression type
/// Gets a compression engine for the specified compression type.
///
/// Dynamically selects and instantiates the appropriate compression engine
/// based on feature flags and available external programs.
///
/// # Arguments
///
/// * `compression_type` - The type of compression to use
/// * `compression_type` - The type of compression to use.
///
/// # Returns
///
/// * `Result<Box<dyn CompressionEngine>>` - A boxed compression engine instance
/// * `Result<Box<dyn CompressionEngine>>` - A boxed compression engine instance,
/// or an error if the type is not supported.
///
/// # Errors
///
/// Returns an error if the specified compression type is not available due to
/// missing features or external programs.
///
/// # Examples
///
/// ```
/// use keep::compression_engine::{get_compression_engine, CompressionType};
/// let engine = get_compression_engine(CompressionType::GZip).unwrap();
/// assert!(engine.is_supported());
/// ```
pub fn get_compression_engine(
compression_type: CompressionType,
) -> Result<Box<dyn CompressionEngine>> {
@@ -212,11 +301,23 @@ pub fn get_compression_engine(
}
}
/// Gets the default compression type based on available support
/// Gets the default compression type based on available support.
///
/// Iterates through all compression types and returns the first one that is
/// supported on the current system. Falls back to `None` if no compression
/// is available.
///
/// # Returns
///
/// * `CompressionType` - The first supported compression type found
/// * `CompressionType` - The first supported compression type found.
///
/// # Examples
///
/// ```
/// use keep::compression_engine::default_compression_type;
/// let default = default_compression_type();
/// println!("Default compression: {}", default);
/// ```
pub fn default_compression_type() -> CompressionType {
let mut default = CompressionType::None;
for compression_type in CompressionType::iter() {