diff --git a/src/bin/extract.rs b/src/bin/extract.rs index e84f4054..c4122510 100644 --- a/src/bin/extract.rs +++ b/src/bin/extract.rs @@ -6,7 +6,7 @@ fn main() let fname = Path::new(args[1].as_slice()); let file = std::io::File::open(&fname); - let zipcontainer = zip::reader::ZipReader::new(file).unwrap(); + let zipcontainer = zip::ZipReader::new(file).unwrap(); for file in zipcontainer.files() { diff --git a/src/bin/write_sample.rs b/src/bin/write_sample.rs index 5d61c4a3..25d11a40 100644 --- a/src/bin/write_sample.rs +++ b/src/bin/write_sample.rs @@ -11,11 +11,7 @@ fn doit() -> std::io::IoResult<()> let fname = Path::new(args[1].as_slice()); let file = std::io::File::create(&fname).unwrap(); - let mut zip = zip::writer::ZipWriter::new(file); - - -// try!(zip.start_file(b"test", zip::types::Stored)); -// try!(zip.write(b"")); + let mut zip = zip::ZipWriter::new(file); try!(zip.start_file(b"test/readme.txt", zip::types::Stored)); try!(zip.write(b"Hello, World!\n")); diff --git a/src/crc32.rs b/src/crc32.rs index 67877c69..b2578c2c 100644 --- a/src/crc32.rs +++ b/src/crc32.rs @@ -1,3 +1,5 @@ +//! Helper module to compute a CRC32 checksum + use std::io; static CRC32_TABLE : [u32, ..256] = [ @@ -46,6 +48,7 @@ static CRC32_TABLE : [u32, ..256] = [ 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 0x2d02ef8d ]; +/// Update the checksum original based upon the contents of buf. pub fn crc32(original: u32, buf: &[u8]) -> u32 { let mut crc = original ^ !0u32; @@ -58,6 +61,7 @@ pub fn crc32(original: u32, buf: &[u8]) -> u32 return crc ^ !0u32; } +/// Reader that validates the CRC32 when it reaches the EOF. pub struct Crc32Reader { inner: R, @@ -67,6 +71,7 @@ pub struct Crc32Reader impl Crc32Reader { + /// Get a new Crc32Reader which check the inner reader against checksum. pub fn new(inner: R, checksum: u32) -> Crc32Reader { Crc32Reader diff --git a/src/lib.rs b/src/lib.rs index 66652c14..5632ea47 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,13 +1,19 @@ +//! A basic ZipReader/Writer crate + #![feature(phase)] #![feature(unsafe_destructor)] +#![warn(missing_doc)] #[phase(plugin, link)] extern crate log; extern crate time; extern crate flate2; +pub use reader::ZipReader; +pub use writer::ZipWriter; + mod util; mod spec; pub mod crc32; -pub mod reader; +mod reader; pub mod types; -pub mod writer; +mod writer; diff --git a/src/reader.rs b/src/reader.rs index d2b979f0..678e7b5b 100644 --- a/src/reader.rs +++ b/src/reader.rs @@ -7,6 +7,30 @@ use std::io::{IoResult, IoError}; use std::cell::RefCell; use flate2::FlateReader; +/// Wrapper for reading the contents of a ZIP file. +/// +/// ``` +/// fn doit() -> std::io::IoResult<()> +/// { +/// // For demonstration purposes we read from an empty buffer. +/// // Normally a File object would be used. +/// let buf = [0u8, 128]; +/// let mut reader = std::io::BufReader::new(&buf); +/// +/// let zip = try!(zip::ZipReader::new(reader)); +/// +/// for file in zip.files() +/// { +/// println!("Filename: {}", file.file_name_string()); +/// let mut file_reader = try!(zip.read_file(file)); +/// let first_byte = try!(file_reader.read_byte()); +/// println!("{}", first_byte); +/// } +/// Ok(()) +/// } +/// +/// println!("Result: {}", doit()); +/// ``` pub struct ZipReader { inner: RefCell, @@ -25,6 +49,7 @@ fn unsupported_zip_error(detail: &str) -> IoResult impl ZipReader { + /// Opens a ZIP file and parses the content headers. pub fn new(mut reader: T) -> IoResult> { let footer = try!(spec::CentralDirectoryEnd::find_and_parse(&mut reader)); @@ -45,11 +70,18 @@ impl ZipReader Ok(ZipReader { inner: RefCell::new(reader), files: files }) } + /// An iterator over the information of all contained files. pub fn files(&self) -> ::std::slice::Items { self.files.as_slice().iter() } + /// Gets a reader for a contained zipfile. + /// + /// Possible errors: + /// + /// * `ResourceUnavailable`: when another reader returned from this function is still active + /// * `OtherIoError`: if the file is encrypted or has an unsupported compression pub fn read_file(&self, file: &ZipFile) -> IoResult> { let mut inner_reader = match self.inner.try_borrow_mut() diff --git a/src/types.rs b/src/types.rs index d0234e57..493e94e2 100644 --- a/src/types.rs +++ b/src/types.rs @@ -1,49 +1,81 @@ +//! Types that specify what is contained in a ZIP. + use time; +/// Compression methods for the contents of a ZIP file. #[deriving(FromPrimitive, Clone)] pub enum CompressionMethod { + /// The file is stored (no compression) Stored = 0, + /// The file is Shrunk Shrunk = 1, + /// The file is Reduced with compression factor 1 Reduced1 = 2, + /// The file is Reduced with compression factor 2 Reduced2 = 3, + /// The file is Reduced with compression factor 3 Reduced3 = 4, + /// The file is Reduced with compression factor 4 Reduced4 = 5, + /// The file is Imploded Imploded = 6, + /// The file is Deflated Deflated = 8, + /// Enhanced Deflating using Deflate64(tm) Deflate64 = 9, + /// PKWARE Data Compression Library Imploding (old IBM TERSE) PkwareImploding = 10, + /// File is compressed using BZIP2 algorithm Bzip2 = 12, + /// LZMA (EFS) LZMA = 14, + /// File is compressed using IBM TERSE (new) IBMTerse = 18, + /// IBM LZ77 z Architecture (PFS) LZ77 = 19, + /// WavPack compressed data WavPack = 97, + /// PPMd version I, Rev 1 PPMdI1 = 98, + /// Unknown (invalid) compression Unknown = 100000, } - +/// Structure representing a ZIP file. pub struct ZipFile { + /// True if the file is encrypted. pub encrypted: bool, + /// Compression method used to store the file pub compression_method: CompressionMethod, + /// Last modified time. This will only have a 2 second precision. pub last_modified_time: time::Tm, + /// CRC32 checksum pub crc32: u32, + /// Size of the file in the ZIP pub compressed_size: u64, + /// Size of the file when extracted pub uncompressed_size: u64, + /// Name of the file pub file_name: Vec, + /// File comment pub file_comment: Vec, + /// Specifies where the local header of the file starts pub header_start: u64, + /// Specifies where the compressed data of the file starts pub data_start: u64, } impl ZipFile { + /// Lossy UTF-8 interpretation of the file name pub fn file_name_string(&self) -> String { String::from_utf8_lossy(self.file_name.as_slice()).into_string() } + /// Lossy UTF-8 interpretation of the file comment pub fn file_comment_string(&self) -> String { String::from_utf8_lossy(self.file_comment.as_slice()).into_string() diff --git a/src/writer.rs b/src/writer.rs index 27cc2d6d..580f1809 100644 --- a/src/writer.rs +++ b/src/writer.rs @@ -17,6 +17,27 @@ enum GenericZipWriter Deflater(DeflateEncoder), } +/// Generator for ZIP files. +/// +/// ``` +/// fn doit() -> std::io::IoResult<()> +/// { +/// // For this example we write to a buffer, but normally you should use a File +/// let mut buf = [0u8, ..65536]; +/// let w = std::io::BufWriter::new(&mut buf); +/// let mut zip = zip::ZipWriter::new(w); +/// +/// try!(zip.start_file(b"hello_world.txt", zip::types::Stored)); +/// try!(zip.write(b"Hello, World!")); +/// +/// // Optionally finish the zip. (this is also done on drop) +/// try!(zip.finalize()); +/// +/// Ok(()) +/// } +/// +/// println!("Result: {}", doit()); +/// ``` pub struct ZipWriter { inner: GenericZipWriter, @@ -63,6 +84,9 @@ impl ZipWriterStats impl ZipWriter { + /// Initializes the ZipWriter. + /// + /// Before writing to this object, the start_file command should be called. pub fn new(inner: W) -> ZipWriter { ZipWriter @@ -73,6 +97,7 @@ impl ZipWriter } } + /// Start a new file for with the requested compression method. pub fn start_file(&mut self, name: &[u8], compression: types::CompressionMethod) -> IoResult<()> { try!(self.finish_file()); @@ -126,6 +151,7 @@ impl ZipWriter Ok(()) } + /// Finish the last file and write all other zip-structures pub fn finalize(&mut self) -> IoResult<()> { try!(self.finish_file());