Repository: sharksforarms/deku (rust)

Issue:
Document the "logging" feature (was "Debugging faciility")
Hi,

I've written a couple of packet/bytecode decoders using Deku. It's great, but there's one thing I think could really help: some way to get runtime decoding information to help with debugging.

If you are decoding a large chunk of data in one go, then if parsing fails, the information you are often isn't really enough to figure out what's happening.

It would be useful to get some kind of trace out of Deku so that it is easier to hone in on the cause of an error.

Perhaps there could be some kind of `env_logger` support that causes deku to print what field it is decoding and the value it got?

Apologies if this already exists, but I don't see it.

Cheers

Pull request description:
Document the `logging` feature.
Fixes #362.

Patch:
diff --git a/deku-derive/src/macros/mod.rs b/deku-derive/src/macros/mod.rs
index eaae7a8..a039cab 100644
--- a/deku-derive/src/macros/mod.rs
+++ b/deku-derive/src/macros/mod.rs
@@ -117,7 +117,7 @@ fn gen_internal_field_ident(ident: &TokenStream) -> TokenStream {
     // Concat token: https://github.com/rust-lang/rust/issues/29599
     let span = ident.span();
     let s = ident.to_string();
-    let mut name = "__deku_".to_owned();
+    let mut name = "__deku___".to_owned();
     // If its a raw identifier, we must remove 'r#'
     name.push_str(s.strip_prefix("r#").unwrap_or(&s));
 
diff --git a/src/lib.rs b/src/lib.rs
index 39f341b..2e015d8 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -261,6 +261,28 @@ pub struct EncodedString {
 }
 ```
 
+# Debugging decoders with the `logging` feature.
+
+If you are having trouble understanding what causes a Deku parse error, you may find the `logging`
+feature useful.
+
+To use it, you will need to:
+ - enable the `logging` Cargo feature for your Deku dependency
+ - import the `log` crate and a compatible logging library
+
+For example, to log with `env_logger`, the dependencies in your `Cargo.toml` might look like:
+
+```text
+deku = { version = "*", features = ["logging"] }
+log = "*"
+env_logger = "*"
+```
+
+Then you'd call `env_logger::init()` or `env_logger::try_init()` prior to doing Deku decoding.
+
+Deku uses the `trace` logging level, so if you run your application with `RUST_LOG=trace` in your
+environment, you will see logging messages as Deku does its deserialising.
+
 */
 #![warn(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]


Test patch:
diff --git a/tests/test_struct.rs b/tests/test_struct.rs
index c620af5..b239ca4 100644
--- a/tests/test_struct.rs
+++ b/tests/test_struct.rs
@@ -113,6 +113,7 @@ fn test_named_struct() {
         pub vec_len: u8,
         #[deku(count = "vec_len")]
         pub vec_data: Vec<u8>,
+        pub rest: u8,
     }
 
     let test_data: Vec<u8> = [
@@ -128,6 +129,7 @@ fn test_named_struct() {
         0x02,
         0xBE,
         0xEF,
+        0xFF,
     ]
     .to_vec();
 
@@ -148,7 +150,8 @@ fn test_named_struct() {
                 }
             },
             vec_len: 0x02,
-            vec_data: vec![0xBE, 0xEF]
+            vec_data: vec![0xBE, 0xEF],
+            rest: 0xFF
         },
         ret_read
     );