Skip to content

Commit fb796fc

Browse files
committed
Update guide
1 parent 7b8689c commit fb796fc

File tree

1 file changed

+40
-3
lines changed

1 file changed

+40
-3
lines changed

docs/guide/05-requests.md

+40-3
Original file line numberDiff line numberDiff line change
@@ -1988,12 +1988,12 @@ scope, and type. Catchers are similar to routes except in that:
19881988
2. Catchers are declared with the `catch` attribute.
19891989
3. Catchers are _registered_ with [`register()`] instead of [`mount()`].
19901990
4. Any modifications to cookies are cleared before a catcher is invoked.
1991-
// 5. Error catchers cannot invoke guards.
19921991
6. Error catchers should not fail to produce a response.
19931992
7. Catchers are scoped to a path prefix.
19941993

19951994
To declare a catcher for a given status code, use the [`catch`] attribute, which
1996-
takes a single integer corresponding to the HTTP status code to catch. For
1995+
takes a single integer corresponding to the HTTP status code to catch as the first
1996+
arguement. For
19971997
instance, to declare a catcher for `404 Not Found` errors, you'd write:
19981998

19991999
```rust
@@ -2004,7 +2004,8 @@ instance, to declare a catcher for `404 Not Found` errors, you'd write:
20042004
fn not_found() { /* .. */ }
20052005
```
20062006

2007-
TODO: See the catcher documentation
2007+
Cathers can include Request Guards, although forwards and errors work differently.
2008+
Forwards try the next catcher in the chain, while Errors trigger a `500` response.
20082009

20092010
```rust
20102011
# #[macro_use] extern crate rocket;
@@ -2033,6 +2034,42 @@ fn main() {
20332034
}
20342035
```
20352036

2037+
### Additional parameters.
2038+
2039+
Catchers provide two special parameters: `status` and `error`. `status` provides
2040+
access to the status code, which is primarily useful for [default catchers](#default-catchers).
2041+
`error` provides access the error values returned by a [`FromRequest`], [`FromData`] or [`FromParam`].
2042+
It only provides access to the most recent error, so if a route forwards, and another route is
2043+
attempted, only the error produced by the most recent attempt can be extracted. The `error` type
2044+
must implement [`Transient`], a non-static re-implementation of [`std::and::Any`]. (Almost) All errror
2045+
types returned by built-in guards implement [`Transient`], and can therefore be extracted. See
2046+
[the `Transient` derive](@api/master/rocket/catcher/derive.Transient.html) for more information
2047+
on implementing [`Transient`] for custom error types.
2048+
2049+
[`Transient`]: @api/master/rocket/catcher/trait.Transient.html
2050+
[`std::any::Any`]: https://doc.rust-lang.org/1.78.0/core/any/trait.Any.html
2051+
2052+
* The form::Errors type does not (yet) implement Transient
2053+
2054+
The function arguement must be a reference to the error type expected. See the
2055+
[error handling example](@git/master/examples/error-handling)
2056+
for a full application, including the route that generates the error.
2057+
2058+
```rust
2059+
# #[macro_use] extern crate rocket;
2060+
2061+
use rocket::Request;
2062+
use std::num::ParseIntError;
2063+
2064+
#[catch(default, error = "<error>")]
2065+
fn default_catcher(error: &ParseIntError) { /* .. */ }
2066+
2067+
#[launch]
2068+
fn rocket() -> _ {
2069+
rocket::build().register("/", catchers![default_catcher])
2070+
}
2071+
```
2072+
20362073
### Scoping
20372074

20382075
The first argument to `register()` is a path to scope the catcher under called

0 commit comments

Comments
 (0)