Merge #42

42: Add equivalent of dbg! macro r=adamgreig a=nickray

I think this would be quite useful. Thoughts?

Maybe it would be better for `dbg!` to be in core with somehow switchable implementation (semihosting, vcom, etc.), but I don't know how to approach that.

Added CHANGELOG also for the missing one for #39

Perhaps some more documentation is needed?


Co-authored-by: Nicolas Stalder <[email protected]>

Author: bors[bot]

CHANGELOG.md

@@ -5,6 +5,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+- Adds a feature to work around JLink quirks
+- Adds a dbg! macro using heprintln
+
 ## [v0.3.4] - 2019-04-22
 
 ### Fixed

src/lib.rs

@@ -123,6 +123,36 @@
 //! ```
 //! Output and monitoring proceed as in the above example.
 //!
+//! ## The `dbg!` macro
+//!
+//! Analogous to [`std::dbg`](https://doc.rust-lang.org/std/macro.dbg.html) the macro
+//! `dbg!` returns a given expression and prints it using `heprintln!` including context
+//! for quick and dirty debugging.
+//!
+//! Example:
+//!
+//! ```
+//! const UUID: *mut u32 = 0x0009_FC70 as *mut u32;
+//! dbg!(UUID);
+//! let mut uuid: [u32; 4] = [0; 4];
+//! for i in 0..4 {
+//!     dbg!(i);
+//!     uuid[i] = unsafe { dbg!(UUID.offset(i as isize).read_volatile()) };    }
+//! }
+//! ```
+//! outputs
+//! ```
+//! [examples/semihosting.rs:37] UUID = 0x0009fc70
+//! [examples/semihosting.rs:40] i = 0
+//! [examples/semihosting.rs:41] UUID.offset(i as isize).read_volatile() = 3370045464
+//! [examples/semihosting.rs:40] i = 1
+//! [examples/semihosting.rs:41] UUID.offset(i as isize).read_volatile() = 1426218275
+//! [examples/semihosting.rs:40] i = 2
+//! [examples/semihosting.rs:41] UUID.offset(i as isize).read_volatile() = 2422621116
+//! [examples/semihosting.rs:40] i = 3
+//! [examples/semihosting.rs:41] UUID.offset(i as isize).read_volatile() = 1044138593
+//! ```
+//!
 //! # Optional features
 //!
 //! ## `inline-asm`

src/macros.rs

@@ -85,3 +85,29 @@ macro_rules! heprintln {
         $crate::export::hstderr_fmt(format_args!(concat!($s, "\n"), $($tt)*))
     };
 }
+
+/// Macro that prints and returns the value of a given expression
+/// for quick and dirty debugging. Works exactly like `dbg!` in
+/// the standard library, replacing `eprintln` with `heprintln`.
+#[macro_export]
+macro_rules! dbg {
+    () => {
+        $crate::hprintln!("[{}:{}]", file!(), line!());
+    };
+    ($val:expr) => {
+        // Use of `match` here is intentional because it affects the lifetimes
+        // of temporaries - https://stackoverflow.com/a/48732525/1063961
+        match $val {
+            tmp => {
+                $crate::hprintln!("[{}:{}] {} = {:#?}",
+                    file!(), line!(), stringify!($val), &tmp);
+                tmp
+            }
+        }
+    };
+    // Trailing comma with single argument is ignored
+    ($val:expr,) => { $crate::dbg!($val) };
+    ($($val:expr),+ $(,)?) => {
+        ($($crate::dbg!($val)),+,)
+    };
+}