Macro rocket::uri

uri!() { /* proc-macro */ }

Type safe generation of route URIs.

The uri! macro creates a type-safe, URL safe URI given a route and values for the route's URI parameters. The inputs to the macro are the path to a route, a colon, and one argument for each dynamic parameter (parameters in <>) in the route's path and query.

For example, for the following route:

#[get("/person/<name>?<age>")]
fn person(name: String, age: Option<u8>) -> String {
    ...
}

A URI can be created as follows:

// with unnamed parameters, in route path declaration order
let mike = uri!(person: "Mike Smith", 28);
assert_eq!(mike.to_string(), "/person/Mike%20Smith?age=28");

// with named parameters, order irrelevant
let mike = uri!(person: name = "Mike", age = 28);
let mike = uri!(person: age = 28, name = "Mike");
assert_eq!(mike.to_string(), "/person/Mike?age=28");

// with a specific mount-point
let mike = uri!("/api", person: name = "Mike", age = 28);
assert_eq!(mike.to_string(), "/api/person/Mike?age=28");

// with unnamed values ignored
let mike = uri!(person: "Mike", _);
assert_eq!(mike.to_string(), "/person/Mike");

// with named values ignored
let mike = uri!(person: name = "Mike", age = _);
assert_eq!(mike.to_string(), "/person/Mike");

Grammar

The grammar for the uri! macro is:

uri := (mount ',')? PATH (':' params)?

mount = STRING
params := unnamed | named
unnamed := expr (',' expr)*
named := IDENT = expr (',' named)?
expr := EXPR | '_'

EXPR := a valid Rust expression (examples: `foo()`, `12`, `"hey"`)
IDENT := a valid Rust identifier (examples: `name`, `age`)
STRING := an uncooked string literal, as defined by Rust (example: `"hi"`)
PATH := a path, as defined by Rust (examples: `route`, `my_mod::route`)

Semantics

The uri! macro returns an Origin structure with the URI of the supplied route interpolated with the given values. Note that Origin implements Into<Uri> (and by extension, TryInto<Uri>), so it can be converted into a Uri using .into() as needed.

A uri! invocation only typechecks if the type of every value in the invocation matches the type declared for the parameter in the given route, after conversion with FromUriParam, or if a value is ignored using _ and the corresponding route type implements Ignorable.

Each value passed into uri! is rendered in its appropriate place in the URI using the UriDisplay implementation for the value's type. The UriDisplay implementation ensures that the rendered value is URI-safe.

If a mount-point is provided, the mount-point is prepended to the route's URI.

Conversion

The FromUriParam trait is used to typecheck and perform a conversion for each value passed to uri!. If a FromUriParam<P, S> implementation exists for a type T for part URI part P, then a value of type S can be used in uri! macro for a route URI parameter declared with a type of T in part P. For example, the following implementation, provided by Rocket, allows an &str to be used in a uri! invocation for route URI parameters declared as String:

impl<P: UriPart, 'a> FromUriParam<P, &'a str> for String { .. }

Ignorables

Query parameters can be ignored using _ in place of an expression. The corresponding type in the route URI must implement Ignorable. Ignored parameters are not interpolated into the resulting Origin. Path parameters are not ignorable.