From 16c212f853abc00a430520b01e7130c36e384545 Mon Sep 17 00:00:00 2001
From: Nikolay Kim <fafhrd91@gmail.com>
Date: Sat, 31 Mar 2018 09:18:25 -0700
Subject: [PATCH] add extractors info to guide
---
CHANGES.md | 3 +++
guide/src/qs_5.md | 23 +++++++++++++++++++++--
guide/src/qs_7.md | 33 ++++++++++++++++++++++++++++++---
src/json.rs | 2 --
src/pred.rs | 3 ++-
src/server/mod.rs | 7 +++++++
src/ws/mod.rs | 2 +-
7 files changed, 64 insertions(+), 9 deletions(-)
diff --git a/CHANGES.md b/CHANGES.md
index b424a387..4acf464a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,6 +4,9 @@
* Type-safe path/query parameter handling, using serde #70
+* HttpResponse builder's methods `.body()`, `.finish()`, `.json()`
+ return `HttpResponse` instead of `Result`
+
* Use more ergonomic `actix_web::Error` instead of `http::Error` for `HttpResponseBuilder::body()`
* Use more ergonomic `actix_web::Error` instead of `http::Error` for `ClientRequestBuilder::body()`
diff --git a/guide/src/qs_5.md b/guide/src/qs_5.md
index 67b3be79..f97840a0 100644
--- a/guide/src/qs_5.md
+++ b/guide/src/qs_5.md
@@ -329,9 +329,7 @@ It uses *serde* package as a deserialization library.
has to implement *serde's *`Deserialize` trait.
```rust
-# extern crate bytes;
# extern crate actix_web;
-# extern crate futures;
#[macro_use] extern crate serde_derive;
use actix_web::{App, Path, Result, http::Method};
@@ -352,6 +350,27 @@ fn main() {
}
```
+It also possible to extract path information to a tuple, in this case you don't need
+to define extra type, just use tuple for as a `Path` generic type.
+
+Here is previous example re-written using tuple instead of specific type.
+
+```rust
+# extern crate actix_web;
+use actix_web::{App, Path, Result, http::Method};
+
+// extract path info using serde
+fn index(info: Path<(String, u32)>) -> Result<String> {
+ Ok(format!("Welcome {}! id: {}", info.0, info.1))
+}
+
+fn main() {
+ let app = App::new()
+ .resource("/{username}/{id}/index.html", // <- define path parameters
+ |r| r.method(Method::GET).with(index));
+}
+```
+
[Query](../actix_web/struct.Query.html) provides similar functionality for
request query parameters.
diff --git a/guide/src/qs_7.md b/guide/src/qs_7.md
index d841f2bd..886d8b27 100644
--- a/guide/src/qs_7.md
+++ b/guide/src/qs_7.md
@@ -58,9 +58,36 @@ fn index(req: HttpRequest) -> HttpResponse {
## JSON Request
-There are two options for json body deserialization.
+There are several options for json body deserialization.
-The first option is to use *HttpResponse::json()*. This method returns a
+The first option is to use *Json* extractor. You define handler function
+that accepts `Json<T>` as a parameter and use `.with()` method for registering
+this handler. It is also possible to accept arbitrary valid json object by
+using `serde_json::Value` as a type `T`
+
+```rust
+# extern crate actix_web;
+#[macro_use] extern crate serde_derive;
+use actix_web::{App, Json, Result, http};
+
+#[derive(Deserialize)]
+struct Info {
+ username: String,
+}
+
+/// extract `Info` using serde
+fn index(info: Json<Info>) -> Result<String> {
+ Ok(format!("Welcome {}!", info.username))
+}
+
+fn main() {
+ let app = App::new().resource(
+ "/index.html",
+ |r| r.method(http::Method::POST).with(index)); // <- use `with` extractor
+}
+```
+
+The second option is to use *HttpResponse::json()*. This method returns a
[*JsonBody*](../actix_web/dev/struct.JsonBody.html) object which resolves into
the deserialized value.
@@ -128,7 +155,7 @@ A complete example for both options is available in
## JSON Response
-The `Json` type allows you to respond with well-formed JSON data: simply return a value of
+The `Json` type allows to respond with well-formed JSON data: simply return a value of
type Json<T> where T is the type of a structure to serialize into *JSON*. The
type `T` must implement the `Serialize` trait from *serde*.
diff --git a/src/json.rs b/src/json.rs
index 721361ff..eb61da1b 100644
--- a/src/json.rs
+++ b/src/json.rs
@@ -47,9 +47,7 @@ use httpresponse::HttpResponse;
/// ## Example
///
/// ```rust
-/// # extern crate bytes;
/// # extern crate actix_web;
-/// # extern crate futures;
/// #[macro_use] extern crate serde_derive;
/// use actix_web::{App, Json, Result, http};
///
diff --git a/src/pred.rs b/src/pred.rs
index 0c7468d0..57398fc2 100644
--- a/src/pred.rs
+++ b/src/pred.rs
@@ -8,7 +8,8 @@ use httprequest::HttpRequest;
/// Trait defines resource route predicate.
/// Predicate can modify request object. It is also possible to
-/// to store extra attributes on request by using `.extensions()` method.
+/// to store extra attributes on request by using `Extensions` container,
+/// Extensions container available via `HttpRequest::extensions()` method.
pub trait Predicate<S> {
/// Check if request matches predicate
diff --git a/src/server/mod.rs b/src/server/mod.rs
index fafcb9a2..96f53c5f 100644
--- a/src/server/mod.rs
+++ b/src/server/mod.rs
@@ -126,12 +126,16 @@ impl HttpHandler for Box<HttpHandler> {
}
}
+#[doc(hidden)]
pub trait HttpHandlerTask {
+ /// Poll task, this method is used before or after *io* object is available
fn poll(&mut self) -> Poll<(), Error>;
+ /// Poll task when *io* object is available
fn poll_io(&mut self, io: &mut Writer) -> Poll<bool, Error>;
+ /// Connection is disconnected
fn disconnected(&mut self);
}
@@ -152,12 +156,14 @@ impl<T: HttpHandler> IntoHttpHandler for T {
}
}
+#[doc(hidden)]
#[derive(Debug)]
pub enum WriterState {
Done,
Pause,
}
+#[doc(hidden)]
/// Stream writer
pub trait Writer {
fn written(&self) -> u64;
@@ -172,6 +178,7 @@ pub trait Writer {
fn poll_completed(&mut self, shutdown: bool) -> Poll<(), io::Error>;
}
+#[doc(hidden)]
/// Low-level io stream operations
pub trait IoStream: AsyncRead + AsyncWrite + 'static {
fn shutdown(&mut self, how: Shutdown) -> io::Result<()>;
diff --git a/src/ws/mod.rs b/src/ws/mod.rs
index c601236b..9c5c74c5 100644
--- a/src/ws/mod.rs
+++ b/src/ws/mod.rs
@@ -10,7 +10,7 @@
//! # extern crate actix_web;
//! # use actix::*;
//! # use actix_web::*;
-//! use actix_web::ws;
+//! use actix_web::{ws, HttpRequest, HttpResponse};
//!
//! // do websocket handshake and start actor
//! fn ws_index(req: HttpRequest) -> Result<HttpResponse> {