From 1181e6b70ba6a4b4b107ecd9a96f619a9bf92b6b Mon Sep 17 00:00:00 2001 From: Christopher Cole Date: Wed, 15 Feb 2023 15:21:13 -0800 Subject: [PATCH] Reorder README/doc comment feature list --- README.md | 70 +++++++++++++++++++++++++++--------------------------- src/lib.rs | 70 +++++++++++++++++++++++++++--------------------------- 2 files changed, 70 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index 36d162b..27d94e8 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,41 @@ The `elf` crate provides a pure-safe-rust interface for reading ELF object files # Capabilities +### ✨ Works in `no_std` environments ✨ +This crate provides an elf parsing interface which does not allocate or use any std +features, so it can be used in `no_std` environments such as kernels and bootloaders. +The no_std variant merely disables the additional stream-oriented `std:: Read + Seek` interface. +All core parsing functionality is the same! + +### ✨ Endian-aware ✨ +This crate handles translating between file and host endianness when +parsing the ELF contents and provides four endian parsing implementations +optimized to support the different common use-cases for an ELF parsing library. +Parsing is generic across the specifications and each trait impl represents a +specification that encapsulates an interface for parsing integers from some +set of allowed byte orderings. + +* `AnyEndian`: Dynamically parsing either byte order at runtime based on the type of ELF object being parsed. +* `BigEndian`/`LittleEndian`: For tools that know they only want to parse a single given byte order known at compile time. +* `NativeEndian`: For tools that know they want to parse the same byte order as the compilation target's byte order. + +When the limited specifications are used, errors are properly returned when asked to parse an ELF file +with an unexpected byte ordering. + +### ✨ Zero-alloc parser ✨ +This crate implements parsing in a way that avoids heap allocations. ELF structures +are parsed and stored on the stack and provided by patterns such as lazily parsed iterators +that yield stack allocated rust types, or lazily parsing tables that only parse out a particular +entry on table.get(index). The structures are copy-converted as needed from the underlying file +data into Rust's native struct representation. + +### ✨ Fuzz Tested ✨ +Various parts of the library are fuzz tested for panics and crashes (see `fuzz/`). + +Memory safety is a core goal, as is providing a safe interface that errors on bad data +over crashing or panicking. Checked integer math is used where appropriate, and ParseErrors are +returned when bad or corrupted ELF structures are encountered. + ### ✨ Uses only safe interfaces ✨ With memory safety a core goal, this crate contains zero unsafe code blocks of its own and only uses safe interface methods from core and std, so you can @@ -22,26 +57,6 @@ Note: I'd love to see this crate be enhanced further once rust provides safe tra See: -### ✨ Fuzz Tested ✨ -Various parts of the library are fuzz tested for panics and crashes (see `fuzz/`). - -Memory safety is a core goal, as is providing a safe interface that errors on bad data -over crashing or panicking. Checked integer math is used where appropriate, and ParseErrors are -returned when bad or corrupted ELF structures are encountered. - -### ✨ Works in `no_std` environments ✨ -This crate provides an elf parsing interface which does not allocate or use any std -features, so it can be used in `no_std` environments such as kernels and bootloaders. -The no_std variant merely disables the additional stream-oriented `std:: Read + Seek` interface. -All core parsing functionality is the same! - -### ✨ Zero-alloc parser ✨ -This crate implements parsing in a way that avoids heap allocations. ELF structures -are parsed and stored on the stack and provided by patterns such as lazily parsed iterators -that yield stack allocated rust types, or lazily parsing tables that only parse out a particular -entry on table.get(index). The structures are copy-converted as needed from the underlying file -data into Rust's native struct representation. - ### ✨ Some zero-copy interfaces ✨ The StringTable, for instance, yields `&[u8]` and `&str` backed by the raw string table bytes. @@ -58,21 +73,6 @@ The `ParsingIterator`s are also nice in that you can easily zip/enumerate/filter how you wish. Do you know that you want to do multiple passes over pairs from different tables? Just zip/collect them into another type so you only parse/endian-flip each entry once! -### ✨ Endian-aware ✨ -This crate handles translating between file and host endianness when -parsing the ELF contents and provides four endian parsing implementations -optimized to support the different common use-cases for an ELF parsing library. -Parsing is generic across the specifications and each trait impl represents a -specification that encapsulates an interface for parsing integers from some -set of allowed byte orderings. - -* `AnyEndian`: Dynamically parsing either byte order at runtime based on the type of ELF object being parsed. -* `BigEndian`/`LittleEndian`: For tools that know they only want to parse a single given byte order known at compile time. -* `NativeEndian`: For tools that know they want to parse the same byte order as the compilation target's byte order. - -When the limited specifications are used, errors are properly returned when asked to parse an ELF file -with an unexpected byte ordering. - ### ✨ Stream-based lazy i/o interface ✨ The `ElfStream` parser type takes a `std:: Read + Seek` (such as `std::fs::File`) where ranges of file contents are read lazily on-demand based on what the user wants to parse. diff --git a/src/lib.rs b/src/lib.rs index 7b0e180..291e0c9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,6 +2,41 @@ //! //! # Capabilities //! +//! ### ✨ Works in `no_std` environments ✨ +//! This crate provides an elf parsing interface which does not allocate or use any std +//! features, so it can be used in `no_std` environments such as kernels and bootloaders. +//! The no_std variant merely disables the additional stream-oriented `std:: Read + Seek` interface. +//! All core parsing functionality is the same! +//! +//! ### ✨ Endian-aware ✨ +//! This crate handles translating between file and host endianness when +//! parsing the ELF contents and provides four endian parsing implementations +//! optimized to support the different common use-cases for an ELF parsing library. +//! Parsing is generic across the specifications and each trait impl represents a +//! specification that encapsulates an interface for parsing integers from some +//! set of allowed byte orderings. +//! +//! * [AnyEndian](endian::AnyEndian): Dynamically parsing either byte order at runtime based on the type of ELF object being parsed. +//! * [BigEndian](endian::BigEndian)/[LittleEndian](endian::LittleEndian): For tools that know they only want to parse a single given byte order known at compile time. +//! * [NativeEndian](type@endian::NativeEndian): For tools that know they want to parse the same byte order as the compilation target's byte order. +//! +//! When the limited specifications are used, errors are properly returned when asked to parse an ELF file +//! with an unexpected byte ordering. +//! +//! ### ✨ Zero-alloc parser ✨ +//! This crate implements parsing in a way that avoids heap allocations. ELF structures +//! are parsed and stored on the stack and provided by patterns such as lazily parsed iterators +//! that yield stack allocated rust types, or lazily parsing tables that only parse out a particular +//! entry on table.get(index). The structures are copy-converted as needed from the underlying file +//! data into Rust's native struct representation. +//! +//! ### ✨ Fuzz Tested ✨ +//! Various parts of the library are fuzz tested for panics and crashes (see `fuzz/`). +//! +//! Memory safety is a core goal, as is providing a safe interface that errors on bad data +//! over crashing or panicking. Checked integer math is used where appropriate, and ParseErrors are +//! returned when bad or corrupted ELF structures are encountered. +//! //! ### ✨ Uses only safe interfaces ✨ //! With memory safety a core goal, this crate contains zero unsafe code blocks //! of its own and only uses safe interface methods from core and std, so you can @@ -13,26 +48,6 @@ //! //! See: //! -//! ### ✨ Fuzz Tested ✨ -//! Various parts of the library are fuzz tested for panics and crashes (see `fuzz/`). -//! -//! Memory safety is a core goal, as is providing a safe interface that errors on bad data -//! over crashing or panicking. Checked integer math is used where appropriate, and ParseErrors are -//! returned when bad or corrupted ELF structures are encountered. -//! -//! ### ✨ Works in `no_std` environments ✨ -//! This crate provides an elf parsing interface which does not allocate or use any std -//! features, so it can be used in `no_std` environments such as kernels and bootloaders. -//! The no_std variant merely disables the additional stream-oriented `std:: Read + Seek` interface. -//! All core parsing functionality is the same! -//! -//! ### ✨ Zero-alloc parser ✨ -//! This crate implements parsing in a way that avoids heap allocations. ELF structures -//! are parsed and stored on the stack and provided by patterns such as lazily parsed iterators -//! that yield stack allocated rust types, or lazily parsing tables that only parse out a particular -//! entry on table.get(index). The structures are copy-converted as needed from the underlying file -//! data into Rust's native struct representation. -//! //! ### ✨ Some zero-copy interfaces ✨ //! The StringTable, for instance, yields `&[u8]` and `&str` backed by the raw string table bytes. //! @@ -49,21 +64,6 @@ //! how you wish. Do you know that you want to do multiple passes over pairs from different tables? Just //! zip/collect them into another type so you only parse/endian-flip each entry once! //! -//! ### ✨ Endian-aware ✨ -//! This crate handles translating between file and host endianness when -//! parsing the ELF contents and provides four endian parsing implementations -//! optimized to support the different common use-cases for an ELF parsing library. -//! Parsing is generic across the specifications and each trait impl represents a -//! specification that encapsulates an interface for parsing integers from some -//! set of allowed byte orderings. -//! -//! * [AnyEndian](endian::AnyEndian): Dynamically parsing either byte order at runtime based on the type of ELF object being parsed. -//! * [BigEndian](endian::BigEndian)/[LittleEndian](endian::LittleEndian): For tools that know they only want to parse a single given byte order known at compile time. -//! * [NativeEndian](type@endian::NativeEndian): For tools that know they want to parse the same byte order as the compilation target's byte order. -//! -//! When the limited specifications are used, errors are properly returned when asked to parse an ELF file -//! with an unexpected byte ordering. -//! //! ### ✨ Stream-based lazy i/o interface ✨ //! The [ElfStream] parser type takes a `std:: Read + Seek` (such as `std::fs::File`) where ranges of //! file contents are read lazily on-demand based on what the user wants to parse.