Add doc comments for many public facing types
This commit is contained in:
parent
7346b40df8
commit
13c82f79da
@ -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,
|
||||
}
|
||||
|
||||
|
@ -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>,
|
||||
}
|
||||
|
||||
|
@ -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,
|
||||
}
|
||||
|
||||
|
28
src/node.rs
28
src/node.rs
@ -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!()
|
||||
}
|
||||
}
|
||||
|
@ -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,
|
||||
|
@ -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,
|
||||
|
Loading…
Reference in New Issue
Block a user