@@ -1988,12 +1988,12 @@ scope, and type. Catchers are similar to routes except in that:
1988
1988
2 . Catchers are declared with the ` catch ` attribute.
1989
1989
3 . Catchers are _ registered_ with [ ` register() ` ] instead of [ ` mount() ` ] .
1990
1990
4 . Any modifications to cookies are cleared before a catcher is invoked.
1991
- // 5. Error catchers cannot invoke guards.
1992
1991
6 . Error catchers should not fail to produce a response.
1993
1992
7 . Catchers are scoped to a path prefix.
1994
1993
1995
1994
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
1997
1997
instance, to declare a catcher for ` 404 Not Found ` errors, you'd write:
1998
1998
1999
1999
``` rust
@@ -2004,7 +2004,8 @@ instance, to declare a catcher for `404 Not Found` errors, you'd write:
2004
2004
fn not_found () { /* .. */ }
2005
2005
```
2006
2006
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.
2008
2009
2009
2010
``` rust
2010
2011
# #[macro_use] extern crate rocket;
@@ -2033,6 +2034,42 @@ fn main() {
2033
2034
}
2034
2035
```
2035
2036
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
+
2036
2073
### Scoping
2037
2074
2038
2075
The first argument to ` register() ` is a path to scope the catcher under called
0 commit comments