Fix guide examples for 0.4.

This commit is contained in:
Sergio Benitez 2020-02-27 15:35:56 -08:00
parent 878a73b6f0
commit 60cba26f65
8 changed files with 85 additions and 52 deletions

View File

@ -1,14 +0,0 @@
#![feature(proc_macro_hygiene)]
#![feature(external_doc)]
#[allow(dead_code)]
mod test_guide {
#[doc(include = "../../../site/guide/2-getting-started.md")]
pub struct GuideGettingStart;
/// ```rust
/// assert_eq!(0, 1);
/// ```
struct Foo;
}

View File

@ -79,6 +79,7 @@ of the form `GET /`. We declare the route and its handler by adding the `index`
function below to `src/main.rs`:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
#[get("/")]
@ -109,7 +110,7 @@ Remember that routes first need to be mounted before Rocket dispatches requests
to them. To mount the `index` route, modify the main function so that it reads:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# #[get("/")] fn index() { }
@ -233,14 +234,14 @@ you should attempt to write the route yourself. Here's a hint: a possible route
and handler signature look like this:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
use rocket::Data;
use rocket::response::Debug;
#[post("/", data = "<paste>")]
fn upload(paste: Data) -> Result<String, Debug<std::io::Error>> {
fn upload(paste: Data) -> Result<String, std::io::Error> {
# unimplemented!()
/* .. */
}
@ -257,6 +258,7 @@ Your code should:
Here's our version (in `src/main.rs`):
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -270,10 +272,9 @@ Here's our version (in `src/main.rs`):
use std::path::Path;
use rocket::Data;
use rocket::response::Debug;
#[post("/", data = "<paste>")]
fn upload(paste: Data) -> Result<String, Debug<std::io::Error>> {
fn upload(paste: Data) -> Result<String, std::io::Error> {
let id = PasteId::new(3);
let filename = format!("upload/{id}", id = id);
let url = format!("{host}/{id}\n", host = "http://localhost:8000", id = id);
@ -287,7 +288,7 @@ fn upload(paste: Data) -> Result<String, Debug<std::io::Error>> {
Ensure that the route is mounted at the root path:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# #[get("/")] fn index() {}
@ -335,6 +336,7 @@ as a **404** error, which is exactly what we want to return when the requested
paste doesn't exist.
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
use std::fs::File;
@ -350,7 +352,7 @@ fn retrieve(id: &RawStr) -> Option<File> {
Make sure that the route is mounted at the root path:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# #[get("/")] fn index() {}
@ -421,6 +423,7 @@ Rocket will then ensure that `<id>` represents a valid `PasteId` before calling
the `retrieve` route, preventing attacks on the `retrieve` route:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# use std::fs::File;

View File

@ -62,7 +62,7 @@ handler, with the set of parameters to match against. A complete route
declaration looks like this:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
#[get("/world")] // <- route attribute
@ -82,7 +82,7 @@ constructing routes.
Before Rocket can dispatch requests to a route, the route needs to be _mounted_:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# #[get("/world")]
@ -113,7 +113,7 @@ When a route is declared inside a module other than the root, you may find
yourself with unexpected errors when mounting:
```rust,compile_fail
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
mod other {
@ -141,7 +141,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
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# #[get("/")] pub fn hello() {}

View File

@ -5,6 +5,7 @@ about a request in order for the route's handler to be called. You've already
seen an example of this in action:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -39,6 +40,7 @@ against. For example, the following attribute will match against `POST` requests
to the root path:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -75,6 +77,7 @@ names in a route's path. For example, if we want to say _Hello!_ to anything,
not just the world, we can declare a route like so:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -99,6 +102,7 @@ the full list of provided implementations, see the [`FromParam` API docs].
Here's a more complete route to illustrate varied usage:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -145,6 +149,7 @@ As an example, the following route matches against all paths that begin with
`/page/`:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -160,6 +165,7 @@ The path after `/page/` will be available in the `path` parameter. The
this, a safe and secure static file server can be implemented in 4 lines:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -190,6 +196,7 @@ Let's take a closer look at the route attribute and signature pair from a
previous example:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -209,7 +216,7 @@ be manually set with the `rank` attribute. To illustrate, consider the following
routes:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# use rocket::http::RawStr;
@ -291,7 +298,7 @@ Query segments can be declared static or dynamic in much the same way as path
segments:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -333,6 +340,7 @@ parameter is missing in a request, `None` will be provided as the value. A
route using `Option<T>` looks as follows:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -371,6 +379,7 @@ these types allow you to use a structure with named fields to automatically
validate query/form parameters:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -391,6 +400,7 @@ sets `id` to `100` and `user` to `User { name: "sandal", account: 400 }`. To
catch forms that fail to validate, use a type of `Option` or `Result`:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -426,7 +436,7 @@ For instance, the following dummy handler makes use of three request guards,
named in the route attribute.
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -455,7 +465,7 @@ headers, you might create an `ApiKey` type that implements `FromRequest` and
then use it as a request guard:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
# type ApiKey = rocket::http::Method;
@ -537,7 +547,7 @@ following three routes, each leading to an administrative control panel at
`/admin`:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -582,6 +592,7 @@ and remove cookies. Because `Cookies` is a request guard, an argument of its
type can simply be added to a handler:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
use rocket::http::Cookies;
@ -618,7 +629,7 @@ methods are suffixed with `_private`. These methods are: [`get_private`],
[`add_private`], and [`remove_private`]. An example of their usage is below:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -627,7 +638,7 @@ use rocket::response::{Flash, Redirect};
/// Retrieve the user's ID, if any.
#[get("/user_id")]
fn user_id(cookies: Cookies) -> Option<String> {
fn user_id(mut cookies: Cookies) -> Option<String> {
cookies.get_private("user_id")
.map(|cookie| format!("User ID: {}", cookie.value()))
}
@ -698,6 +709,7 @@ due to the offending handler. A common error is to have a handler that uses a
`Cookies`, as so:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
# use rocket::http::Cookies;
@ -713,6 +725,7 @@ guard will retrieve an instance of `Cookies` when one already exists for
guards:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
# use rocket::http::Cookies;
@ -727,6 +740,7 @@ When using request guards that modify cookies on-demand, such as
`Cookies` instance before accessing the `FlashMessage`.
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -763,6 +777,7 @@ When a route indicates a payload-supporting method (`PUT`, `POST`, `DELETE`, and
As an example, consider the following route:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -789,6 +804,7 @@ route.
As an example, consider the following route:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
# type User = ();
@ -813,7 +829,7 @@ an argument in the handler. The argument's type must implement the [`FromData`]
trait. It looks like this, where `T` is assumed to implement `FromData`:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# type T = rocket::data::Data;
@ -835,6 +851,7 @@ checkbox, and `description`, a text field. You can easily handle the form
request in Rocket as follows:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -862,6 +879,7 @@ returned. As before, a forward or failure can be caught by using the `Option`
and `Result` types:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -897,6 +915,7 @@ is also required to implement `FromForm`. For instance, we can simply replace
`Form` with `LenientForm` above to get lenient parsing:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -929,6 +948,7 @@ Since `type` is a reserved keyword in Rust, it cannot be used as the name of a
field. To get around this, you can use field renaming as follows:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -951,6 +971,7 @@ a field in a form structure, and implement `FromFormValue` so that it only
validates integers over that age:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -981,6 +1002,7 @@ valid form for that structure. You can use `Option` or `Result` types for fields
to catch parse failures:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -995,6 +1017,7 @@ struct Person {
The `FromFormValue` trait can also be derived for enums with nullary fields:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -1021,6 +1044,7 @@ Handling JSON data is no harder: simply use the
[`rocket_contrib`]:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# extern crate rocket_contrib;
# fn main() {}
@ -1052,15 +1076,15 @@ possible via the [`Data`](@api/rocket/data/struct.Data.html)
type:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
use rocket::Data;
use rocket::response::Debug;
#[post("/upload", format = "plain", data = "<data>")]
fn upload(data: Data) -> Result<String, Debug<std::io::Error>> {
Ok(data.stream_to_file("/tmp/upload.txt").map(|n| n.to_string())?)
fn upload(data: Data) -> Result<String, std::io::Error> {
data.stream_to_file("/tmp/upload.txt").map(|n| n.to_string())
}
```
@ -1104,6 +1128,7 @@ status code to catch. For instance, to declare a catcher for `404 Not Found`
errors, you'd write:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -1117,6 +1142,7 @@ As with routes, the return type (here `T`) must implement `Responder`. A
concrete implementation may look like:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -1135,7 +1161,7 @@ mounting a route: call the [`register()`] method with a list of catchers via the
looks like:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# use rocket::Request;

View File

@ -36,6 +36,7 @@ the wrapped `Responder`. As an example, the [`Accepted`] type sets the status to
`202 - Accepted`. It can be used as follows:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -53,6 +54,7 @@ Content-Type of `&'static str` to JSON, you can use the [`content::Json`] type
as follows:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
use rocket::response::content;
@ -90,6 +92,7 @@ returning a [`Status`] directly. For instance, to forward to the catcher for
**406: Not Acceptable**, you would write:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -124,6 +127,7 @@ responder, headers, or sets a custom status or content-type, `Responder` can be
automatically derived:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -175,6 +179,7 @@ to `text/plain`. To get a taste for what such a `Responder` implementation looks
like, here's the implementation for `String`:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -202,6 +207,7 @@ Because of these implementations, you can directly return an `&str` or `String`
type from a handler:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
#[get("/string")]
@ -223,6 +229,7 @@ known until process-time whether content exists. For example, because of
found and a `404` when a file is not found in just 4, idiomatic lines:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -248,6 +255,7 @@ file server, for instance, we might wish to provide more feedback to the user
when a file isn't found. We might do this as follows:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -301,17 +309,18 @@ this easy. The `Stream` type can be created from any `Read` type. For example,
to stream from a local Unix stream, we might write:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
# #[cfg(unix)]
# mod test {
use std::os::unix::net::UnixStream;
use rocket::response::{Stream, Debug};
use rocket::response::Stream;
#[get("/stream")]
fn stream() -> Result<Stream<UnixStream>, Debug<std::io::Error>> {
Ok(UnixStream::connect("/path/to/my/socket").map(Stream::from)?)
fn stream() -> Result<Stream<UnixStream>, std::io::Error> {
UnixStream::connect("/path/to/my/socket").map(Stream::from)
}
# }
```
@ -329,6 +338,7 @@ As an example, to respond with the JSON value of a `Task` structure, we might
write:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# #[macro_use] extern crate rocket_contrib;
# fn main() {}
@ -363,6 +373,7 @@ Rocket includes built-in templating support that works largely through a
for instance, you might return a value of type `Template` as follows:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# #[macro_use] extern crate rocket_contrib;
# fn main() {}
@ -390,7 +401,7 @@ fairings. To attach the template fairing, simply call
`.attach(Template::fairing())` on an instance of `Rocket` as follows:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# use rocket_contrib::templates::Template;
@ -451,6 +462,7 @@ methods such as [`Redirect::to()`].
For example, given the following route:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -461,7 +473,7 @@ fn person(name: String, age: Option<u8>) { /* .. */ }
URIs to `person` can be created as follows:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# #[get("/person/<name>?<age>")]
@ -528,7 +540,7 @@ in the query part of a URI, derive using [`UriDisplayQuery`].
As an example, consider the following form structure and route:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -550,7 +562,7 @@ automatically generated, allowing for URIs to `add_user` to be generated using
`uri!`:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# use rocket::http::RawStr;
@ -624,7 +636,7 @@ Conversions _nest_. For instance, a value of type `T` can be supplied when a
value of type `Option<Form<T>>` is expected:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# use rocket::http::RawStr;

View File

@ -70,6 +70,7 @@ the managed state. For example, we can retrieve and respond with the current
`HitCount` in a `count` route as follows:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -88,6 +89,7 @@ fn count(hit_count: State<HitCount>) -> String {
You can retrieve more than one `State` type in a single route as well:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -117,6 +119,7 @@ implementation. To do so, simply invoke `State<T>` as a guard using the
[`Request::guard()`] method.
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
@ -131,7 +134,7 @@ impl<'a, 'r> FromRequest<'a, 'r> for T {
type Error = ErrorType;
fn from_request(req: &'a Request<'r>) -> request::Outcome<T, Self::Error> {
let hit_count_state = try_outcome!(req.guard::<State<HitCount>>());
let hit_count_state = req.guard::<State<HitCount>>()?;
let current_count = hit_count_state.count.load(Ordering::Relaxed);
/* ... */
# request::Outcome::Success(T)
@ -158,6 +161,7 @@ As an example, consider the following request guard implementation for
integer ID per request:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# fn main() {}
# use std::sync::atomic::{AtomicUsize, Ordering};
@ -289,6 +293,7 @@ Finally, attach the fairing returned by `YourType::fairing()`, which was
generated by the `#[database]` attribute:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
#[macro_use] extern crate rocket_contrib;
@ -310,6 +315,7 @@ That's it! Whenever a connection to the database is needed, use your type as a
request guard:
```rust
# #![feature(decl_macro)]
# #[macro_use] extern crate rocket;
# #[macro_use] extern crate rocket_contrib;
# fn main() {}

View File

@ -82,7 +82,7 @@ These methods are typically used in combination with the `assert_eq!` or
`assert!` macros as follows:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# use std::io::Cursor;
@ -117,7 +117,7 @@ To solidify an intuition for how Rocket applications are tested, we walk through
how to test the "Hello, world!" application below:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
#[get("/")]
@ -197,7 +197,7 @@ Here, we want to ensure two things:
We do this by checking the `Response` object directly:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
# #[get("/")]
@ -217,7 +217,7 @@ assert_eq!(response.body_string(), Some("Hello, world!".into()));
That's it! Altogether, this looks like:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
#[get("/")]

View File

@ -189,7 +189,7 @@ The following code will:
3. Retrieve the parameter in an `assets` route via the `State` guard.
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
use std::path::{Path, PathBuf};
@ -258,7 +258,7 @@ In addition to using environment variables or a config file, Rocket can also be
configured using the [`rocket::custom()`] method and [`ConfigBuilder`]:
```rust
# #![feature(proc_macro_hygiene)]
# #![feature(proc_macro_hygiene, decl_macro)]
# #[macro_use] extern crate rocket;
use rocket::config::{Config, Environment};