Module format 

Building and parsing Key Expressions

A common issue in REST API is the association of meaning to sections of the URL, and respecting that API in a convenient manner. The same issue arises naturally when designing a KE space, and KeFormat was designed to help you with this, both in constructing and in parsing KEs that fit the formats you’ve defined.

kedefine also allows you to define formats at compile time, allowing a more performant, but more importantly safer and more convenient use of said formats, as the keformat and kewrite macros will be able to tell you if you’re attempting to set fields of the format that do not exist.

The format syntax

KE formats are defined following a syntax that extends the keyexpr syntax. In addition to existing chunk types, KE formmats support “specification” chunks. These chunks must follow the one of the following syntaxes: ${id:pattern}, ${id:pattern#default}, $#{id:pattern}#, or $#{id:pattern#default}#, where:

• id is the chunk identifier: it cannot contain the : character, and is used to name the chunk in accessors.
• pattern must be a valid KE (and therefore cannot contain #) and defines the range of values that the chunk may adopt.
• default (optional) is used as the chunk value when formatting if the builder wasn’t supplied with a value for id.

Formatting

To use a format to build a Key Expression, its formatter must be constructed.

A formatter functions like as an id-value map which can be KeFormatter::build into a OwnedKeyExpr once all specs have a value.

The formatter will notably prevent you from setting values for a spec that isn’t included by its pattern.

Parsing

KeFormat can also be used to parse any keyexpr that intersects with it, using KeFormat::parse.

The parser will then assign subsections of the keyexpr to each spec, and the resulting Parsed result can then be queried for each spec’s assigned value.

Specs are considered greedy and evaluated left-to-right: if your format would allow ambiguous parsings, chunks will be consumed by the leftmost specs first. For example ${a:**}/-/${b:**} parsing hey/-/-/there would assign hey/- to a and there to b, (even though you might have expected a to only consume hey and b to consume the remaining -/there).

A good way to avoid ambiguities when working with formats that contain multiple ** specs is to separate such specs using verbatim chunks (chunks that start with an @), as ** is incapable of consuming these chunks.

Modules

macro_support

Structs

Iter

KeFormat

Building and parsing Key Expressions

KeFormatter

An active formatter for a KeFormat.

OwnedKeFormat

A KeFormat that owns its format-string.

Parsed

Segment

Enums

FormatSetError

Traits

IKeFormatStorage