From feadb4dd16bded8cacf123df111dca17d5d9509f Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Sat, 27 Mar 2021 16:25:39 -0700 Subject: [PATCH] Prefer '&str' in doc examples. --- README.md | 2 +- core/codegen/src/bang/test_guide.rs | 6 +++- site/guide/3-overview.md | 1 + site/guide/4-requests.md | 50 ++++++++++++++--------------- site/guide/5-responses.md | 8 ++--- site/index.toml | 20 ++++++------ site/tests/src/lib.rs | 2 +- 7 files changed, 47 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 7be3b6af..98ec71ee 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ extensibility, and speed. #[macro_use] extern crate rocket; #[get("//")] -fn hello(name: String, age: u8) -> String { +fn hello(name: &str, age: u8) -> String { format!("Hello, {} year old named {}!", age, name) } diff --git a/core/codegen/src/bang/test_guide.rs b/core/codegen/src/bang/test_guide.rs index e442abab..ad2a609e 100644 --- a/core/codegen/src/bang/test_guide.rs +++ b/core/codegen/src/bang/test_guide.rs @@ -26,7 +26,7 @@ fn entry_to_tests(root_glob: &LitStr) -> Result, Box .replace(|c| c == '-' || c == '.', "_")) .ok_or_else(|| "invalid file name")?; - let ident = Ident::new(&name, root_glob.span()); + let ident = Ident::new(&name.to_lowercase(), root_glob.span()); let full_path = Path::new(&manifest_dir).join(&path).display().to_string(); tests.push(quote_spanned!(root_glob.span() => mod #ident { @@ -36,5 +36,9 @@ fn entry_to_tests(root_glob: &LitStr) -> Result, Box )); } + if tests.is_empty() { + return Err(format!("glob '{}' evaluates to 0 files", full_glob).into()); + } + Ok(tests) } diff --git a/site/guide/3-overview.md b/site/guide/3-overview.md index 59d79206..fc29bc32 100644 --- a/site/guide/3-overview.md +++ b/site/guide/3-overview.md @@ -272,6 +272,7 @@ Rocket makes it easy to use `async/await` in routes. ```rust # #[macro_use] extern crate rocket; use rocket::tokio::time::{sleep, Duration}; + #[get("/delay/")] async fn delay(seconds: u64) -> String { sleep(Duration::from_secs(seconds)).await; diff --git a/site/guide/4-requests.md b/site/guide/4-requests.md index fc34045f..b7e0aa74 100644 --- a/site/guide/4-requests.md +++ b/site/guide/4-requests.md @@ -100,7 +100,7 @@ Here's a more complete route to illustrate varied usage: # fn main() {} #[get("/hello///")] -fn hello(name: String, age: u8, cool: bool) -> String { +fn hello(name: &str, age: u8, cool: bool) -> String { if cool { format!("You're a cool {} year old, {}!", age, name) } else { @@ -173,7 +173,7 @@ previous example: # fn main() {} #[get("/hello///")] -fn hello(name: String, age: u8, cool: bool) { /* ... */ } +fn hello(name: &str, age: u8, cool: bool) { /* ... */ } ``` What if `cool` isn't a `bool`? Or, what if `age` isn't a `u8`? When a parameter @@ -626,13 +626,13 @@ use serde::Deserialize; use rocket_contrib::json::Json; #[derive(Deserialize)] -struct Task { - description: String, +struct Task<'r> { + description: &'r str, complete: bool } #[post("/todo", data = "")] -fn new(task: Json) { /* .. */ } +fn new(task: Json>) { /* .. */ } ``` See the [JSON example] on GitHub for a complete example. @@ -711,13 +711,13 @@ can easily handle the form request in Rocket as follows: use rocket::form::Form; #[derive(FromForm)] -struct Task { +struct Task<'r> { complete: bool, - r#type: String, + r#type: &'r str, } #[post("/todo", data = "")] -fn new(task: Form) { /* .. */ } +fn new(task: Form>) { /* .. */ } ``` The [`Form`] type implements the `FromData` trait as long as its generic @@ -732,10 +732,10 @@ forward or failure can be caught by using the `Option` and `Result` types: ```rust # use rocket::{post, form::Form}; -# type Task = String; +# type Task<'r> = &'r str; #[post("/todo", data = "")] -fn new(task: Option>) { /* .. */ } +fn new(task: Option>>) { /* .. */ } ``` [`Form`]: @api/rocket/form/struct.Form.html @@ -760,10 +760,10 @@ replace `Form` with `Form>` above to get strict parsing: use rocket::form::{Form, Strict}; -# #[derive(FromForm)] struct Task { complete: bool, description: String, } +# #[derive(FromForm)] struct Task<'r> { complete: bool, description: &'r str, } #[post("/todo", data = "")] -fn new(task: Form>) { /* .. */ } +fn new(task: Form>>) { /* .. */ } ``` `Strict` can also be used to make individual fields strict while keeping the @@ -838,9 +838,9 @@ structure can be written as: # use rocket::form::FromForm; #[derive(FromForm)] -struct External { +struct External<'r> { #[field(name = "first-Name")] - first_name: String + first_name: &'r str } ``` @@ -851,10 +851,10 @@ If you want to accept both `firstName` case-insensitively as well as # use rocket::form::FromForm; #[derive(FromForm)] -struct External { +struct External<'r> { #[field(name = uncased("firstName"))] #[field(name = "first_name")] - first_name: String + first_name: &'r str } ``` @@ -868,11 +868,11 @@ in each instance case-insensitively, you would write: # use rocket::form::FromForm; #[derive(FromForm)] -struct External { +struct External<'r> { #[field(name = uncased("first-name"))] #[field(name = uncased("first_name"))] #[field(name = uncased("firstname"))] - first_name: String + first_name: &'r str } ``` @@ -998,19 +998,19 @@ Form structs can be nested: use rocket::form::FromForm; #[derive(FromForm)] -struct MyForm { - owner: Person, - pet: Pet, +struct MyForm<'r> { + owner: Person<'r>, + pet: Pet<'r>, } #[derive(FromForm)] -struct Person { - name: String +struct Person<'r> { + name: &'r str } #[derive(FromForm)] -struct Pet { - name: String, +struct Pet<'r> { + name: &'r str, #[field(validate = eq(true))] good_pet: bool, } diff --git a/site/guide/5-responses.md b/site/guide/5-responses.md index 3f304c7f..fbeca0a5 100644 --- a/site/guide/5-responses.md +++ b/site/guide/5-responses.md @@ -454,7 +454,7 @@ For example, given the following route: # fn main() {} #[get("//?")] -fn person(id: Option, name: String, age: Option) { /* .. */ } +fn person(id: Option, name: &str, age: Option) { /* .. */ } ``` URIs to `person` can be created as follows: @@ -463,7 +463,7 @@ URIs to `person` can be created as follows: # #[macro_use] extern crate rocket; # #[get("//?")] -# fn person(id: Option, name: String, age: Option) { /* .. */ } +# fn person(id: Option, name: &str, age: Option) { /* .. */ } // with unnamed parameters, in route path declaration order let mike = uri!(person: 101, "Mike Smith", Some(28)); @@ -495,7 +495,7 @@ error: `person` route uri expects 3 parameters but 1 was supplied 7 | let x = uri!(person: "Mike Smith"); | ^^^^^^^^^^^^ | - = note: expected parameters: id: Option , name: String, age: Option + = note: expected parameters: id: Option , name: &str, age: Option ``` Rocket also informs you of any type errors at compile-time: @@ -593,7 +593,7 @@ generated. # #[macro_use] extern crate rocket; # #[get("//?")] -# fn person(id: Option, name: String, age: Option) { /* .. */ } +# fn person(id: Option, name: &str, age: Option) { /* .. */ } /// Note that `id` is `Option` in the route, but `id` in `uri!` _cannot_ /// be an `Option`. `age`, on the other hand, _must_ be an `Option` (or `Result` diff --git a/site/index.toml b/site/index.toml index f9c59d3d..8884a671 100644 --- a/site/index.toml +++ b/site/index.toml @@ -50,7 +50,7 @@ code = ''' #[macro_use] extern crate rocket; #[get("/hello//")] - fn hello(name: String, age: u8) -> String { + fn hello(name: &str, age: u8) -> String { format!("Hello, {} year old named {}!", age, name) } @@ -75,17 +75,17 @@ text = ''' title = "Forms? Check!" code = ''' #[derive(FromForm)] - struct Task { - description: String, + struct Task<'r> { + description: &'r str, completed: bool } #[post("/", data = "")] - fn new(task: Form) -> Flash { + fn new(task: Form>) -> Flash { if task.description.is_empty() { - Flash::error(Redirect::to("/"), "Cannot be empty.") + Flash::error(Redirect::to(uri!(home)), "Cannot be empty.") } else { - Flash::success(Redirect::to("/"), "Task added.") + Flash::success(Redirect::to(uri!(home)), "Task added.") } } ''' @@ -103,14 +103,14 @@ text = ''' title = "JSON, out of the box." code = ''' #[derive(Serialize, Deserialize)] - struct Message { - contents: String, + struct Message<'r> { + contents: &'r str, } #[put("/", data = "")] - fn update(db: &Db, id: Id, msg: Json) -> JsonValue { + fn update(db: &Db, id: Id, msg: Json>) -> JsonValue { if db.contains_key(&id) { - db.insert(id, &msg.contents); + db.insert(id, msg.contents); json!({ "status": "ok" }) } else { json!({ "status": "error" }) diff --git a/site/tests/src/lib.rs b/site/tests/src/lib.rs index f237442a..43982c5d 100644 --- a/site/tests/src/lib.rs +++ b/site/tests/src/lib.rs @@ -1,5 +1,5 @@ #[cfg(any(test, doctest))] rocket::internal_guide_tests!("../guide/*.md"); -#[cfg(any(test, doctest))] rocket::internal_guide_tests!("../../../README.md"); +#[cfg(any(test, doctest))] rocket::internal_guide_tests!("../../README.md"); #[macro_export] macro_rules! map {