Introducing keformat!

[p-avital]

To help users with processing Key Expressions, here come KeFormats.

examples/examples/z_formats shows how zenoh-rs users are expected to use the keformat macro:

• keformat!($spec: lit, $module: ident) will declare mod $module which contain all of the formatting utilities wrapped in helpers that provide accessors based on the $spec:
  • Format is a ZST representing this exact format.
  • formatter() -> Formatter constructs a formatter with setters for each field of the spec.
  • parser<'s>(&'s keyexpr) -> ZResult<Parsed<'s>> parses the keyexpr into an annotated parsing result, with getters for each field of the spec.
• keformat!($formatter: expr, $($field: ident [ = $value: expr])*) works on formatters constructed by the previously mentioned formatter() function. It sets each $field in the formatter, returning a ZResult<&mut Formatter> that will error if $value doesn't fit $field's spec. If no $value is provided, the macro will assume a $field variable exists and use it as $value. The macro will detect attempt to set fields that don't exist.

KeFormats can also be constructed at runtime, and the formatters and parse-results may be used respectively like read-only and write-only maps. APIs for other languages may be built on to of these.

TODOs:

• More documentation
• C and Python APIs

[p-avital]

This PR introduces a very weird bug with rust-analyzer: rust-lang/rust-analyzer#14190

I propose we refrain on merging it to avoid users having a subpar experience with the macros and dismissing the feature until that issue is fixed.

Can someone on the team with a Mac let me know if they're also affected (proc_macro build fails in RA only, I've confirmed it on Linux and Windows).

[Mallets]

I've just cloned the repo and on my Mac (Intel i5 - Ventura 13.1) I don't see any problem.

• rustc 1.67.1
• rust-analyzer 0.3.1418

[Mallets]

Approving this pull request.
As next step it would be nice to create a zenoh-keyexpr crate where all type definitions, macros, utils (e.g. ketree), etc. are grouped. I fill that too many things are pushed into zenoh-protocol now. The issue #445 has been created to keep track of this.