DevComp/zip-rs-wasm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #265 from zip-rs/explainer

Browse source 
Picking the low-hanging documentation fruit
This commit is contained in:
Alexander Zaitsev 2022-03-08 18:23:21 +03:00 • committed by GitHub
commit 25a5b4e4ba
Signed by: DevComp
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 134 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
src/lib.rs
View file

@ -1,7 +1,26 @@
//! An ergonomic API for reading and writing ZIP files.
//! A library for reading and writing ZIP archives.
//! ZIP is a format designed for cross-platform file "archiving".
//! That is, storing a collection of files in a single datastream
//! to make them easier to share between computers.
//! Additionally, ZIP is able to compress and encrypt files in its
//! archives.
//!
//! The current implementation is based on [PKWARE's APPNOTE.TXT v6.3.9](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT)
// TODO(#184): Decide on the crate's bias: Do we prioritise permissiveness/correctness/speed/ergonomics?
//!
//! ---
//!
//! [`zip`](`crate`) has support for the most common ZIP archives found in common use.
//! However, in special cases,
//! there are some zip archives that are difficult to read or write.
//!
//! This is a list of supported features:
//!
//! | | Reading | Writing |
//! | ------- | ------ | ------- |
//! | Deflate | ✅ [->](`crate::ZipArchive::by_name`) | ✅ [->](`crate::write::FileOptions::compression_method`) |
//!
//!
//!
#![warn(missing_docs)]

70
src/read.rs
View file

