Skip to content

Commit

Permalink
Document mounting multiple routes in guide.
Browse files Browse the repository at this point in the history
Also mention that a route's rank is displayed in brackets.

Closes rwf2#983.
Closes rwf2#981.
  • Loading branch information
SergioBenitez committed May 11, 2019
1 parent 7405033 commit 9d93d55
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 6 deletions.
14 changes: 10 additions & 4 deletions site/guide/3-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,8 +86,9 @@ fn main() {

The `mount` method takes as input:

1. A _base_ path to namespace a list of routes under.
2. A list of routes via the `routes!` macro.
1. A _base_ path to namespace a list of routes under, here, `"/hello"`.
2. A list of routes via the `routes!` macro: here, `routes![world]`, with
multiple routes: `routes![a, b, c]`.

This creates a new `Rocket` instance via the `ignite` function and mounts the
`world` route to the `"/hello"` path, making Rocket aware of the route. `GET`
Expand All @@ -108,11 +109,16 @@ mod other {
}
}

#[get("/hello")]
pub fn hello() -> &'static str {
"Hello, outside world!"
}

use other::world;

fn main() {
// error[E0425]: cannot find value `static_rocket_route_info_for_world` in this scope
rocket::ignite().mount("/hello", routes![world]);
rocket::ignite().mount("/hello", routes![hello, world]);
}
```

Expand All @@ -121,7 +127,7 @@ into the name of a structure generated by Rocket's code generation. The solution
is to refer to the route using a namespaced path instead:

```rust
rocket::ignite().mount("/hello", routes![other::world]);
rocket::ignite().mount("/hello", routes![hello, other::world]);
```

## Launching
Expand Down
16 changes: 14 additions & 2 deletions site/guide/4-requests.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,11 +190,18 @@ fn user_int(id: isize) -> T { ... }

#[get("/user/<id>", rank = 3)]
fn user_str(id: &RawStr) -> T { ... }

fn main() {
rocket::ignite()
.mount("/", routes![user, user_int, user_str])
.launch();
}
```

Notice the `rank` parameters in `user_int` and `user_str`. If we run this
application with the routes mounted at the root, requests to `/user/<id>` will
be routed as follows:
application with the routes mounted at the root path, as is done in `main`
above, requests to `/user/<id>` (such as `/user/123`, `/user/Bob`, and so on)
will be routed as follows:

1. The `user` route matches first. If the string at the `<id>` position is an
unsigned integer, then the `user` handler is called. If it is not, then the
Expand All @@ -206,6 +213,11 @@ be routed as follows:
3. The `user_str` route matches last. Since `<id>` is a always string, the
route always matches. The `user_str` handler is called.

! note: A route's rank appears in **[brackets]** during launch.

You'll also find a route's rank logged in brackets during application launch:
`GET /user/<id> [3] (user_str)`.

Forwards can be _caught_ by using a `Result` or `Option` type. For example, if
the type of `id` in the `user` function was `Result<usize, &RawStr>`, then `user`
would never forward. An `Ok` variant would indicate that `<id>` was a valid
Expand Down

0 comments on commit 9d93d55

Please sign in to comment.