From 34a1d301d88df75169e83fe1b01679cad9696176 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Fri, 7 Aug 2020 17:52:17 +0200 Subject: [PATCH 1/4] future-proof: remove `write!` from the public API instead only `#[derive(Format)]` is to be used to implement the `Format` trait --- book/src/SUMMARY.md | 2 +- book/src/format.md | 2 +- macros/src/lib.rs | 2 +- src/export.rs | 1 + src/lib.rs | 20 -------------------- 5 files changed, 4 insertions(+), 23 deletions(-) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 8b0987ed..96e7bbfa 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -10,7 +10,7 @@ - [Bitfields](./bitfields.md) - [Interned strings](./istr.md) - [#[derive(Format)]](./format.md) - - [write!](./write.md) + - [Filtering](./filtering.md) - [#[timestamp]](./timestamp.md) - [#[global_logger]](./global-logger.md) diff --git a/book/src/format.md b/book/src/format.md index bbeea309..5bda5b50 100644 --- a/book/src/format.md +++ b/book/src/format.md @@ -1,6 +1,6 @@ # `#[derive(Format)]` -The preferred way to implement the `Format` trait for a struct or enum is to use the `derive` attribute. +To implement the `Format` trait for a struct or enum use the `derive` attribute. ``` rust #[derive(Format)] diff --git a/macros/src/lib.rs b/macros/src/lib.rs index d61ea9ac..dc8a031a 100644 --- a/macros/src/lib.rs +++ b/macros/src/lib.rs @@ -241,7 +241,7 @@ pub fn format(ts: TokenStream) -> TokenStream { Data::Struct(ds) => { fs = ident.to_string(); let args = fields(&ds.fields, &mut fs, Kind::Struct); - exprs.push(quote!(binfmt::write!(f, #fs #(,#args)*);)) + exprs.push(quote!(binfmt::export::write!(f, #fs #(,#args)*);)) } Data::Union(..) => { diff --git a/src/export.rs b/src/export.rs index 16d1c32f..12341a7d 100644 --- a/src/export.rs +++ b/src/export.rs @@ -1,5 +1,6 @@ use crate::{Formatter, Str}; +pub use binfmt_macros::write; pub use common::Level; #[cfg(target_arch = "x86_64")] diff --git a/src/lib.rs b/src/lib.rs index 59899f8a..087a30c4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -97,26 +97,6 @@ pub use binfmt_macros::global_logger; /// ``` pub use binfmt_macros::timestamp; -/// Writes binfmt-formatted data to a [`Formatter`]. -/// -/// This works similarly to the `write!` macro in libcore. -/// -/// Usage: -/// -/// ``` -/// # use binfmt::{Format, Formatter}; -/// # struct S; -/// # impl Format for S { -/// # fn format(&self, formatter: &mut Formatter) { -/// # let arguments = 0u8; -/// binfmt::write!(formatter, "format string {:?}", arguments) -/// # } -/// # } -/// ``` -/// -/// [`Formatter`]: struct.Formatter.html -pub use binfmt_macros::write; - #[doc(hidden)] pub use binfmt_macros::winfo; #[doc(hidden)] // documented as the `Format` trait instead From 39f6f90b1e99e06b7e7e97b6f8640efcd596f22c Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Mon, 10 Aug 2020 09:44:59 +0200 Subject: [PATCH 2/4] fix tests --- src/lib.rs | 26 +------------------------- src/tests.rs | 4 ++-- 2 files changed, 3 insertions(+), 27 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 087a30c4..d367bfb6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -375,7 +375,7 @@ pub trait Write { /// /// # Example /// -/// It is recommended to `#[derive]` implementations of this trait: +/// It is required to `#[derive]` implementations of this trait: /// /// ``` /// use binfmt::Format; @@ -387,30 +387,6 @@ pub trait Write { /// sequence: u16, /// } /// ``` -/// -/// If necessary, implementations can also be written manually: -/// -/// ``` -/// use binfmt::{Format, Formatter}; -/// -/// struct Header { -/// source: u8, -/// destination: u8, -/// sequence: u16, -/// } -/// -/// impl Format for Header { -/// fn format(&self, fmt: &mut Formatter) { -/// binfmt::write!( -/// fmt, -/// "Header {{ source: {:u8}, destination: {:u8}, sequence: {:u16} }}", -/// self.source, -/// self.destination, -/// self.sequence -/// ) -/// } -/// } -/// ``` pub trait Format { /// Writes the binfmt representation of `self` to `fmt`. fn format(&self, fmt: &mut Formatter); diff --git a/src/tests.rs b/src/tests.rs index 8c6d870c..a77d95c4 100644 --- a/src/tests.rs +++ b/src/tests.rs @@ -36,7 +36,7 @@ fn trailing_comma() { #[allow(unreachable_code, unused_variables)] if false { let fmt: binfmt::Formatter = panic!(); - binfmt::write!(fmt, "test write",); - binfmt::write!(fmt, "test write {:?}", 0,); + binfmt::export::write!(fmt, "test write",); + binfmt::export::write!(fmt, "test write {:?}", 0,); } } From a29d0b0e9c832883b8d8d2aad8040d325c4823e0 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Mon, 10 Aug 2020 16:13:22 +0200 Subject: [PATCH 3/4] remove write.md --- book/src/write.md | 19 ------------------- 1 file changed, 19 deletions(-) delete mode 100644 book/src/write.md diff --git a/book/src/write.md b/book/src/write.md deleted file mode 100644 index be1c17a8..00000000 --- a/book/src/write.md +++ /dev/null @@ -1,19 +0,0 @@ -# write! - -When implementing the `Format` trait manually, the `write!` macro must be used to log the data. -This macro takes a `Formatter` as its first argument. - -``` rust -/// Packet configuration register 1 -pub struct PCNF1 { value: u32 } - -impl binfmt::Format for PCNF1 { - fn fmt(&self, f: &mut binfmt::Formatter) { - binfmt::write!( - f, - "PCNF1: {{ MAXLEN: {0:0..8}, STATLEN: {0:8..16}, BALEN: {0:16..19} }}", - self.value, - ); - } -} -``` From 6dd42b11e551dfffa8c9a33c6ae943aa6941b12b Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Mon, 10 Aug 2020 14:36:00 +0000 Subject: [PATCH 4/4] Update book/src/SUMMARY.md Co-authored-by: Jonas Schievink --- book/src/SUMMARY.md | 1 - 1 file changed, 1 deletion(-) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 96e7bbfa..4ba49616 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -10,7 +10,6 @@ - [Bitfields](./bitfields.md) - [Interned strings](./istr.md) - [#[derive(Format)]](./format.md) - - [Filtering](./filtering.md) - [#[timestamp]](./timestamp.md) - [#[global_logger]](./global-logger.md)