Add doc comments for many public facing types

This commit is contained in:
Nathan Fisher 2023-07-04 20:13:38 -04:00
parent 7346b40df8
commit 13c82f79da
6 changed files with 50 additions and 2 deletions

View File

@ -3,11 +3,19 @@ use {
std::io::{Read, Write},
};
/// Optional checksumming for individual files
#[derive(Debug)]
pub enum Checksum {
/// Md5 checksumming, fastest
Md5([u8; 16]),
/// Sha1 checksumming. On par with md5.
Sha1([u8; 20]),
/// The most thorough checksumming offered. Use this if data integrity is of
/// utmost importance and computational overhead is of lesser importance.
Sha256([u8; 32]),
/// Do not use checksumming. If this option is selected it is recommended that
/// the entire archive is downloaded in entirety and checksummed to ensure it's
/// integrity, as was the pattern with Unix 'tar' archives and 'iso' images
Skip,
}

View File

@ -6,10 +6,14 @@ use {
std::io::{Read, Write},
};
/// A representation of a regular file as an archive member
#[derive(Debug)]
pub struct File {
/// The length of this file
pub len: u64,
/// The optional checksum of this file
pub checksum: Checksum,
/// The bytes making up this file
pub data: Vec<u8>,
}

View File

@ -3,15 +3,22 @@ use {
std::io::{Read, Write},
};
#[repr(u8)]
/// An enum representing the type of file of an archive member
#[derive(Debug)]
pub enum FileType {
/// A normal file and it's contained data
Normal(File),
/// A hard link to another file in this archive
HardLink(String),
/// A soft link to another file
SoftLink(String),
/// A directory inode
Directory,
/// A character (buffered) device
Character(Special),
/// A block device
Block(Special),
/// A Unix named pipe (fifo)
Fifo,
}

View File

@ -39,17 +39,27 @@ impl From<u32> for Kind {
}
}
/// A representation of a file and it's associated metadata.
#[derive(Debug)]
pub struct Node {
/// The filesystem path to this file
pub name: String,
/// The Unix permissions bits of this file
pub mode: u32,
/// The user id of this file's owner
pub uid: u32,
/// The group id of this file's owner
pub gid: u32,
/// The most recent modification time of this file
pub mtime: u64,
/// The type of file this node represents
pub filetype: FileType,
}
impl Node {
/// Reads a `Node` from an archive file or stream of Nodes.
/// > Note: this function reads an already created node. To create a new node
/// > from a file, use the `from_path` method.
pub fn read<T: Read>(reader: &mut T) -> Result<Self, Error> {
let mut len = [0; 8];
reader.read_exact(&mut len)?;
@ -74,6 +84,10 @@ impl Node {
})
}
/// Write a `Node` struct into it's on-disk archive representation.
/// > Note: this function saves the data to the archive format's on-disk
/// > representation. To extract the contents of a `Node` and write out the
/// > file it represents, use the `extract` method instead.
pub fn write<T: Write>(&self, writer: &mut T) -> Result<(), Error> {
let len = self.name.len() as u64;
writer.write_all(&len.to_le_bytes())?;
@ -86,10 +100,18 @@ impl Node {
Ok(())
}
/// Creates a new node from a file which exists on the filesystem
/// ### Parameters
/// - path - the path to this file
/// - checksum - a zeroed out `Checksum` variant to be used if the inline
/// checksumming feature is to be used
/// - links - this should be passed to each invocation of `from_path` used
/// during the creation of a single archive, to identify hard links and to
/// avoid writing their data out more than once.
pub fn from_path(
path: &str,
checksum: Checksum,
links: Mutex<HashMap<u64, String>>,
links: &Mutex<HashMap<u64, String>>,
) -> Result<Self, Error> {
let name = String::from(path);
let fd = fs::File::open(path)?;
@ -174,4 +196,8 @@ impl Node {
filetype,
})
}
pub fn extract(&self, prefix: Option<&str>) -> Result<(), Error> {
todo!()
}
}

View File

@ -3,6 +3,7 @@ use {
std::io::{Read, Write},
};
/// Represents the major and minor numbers of a Unix special Device node
#[derive(Debug)]
pub struct Special {
pub major: u32,

View File

@ -6,6 +6,8 @@ use {
},
};
/// An iterator over a series of archive `Node`'s. This struct is generic over any
/// type which implements `Read`, such as a file or a network stream.
#[derive(Debug)]
pub struct Stream<T: Read> {
reader: T,