diff --git a/core/lib/tests/guide.rs b/core/lib/tests/guide.rs deleted file mode 100644 index b352d9f8..00000000 --- a/core/lib/tests/guide.rs +++ /dev/null @@ -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; -} - diff --git a/site/guide/10-pastebin.md b/site/guide/10-pastebin.md index dbb0bb16..69116fa4 100644 --- a/site/guide/10-pastebin.md +++ b/site/guide/10-pastebin.md @@ -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 = "")] -fn upload(paste: Data) -> Result> { +fn upload(paste: Data) -> Result { # 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 = "")] -fn upload(paste: Data) -> Result> { +fn upload(paste: Data) -> Result { 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> { 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 { 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 `` 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; diff --git a/site/guide/3-overview.md b/site/guide/3-overview.md index b8f8d2ca..33db0fc0 100644 --- a/site/guide/3-overview.md +++ b/site/guide/3-overview.md @@ -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() {} diff --git a/site/guide/4-requests.md b/site/guide/4-requests.md index 0198bb19..29ca8223 100644 --- a/site/guide/4-requests.md +++ b/site/guide/4-requests.md @@ -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` 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 { +fn user_id(mut cookies: Cookies) -> Option { 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 = "")] -fn upload(data: Data) -> Result> { - Ok(data.stream_to_file("/tmp/upload.txt").map(|n| n.to_string())?) +fn upload(data: Data) -> Result { + 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; diff --git a/site/guide/5-responses.md b/site/guide/5-responses.md index 7a95bace..63f56937 100644 --- a/site/guide/5-responses.md +++ b/site/guide/5-responses.md @@ -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, Debug> { - Ok(UnixStream::connect("/path/to/my/socket").map(Stream::from)?) +fn stream() -> Result, 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) { /* .. */ } 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/?")] @@ -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>` is expected: ```rust -# #![feature(proc_macro_hygiene)] +# #![feature(proc_macro_hygiene, decl_macro)] # #[macro_use] extern crate rocket; # use rocket::http::RawStr; diff --git a/site/guide/6-state.md b/site/guide/6-state.md index e1c63ca9..51292b54 100644 --- a/site/guide/6-state.md +++ b/site/guide/6-state.md @@ -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) -> 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` 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 { - let hit_count_state = try_outcome!(req.guard::>()); + let hit_count_state = req.guard::>()?; 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() {} diff --git a/site/guide/8-testing.md b/site/guide/8-testing.md index 784684de..01532738 100644 --- a/site/guide/8-testing.md +++ b/site/guide/8-testing.md @@ -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("/")] diff --git a/site/guide/9-configuration.md b/site/guide/9-configuration.md index c1ae792d..cdda9654 100644 --- a/site/guide/9-configuration.md +++ b/site/guide/9-configuration.md @@ -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};