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},
|
std::io::{Read, Write},
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/// Optional checksumming for individual files
|
||||||
#[derive(Debug)]
|
#[derive(Debug)]
|
||||||
pub enum Checksum {
|
pub enum Checksum {
|
||||||
|
/// Md5 checksumming, fastest
|
||||||
Md5([u8; 16]),
|
Md5([u8; 16]),
|
||||||
|
/// Sha1 checksumming. On par with md5.
|
||||||
Sha1([u8; 20]),
|
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]),
|
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,
|
Skip,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -6,10 +6,14 @@ use {
|
|||||||
std::io::{Read, Write},
|
std::io::{Read, Write},
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/// A representation of a regular file as an archive member
|
||||||
#[derive(Debug)]
|
#[derive(Debug)]
|
||||||
pub struct File {
|
pub struct File {
|
||||||
|
/// The length of this file
|
||||||
pub len: u64,
|
pub len: u64,
|
||||||
|
/// The optional checksum of this file
|
||||||
pub checksum: Checksum,
|
pub checksum: Checksum,
|
||||||
|
/// The bytes making up this file
|
||||||
pub data: Vec<u8>,
|
pub data: Vec<u8>,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -3,15 +3,22 @@ use {
|
|||||||
std::io::{Read, Write},
|
std::io::{Read, Write},
|
||||||
};
|
};
|
||||||
|
|
||||||
#[repr(u8)]
|
/// An enum representing the type of file of an archive member
|
||||||
#[derive(Debug)]
|
#[derive(Debug)]
|
||||||
pub enum FileType {
|
pub enum FileType {
|
||||||
|
/// A normal file and it's contained data
|
||||||
Normal(File),
|
Normal(File),
|
||||||
|
/// A hard link to another file in this archive
|
||||||
HardLink(String),
|
HardLink(String),
|
||||||
|
/// A soft link to another file
|
||||||
SoftLink(String),
|
SoftLink(String),
|
||||||
|
/// A directory inode
|
||||||
Directory,
|
Directory,
|
||||||
|
/// A character (buffered) device
|
||||||
Character(Special),
|
Character(Special),
|
||||||
|
/// A block device
|
||||||
Block(Special),
|
Block(Special),
|
||||||
|
/// A Unix named pipe (fifo)
|
||||||
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)]
|
#[derive(Debug)]
|
||||||
pub struct Node {
|
pub struct Node {
|
||||||
|
/// The filesystem path to this file
|
||||||
pub name: String,
|
pub name: String,
|
||||||
|
/// The Unix permissions bits of this file
|
||||||
pub mode: u32,
|
pub mode: u32,
|
||||||
|
/// The user id of this file's owner
|
||||||
pub uid: u32,
|
pub uid: u32,
|
||||||
|
/// The group id of this file's owner
|
||||||
pub gid: u32,
|
pub gid: u32,
|
||||||
|
/// The most recent modification time of this file
|
||||||
pub mtime: u64,
|
pub mtime: u64,
|
||||||
|
/// The type of file this node represents
|
||||||
pub filetype: FileType,
|
pub filetype: FileType,
|
||||||
}
|
}
|
||||||
|
|
||||||
impl Node {
|
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> {
|
pub fn read<T: Read>(reader: &mut T) -> Result<Self, Error> {
|
||||||
let mut len = [0; 8];
|
let mut len = [0; 8];
|
||||||
reader.read_exact(&mut len)?;
|
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> {
|
pub fn write<T: Write>(&self, writer: &mut T) -> Result<(), Error> {
|
||||||
let len = self.name.len() as u64;
|
let len = self.name.len() as u64;
|
||||||
writer.write_all(&len.to_le_bytes())?;
|
writer.write_all(&len.to_le_bytes())?;
|
||||||
@ -86,10 +100,18 @@ impl Node {
|
|||||||
Ok(())
|
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(
|
pub fn from_path(
|
||||||
path: &str,
|
path: &str,
|
||||||
checksum: Checksum,
|
checksum: Checksum,
|
||||||
links: Mutex<HashMap<u64, String>>,
|
links: &Mutex<HashMap<u64, String>>,
|
||||||
) -> Result<Self, Error> {
|
) -> Result<Self, Error> {
|
||||||
let name = String::from(path);
|
let name = String::from(path);
|
||||||
let fd = fs::File::open(path)?;
|
let fd = fs::File::open(path)?;
|
||||||
@ -174,4 +196,8 @@ impl Node {
|
|||||||
filetype,
|
filetype,
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
|
||||||
|
pub fn extract(&self, prefix: Option<&str>) -> Result<(), Error> {
|
||||||
|
todo!()
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
@ -3,6 +3,7 @@ use {
|
|||||||
std::io::{Read, Write},
|
std::io::{Read, Write},
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/// Represents the major and minor numbers of a Unix special Device node
|
||||||
#[derive(Debug)]
|
#[derive(Debug)]
|
||||||
pub struct Special {
|
pub struct Special {
|
||||||
pub major: u32,
|
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)]
|
#[derive(Debug)]
|
||||||
pub struct Stream<T: Read> {
|
pub struct Stream<T: Read> {
|
||||||
reader: T,
|
reader: T,
|
||||||
|
Loading…
Reference in New Issue
Block a user