consortium-log-macros 0.6.0

Format-string normalization macros for consortium-log.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

# consortium-log-macros

Internal format-string normalization for [`consortium-log`](../consortium-log).

> **Implementation detail.** Depend on `consortium-log`. This crate's API is not
> stable and its single macro is not meant to be called directly.

## What it does

`consortium-log` forwards one call site to two backends that do not agree about
format strings. Rust's implicit captures —

```rust,ignore
trace!("channel {name} lowered")
```

— work with `tracing`, which is built on `core::fmt`. They do **not** work with
`defmt`, which parses format strings itself and has no notion of pulling `name`
out of the enclosing scope.

Rather than banning the nicer syntax in shared code, `expand_captures` rewrites it
into the indexed form both backends accept:

```text
trace!("channel {name} lowered")
  →  __defmt!(trace, "channel {0} lowered", name)
```

Explicit positional arguments keep their indices; captures are appended after
them, and a name used twice reuses one index.

## Why the callback is an input

The macro takes **three parenthesized groups** — callback path, log level, and the
original log arguments — and re-emits an invocation of that callback.

Threading the callback path _through_ the macro is what preserves
`consortium-log`'s `$crate` hygiene. The facade passes `$crate::__defmt`, so the
expansion names the facade's own dispatch macro regardless of which crate the log
call was written in. A proc-macro cannot synthesize a `$crate` token of its own,
so the path has to arrive as data.

## What is deliberately left alone

Two inputs are forwarded byte-for-byte rather than rewritten:

- **Anything that fails to parse** as a format string plus arguments. Emitting the
  original tokens lets the backend produce the real diagnostic, pointing at the
  user's call site instead of at this rewrite.
- **Named arguments** (`name = expression`). Those already mean something to Rust
  and to `tracing`'s structured fields, so `{name}` alongside them is not an
  implicit capture and must not be treated as one.

## Testing

```bash
cargo test -p consortium-log-macros
cargo test -p consortium-log --features defmt      # end-to-end through the facade
cargo test -p consortium-log --features tracing
```

## License

Apache-2.0. See [LICENSE](../../LICENSE).