@ -34,41 +34,45 @@ mod ffi {
pub const S_IFREG: u32 = 0o0100000;
}
/// Extract immutable data from `ZipArchive` to make it cheap to clone
#[derive(Debug)]
struct Shared {
files: Vec<ZipFileData>,
names_map: HashMap<String, usize>,
offset: u64,
comment: Vec<u8>,
}
/// ZIP archive reader
///
/// At the moment, this type is cheap to clone if this is the case for the
/// reader it uses. However, this is not guaranteed by this crate and it may
/// change in the future.
///
/// ```no_run
/// use std::io::prelude::*;
/// fn list_zip_contents(reader: impl Read + Seek) -> zip::result::ZipResult<()> {
/// let mut zip = zip::ZipArchive::new(reader)?;
///
/// for i in 0..zip.len() {
/// let mut file = zip.by_index(i)?;
/// println!("Filename: {}", file.name());
/// std::io::copy(&mut file, &mut std::io::stdout());
/// }
///
/// Ok(())
/// }
/// ```
#[derive(Clone, Debug)]
pub struct ZipArchive<R> {
reader: R,
shared: Arc<Shared>,
// Put the struct declaration in a private module to convince rustdoc to display ZipArchive nicely
pub(crate) mod zip_archive {
/// Extract immutable data from `ZipArchive` to make it cheap to clone
#[derive(Debug)]
pub struct Shared {
pub(super) files: Vec<super::ZipFileData>,
pub(super) names_map: super::HashMap<String, usize>,
pub(super) offset: u64,
pub(super) comment: Vec<u8>,
}
/// ZIP archive reader
///
/// At the moment, this type is cheap to clone if this is the case for the
/// reader it uses. However, this is not guaranteed by this crate and it may
/// change in the future.
///
/// ```no_run
/// use std::io::prelude::*;
/// fn list_zip_contents(reader: impl Read + Seek) -> zip::result::ZipResult<()> {
/// let mut zip = zip::ZipArchive::new(reader)?;
///
/// for i in 0..zip.len() {
/// let mut file = zip.by_index(i)?;
/// println!("Filename: {}", file.name());
/// std::io::copy(&mut file, &mut std::io::stdout());
/// }
///
/// Ok(())
/// }
/// ```
#[derive(Clone, Debug)]
pub struct ZipArchive<R> {
pub(super) reader: R,
pub(super) shared: super::Arc<Shared>,
}
}
pub use zip_archive::{Shared, ZipArchive};
#[allow(clippy::large_enum_variant)]
enum CryptoReader<'a> {
Plaintext(io::Take<&'a mut dyn Read>),

42
src/types.rs
View file

@ -1,4 +1,6 @@
//! Types that specify what is contained in a ZIP.
#[cfg(doc)]
use {crate::read::ZipFile, crate::write::FileOptions};
use std::sync::atomic;
@ -24,19 +26,23 @@ impl System {
}
}
/// A DateTime field to be used for storing timestamps in a zip file
/// Representation of a moment in time.
///
/// This structure does bounds checking to ensure the date is able to be stored in a zip file.
/// Zip files use an old format from DOS to store timestamps,
/// with its own set of peculiarities.
/// For example, it has a resolution of 2 seconds!
///
/// When constructed manually from a date and time, it will also check if the input is sensible
/// (e.g. months are from [1, 12]), but when read from a zip some parts may be out of their normal
/// bounds (e.g. month 0, or hour 31).
/// A [`DateTime`] can be stored directly in a zipfile with [`FileOptions::last_modified_time`],
/// or read from one with [`ZipFile::last_modified`]
///
/// # Warning
///
/// Some utilities use alternative timestamps to improve the accuracy of their
/// ZIPs, but we don't parse them yet. [We're working on this](https://github.com/zip-rs/zip/issues/156#issuecomment-652981904),
/// however this API shouldn't be considered complete.
/// Because there is no timezone associated with the [`DateTime`], they should ideally only
/// be used for user-facing descriptions. This also means [`DateTime::to_time`] returns an
/// [`OffsetDateTime`] (which is the equivalent of chrono's `NaiveDateTime`).
///
/// Modern zip files store more precise timestamps, which are ignored by [`crate::read::ZipArchive`],
/// so keep in mind that these timestamps are unreliable. [We're working on this](https://github.com/zip-rs/zip/issues/156#issuecomment-652981904).
#[derive(Debug, Clone, Copy)]
pub struct DateTime {
year: u16,
@ -168,26 +174,46 @@ impl DateTime {
}
/// Get the month, where 1 = january and 12 = december
///
/// # Warning
///
/// When read from a zip file, this may not be a reasonable value
pub fn month(&self) -> u8 {
self.month
}
/// Get the day
///
/// # Warning
///
/// When read from a zip file, this may not be a reasonable value
pub fn day(&self) -> u8 {
self.day
}
/// Get the hour
///
/// # Warning
///
/// When read from a zip file, this may not be a reasonable value
pub fn hour(&self) -> u8 {
self.hour
}
/// Get the minute
///
/// # Warning
///
/// When read from a zip file, this may not be a reasonable value
pub fn minute(&self) -> u8 {
self.minute
}
/// Get the second
///
/// # Warning
///
/// When read from a zip file, this may not be a reasonable value
pub fn second(&self) -> u8 {
self.second
}

80
src/write.rs
View file

@ -42,45 +42,49 @@ enum GenericZipWriter<W: Write + io::Seek> {
#[cfg(feature = "zstd")]
Zstd(ZstdEncoder<'static, W>),
}
/// ZIP archive generator
///
/// Handles the bookkeeping involved in building an archive, and provides an
/// API to edit its contents.
///
/// ```
/// # fn doit() -> zip::result::ZipResult<()>
/// # {
/// # use zip::ZipWriter;
/// use std::io::Write;
/// use zip::write::FileOptions;
///
/// // We use a buffer here, though you'd normally use a `File`
/// let mut buf = [0; 65536];
/// let mut zip = zip::ZipWriter::new(std::io::Cursor::new(&mut buf[..]));
///
/// let options = zip::write::FileOptions::default().compression_method(zip::CompressionMethod::Stored);
/// zip.start_file("hello_world.txt", options)?;
/// zip.write(b"Hello, World!")?;
///
/// // Apply the changes you've made.
/// // Dropping the `ZipWriter` will have the same effect, but may silently fail
/// zip.finish()?;
///
/// # Ok(())
/// # }
/// # doit().unwrap();
/// ```
pub struct ZipWriter<W: Write + io::Seek> {
inner: GenericZipWriter<W>,
files: Vec<ZipFileData>,
stats: ZipWriterStats,
writing_to_file: bool,
writing_to_extra_field: bool,
writing_to_central_extra_field_only: bool,
writing_raw: bool,
comment: Vec<u8>,
// Put the struct declaration in a private module to convince rustdoc to display ZipWriter nicely
pub(crate) mod zip_writer {
use super::*;
/// ZIP archive generator
///
/// Handles the bookkeeping involved in building an archive, and provides an
/// API to edit its contents.
///
/// ```
/// # fn doit() -> zip::result::ZipResult<()>
/// # {
/// # use zip::ZipWriter;
/// use std::io::Write;
/// use zip::write::FileOptions;
///
/// // We use a buffer here, though you'd normally use a `File`
/// let mut buf = [0; 65536];
/// let mut zip = zip::ZipWriter::new(std::io::Cursor::new(&mut buf[..]));
///
/// let options = zip::write::FileOptions::default().compression_method(zip::CompressionMethod::Stored);
/// zip.start_file("hello_world.txt", options)?;
/// zip.write(b"Hello, World!")?;
///
/// // Apply the changes you've made.
/// // Dropping the `ZipWriter` will have the same effect, but may silently fail
/// zip.finish()?;
///
/// # Ok(())
/// # }
/// # doit().unwrap();
/// ```
pub struct ZipWriter<W: Write + io::Seek> {
pub(super) inner: GenericZipWriter<W>,
pub(super) files: Vec<ZipFileData>,
pub(super) stats: ZipWriterStats,
pub(super) writing_to_file: bool,
pub(super) writing_to_extra_field: bool,
pub(super) writing_to_central_extra_field_only: bool,
pub(super) writing_raw: bool,
pub(super) comment: Vec<u8>,
}
}
pub use zip_writer::ZipWriter;
#[derive(Default)]
struct ZipWriterStats {