Macro hyperbole::uri

macro_rules! uri {
    ($( $token:tt )*) => { ... };
}

Expands to a well-typed uri specification.

Routable segments

A uri! invocation may contain any number of static or dynamic segments separated by forward slashes. Static segments are literal strings and must be matched verbatim when a request comes in, while dynamic segments will match regardless of their content and are parsed (via a FromStr impl) after a route has been matched.

Parsing errors of dynamic segments will short-circuit a request, responding with an error determined by the FromStr::Err.

use hyperbole::uri;

// /
uri![];

// /one
uri!["one"];
// /two
uri!["one" / "two"];

// /:one
uri![one: u32];
// /:one/:two
uri![one: u32 / two: f64];

// /one/:two/three
uri!["one" / two: String / "three"];

A catch-all segment may optionally be added to the end of a uri! to match the rest of an incoming request's path with the same syntax as a dynamic segment, except preceded by a *. Like dynamic segments, a name and type must be specified, where the type implements FromStr.

use hyperbole::uri;

// /*any
uri![*any: String];

// /one/*everything_else
uri!["one" / *everything_else: String];

Within an App, routes must be uniquely determinable. That is, for any request, exactly one or zero routes will match, always. Ambiguous routes are not permitted.

Query parameters

Query parameters may be added to the end of a uri!, but do not affect routing. They are similar to dynamic segments in that they are parsed by a FromStr impl after a request matches a route.

They may be specified as a comma separated list of name: type pairs preceded by a ? after all static, dynamic, and catch-all segments. The order of query parameters does not matter, but duplicates are not permitted.

If a specified query parameter is not present in a request uri that otherwise matches the path specification, the FromStr impl will receive an empty string "" during parsing.

use hyperbole::uri;

uri![? p1: u8];
uri!["abc" ? p1: u8, p2: String];
uri!["one" / two: u32 / *three: String ? param: usize, another: f64];

Interaction with request scoped state

Any parameters in a uri! invocation are exposed as named fields.

After parsing completes, said fields will be merged with any other request scoped state.