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 | 66 +++++++++++++++++++++++++++--------------------------- src/lib.rs | 66 +++++++++++++++++++++++++++--------------------------- 2 files changed, 66 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 36d162b..27d94e8 100644 --- a/README.md +++ b/README.md @@ -11,30 +11,27 @@ The `elf` crate provides a pure-safe-rust interface for reading ELF object files # Capabilities -### ✨ 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 -trust in rust's memory safety guarantees without also having to trust this -library developer as having truly been "right" in why some unsafe block was -safe. 💃 - -Note: I'd love to see this crate be enhanced further once rust provides safe transmutes. - -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! +### ✨ 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 @@ -42,6 +39,24 @@ that yield stack allocated rust types, or lazily parsing tables that only parse 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 +trust in rust's memory safety guarantees without also having to trust this +library developer as having truly been "right" in why some unsafe block was +safe. 💃 + +Note: I'd love to see this crate be enhanced further once rust provides safe transmutes. + +See: + ### ✨ 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,30 +2,27 @@ //! //! # Capabilities //! -//! ### ✨ 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 -//! trust in rust's memory safety guarantees without also having to trust this -//! library developer as having truly been "right" in why some unsafe block was -//! safe. 💃 -//! -//! Note: I'd love to see this crate be enhanced further once rust provides safe transmutes. -//! -//! 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! //! +//! ### ✨ 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 @@ -33,6 +30,24 @@ //! 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 +//! trust in rust's memory safety guarantees without also having to trust this +//! library developer as having truly been "right" in why some unsafe block was +//! safe. 💃 +//! +//! Note: I'd love to see this crate be enhanced further once rust provides safe transmutes. +//! +//! See: +//! //! ### ✨ 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.