decoder: add Frame::fragments() and Frame::display_fragments()

[darkwater]

One cool possibility with defmt is a log viewer that can do more than just display static text, eg. change number representations on the fly. These two methods should make doing something like that a bit easier.

Copying from the docs I put on display_fragments():

---

Returns an iterator over the fragments of the message contained in this log frame.

Collecting this into a String will yield the same result as Self::display_message, but
this iterator will yield interpolated fragments on their own. For example, the log:

defmt::info!("foo = {}, bar = {}", 1, 2);

Will yield the following strings:

vec!["foo = ", "1", ", bar = ", "2"]

Note that nested fragments will not yield separately:

defmt::info!("foo = {}", Foo { bar: 1 });

Will yield:

vec!["foo = ", "Foo { bar: 1 }"]

This iterator yields the same fragments as Self::fragments, so you can zip them
together to get both representations.

---

This is quite limited in that it doesn't go into nested fragments, but could already enable some limited extra functionality with minimal effort.

Haven't tested on an actual project yet, intend to do that tomorrow.

[darkwater]

Oh, forgot to mention, yes I tested this by making a prototype structured logging forwarder, where you can:

defmt::info!("something happened action={}", "foo bar");

and it'll parse "action" as a key, and "foo bar" as a value, sort of escaping the value.

[jonathanpallant]

Thank you for your proposed changes. I had a quick look and they seem OK to me, but I've asked my colleagues for a second opinion.

[jonathanpallant]

Rather than collect these into a single String, it might be better to .join('|') them, so we can verify the splits between the components are where we expect.

[jonathanpallant]

That, or, assert_eq! against a &[&'static str], like &["x=", "None"] or something.

[darkwater]

The idea was to just make sure the output is the same as display(), but yeah that would be better anyway. Done

[jonathanpallant]

This is a new public type, so it needs documenting.

(Also I should #[deny(missing_docs)]...)

[darkwater]

Done (just a summary and a link to display_fragments())

[jonathanpallant]

A couple more observations on a second pass, but I checked the diff in detail with a better diff tool, and most of the 'changed' code is unchanged - it's just de-indented, slightly reformatted thanks to the extra width it now has, and a reference can be dropped because the new function is passed a reference. Functionally it appears to do the same thing as before.

[darkwater]

I just noticed that DisplayFragments and it's already existing neighbours eg. DisplayMessage aren't actually public, since mod frame isn't public. These types are returned by public methods on Frame, so would it be helpful to expose these types?

[jonathanpallant]

I tried to make use of this in defmt-print, so it could print JSON containing an array of fragments rather than a single string, but ran into issues in how defmt-print actually uses the 'log' crate and so it's not very easy to print fragments. I think that crate needs some re-architecting.

Do you have an example of where you found this API useful?

[darkwater]

I'm currently using it for what I mentioned above:

defmt::info!("something happened action={}", "foo bar");

hooks into my structured logging, where action=foo bar is added as a structured field.

Another use case I'm thinking about is using defmt as a transport for a sort of memory inspection tool, eg.:

defmt::debug!("!buffer uart_rx {=[u8]}", &uart_rx_buf);

My toolchain could then pick up those messages and show buffer contents separately from logs. I already have a prototype that does something similar that currently just parses the [12, ab] strings.

[jonathanpallant]

What tool did you use to collect and render the defmt logs?

[darkwater]

I’m using defmt-decoder directly in a bespoke toolchain for a closed source project, as well as on a server component to store logs in production.

[Hoverbear]

This looks good, the new APIs look useful, it cleans some stuff up good, and seems well done. I don't see any API breaks.

Thank you for this. :)

The PR suggests there is a changelog conflict, if you'd like to fix it, I'll re-approve right away. Else I think we can do it when we merge.

[darkwater]

Fixed it