Merge pull request #17 from phip1611/dev

various improvements and fixes

CHANGELOG.md

@@ -1,16 +1,27 @@
 # v0.3.0 (2024-05-03)
+
 - MSRV is now 1.76 stable
 - added support for more Tar archives
-  - 256 character long filename support (prefix + name)
-  - add support for space terminated numbers
-  - non-null terminated names
-  - iterate over directories: read regular files from directories
-  - more info: <https://github.com/phip1611/tar-no-std/pull/10>
+    - 256 character long filename support (prefix + name)
+    - add support for space terminated numbers
+    - non-null terminated names
+    - iterate over directories: read regular files from directories
+    - more info: <https://github.com/phip1611/tar-no-std/pull/10>
 - `TarArchive[Ref]::new` now returns a result
 - added `unstable` feature with enhanced functionality for `nightly` compilers
-  - error types implement `core::error::Error`
+    - error types implement `core::error::Error`
+- various bug fixes and code improvements
+- better error reporting / less panics
+
+Special thanks to the following external contributors or helpers:
+
+- https://github.com/thenhnn: provide me with a bunch of Tar archives coming
+  from a fuzzer
+- https://github.com/schnoberts1 implemented 256 character long filenames (ustar
+  Tar format)
 
 # v0.2.0 (2023-04-11)
+
 - MSRV is 1.60.0
 - bitflags bump: 1.x -> 2.x
 - few internal code improvements (less possible panics)

README.md

@@ -1,59 +1,65 @@
 # `tar-no-std` - Parse Tar Archives (Tarballs)
 
-_Due to historical reasons, there are several formats of tar archives. All of them are based on the same principles,
-but have some subtle differences that often make them incompatible with each other._ [0]
+_Due to historical reasons, there are several formats of Tar archives. All of
+them are based on the same principles, but have some subtle differences that
+often make them incompatible with each other._ [(reference)](https://www.gnu.org/software/tar/manual/html_section/Formats.html)
 
-Library to read Tar archives (by GNU Tar) in `no_std` contexts with zero allocations. If you have a standard
-environment and need full feature support, I recommend the use of <https://crates.io/crates/tar> instead.
+Library to read Tar archives in `no_std` environments with zero allocations. If
+you have a standard environment and need full feature support, I recommend the
+use of <https://crates.io/crates/tar> instead.
 
 ## Limitations
-The crate is simple and only supports reading of "basic" archives, therefore no extensions, such
-as GNU Longname. The maximum supported file name length is 256 characters excluding the NULL-byte (using the tar name/prefix longname implementation). The maximum supported file size is 8GiB. Directories are supported, but only regular fields are yielded in iteration.
 
+This crate is simple and focuses on reading files and their content from a Tar
+archive. Historic basic Tar and ustar [formats](https://www.gnu.org/software/tar/manual/html_section/Formats.html)
+are supported. Other formats may work, but likely without all supported
+features. GNU Extensions such as sparse files, incremental archives, and long
+filename extension are not supported.
+
+The maximum supported file name length is 256 characters excluding the
+NULL-byte (using the Tar name/prefix longname implementation of ustar). The
+maximum supported file size is 8GiB. Directories are supported, but only regular
+fields are yielded in iteration. The path is reflected in their file name.
 
 ## Use Case
 
-This library is useful, if you write a kernel or a similar low-level application, which needs
-"a bunch of files" from an archive ("init ramdisk"). The Tar file could for example come
-as a Multiboot2 boot module provided by the bootloader.
+This library is useful, if you write a kernel or a similar low-level
+application, which needs "a bunch of files" from an archive (like an
+"init ramdisk"). The Tar file could for example come as a Multiboot2 boot module
+provided by the bootloader.
 
-This crate focuses on extracting files from uncompressed Tar archives created with default options by **GNU Tar**.
-GNU Extensions such as sparse files, incremental archives, and long filename extension are not supported yet.
-[This link](https://www.gnu.org/software/tar/manual/html_section/Formats.html) gives a good overview over possible
-archive formats and their limitations.
+## Example
 
-## Example (without `alloc`-feature)
 ```rust
 use tar_no_std::TarArchiveRef;
 
 fn main() {
-    // log: not mandatory
+    // init a logger (optional)
     std::env::set_var("RUST_LOG", "trace");
     env_logger::init();
 
     // also works in no_std environment (except the println!, of course)
     let archive = include_bytes!("../tests/gnu_tar_default.tar");
-    let archive = TarArchiveRef::new(archive);
+    let archive = TarArchiveRef::new(archive).unwrap();
     // Vec needs an allocator of course, but the library itself doesn't need one
     let entries = archive.entries().collect::<Vec<_>>();
     println!("{:#?}", entries);
-    println!("content of last file:");
-    println!("{:#?}", entries[2].data_as_str().expect("Should be valid UTF-8"));
 }
 ```
 
-## Alloc Feature
-This crate allows the usage of the additional Cargo build time feature `alloc`. When this is used,
-the crate also provides the type `TarArchive`, which owns the data on the heap.
+## Cargo Feature
+
+This crate allows the usage of the additional Cargo build time feature `alloc`.
+When this is active, the crate also provides the type `TarArchive`, which owns
+the data on the heap. The `unstable` feature provides additional convenience
+only available on the nightly channel.
 
 ## Compression (`tar.gz`)
-If your tar file is compressed, e.g. by `.tar.gz`/`gzip`, you need to uncompress the bytes first
-(e.g. by a *gzip* library). Afterwards, this crate can read the Tar archive format from the uncompressed
-bytes.
 
-## MSRV
-The MSRV is 1.76.0 stable.
+If your Tar file is compressed, e.g. by `.tar.gz`/`gzip`, you need to uncompress
+the bytes first (e.g. by a *gzip* library). Afterwards, this crate can read the
+Tar archive format from the uncompressed bytes.
 
+## MSRV
 
-## References
-[0]\: https://www.gnu.org/software/tar/manual/html_section/Formats.html
+The MSRV is 1.76.0 stable.

examples/alloc_feature.rs

@@ -27,6 +27,7 @@ use tar_no_std::TarArchive;
 fn main() {
     // log: not mandatory
     std::env::set_var("RUST_LOG", "trace");
+    std::env::set_var("RUST_LOG_STYLE", "always");
     env_logger::init();
 
     // also works in no_std environment (except the println!, of course)

examples/minimal.rs

@@ -26,6 +26,7 @@ use tar_no_std::TarArchiveRef;
 fn main() {
     // log: not mandatory
     std::env::set_var("RUST_LOG", "trace");
+    std::env::set_var("RUST_LOG_STYLE", "always");
     env_logger::init();
 
     // also works in no_std environment (except the println!, of course)