diff --git a/lib/src/request/form/from_form_value.rs b/lib/src/request/form/from_form_value.rs index 012d2b94..cccc28e7 100644 --- a/lib/src/request/form/from_form_value.rs +++ b/lib/src/request/form/from_form_value.rs @@ -7,10 +7,101 @@ use http::uri::URI; /// Trait to create instance of some type from a form value; expected from field /// types in structs deriving `FromForm`. /// -/// # Examples +/// When deriving the `FromForm` trait, Rocket uses the `FromFormValue` +/// implementation of each field's type to validate the form input. To +/// illustrate, consider the following structure: /// -/// This trait is generally implemented when verifying form inputs. For example, -/// if you'd like to verify that some user is over some age in a form, then you +/// ```rust,ignore +/// #[derive(FromForm)] +/// struct Person { +/// name: String, +/// age: u16 +/// } +/// ``` +/// +/// The `FromForm` implementation generated by Rocket will call +/// `String::from_form_value` for the `name` field, and `u16::from_form_value` +/// for the `age` field. The `Person` structure can only be created from a form +/// if both calls return successfully. +/// +/// ## Catching Validation Errors +/// +/// Sometimes you want to be informed of validation errors. When this is +/// desired, types of `Option` or `Result` can be used. These +/// types implement `FromFormValue` themselves. Their implementations always +/// return successfully, so their validation never fails. They can be used to +/// determine if the `from_form_value` call failed and to retrieve the error +/// value from the failed call. +/// +/// For instance, if we wanted to know if a user entered an invalid `age` in the +/// form corresponding to the `Person` structure above, we could use the +/// following structure: +/// +/// ```rust +/// struct Person<'r> { +/// name: String, +/// age: Result +/// } +/// ``` +/// +/// The `Err` value in this case is `&str` since `u16::from_form_value` returns +/// a `Result`. +/// +/// # Provided Implementations +/// +/// Rocket implements `FromFormValue` for many standard library types. Their +/// behavior is documented here. +/// +/// * **f32, f64, isize, i8, i16, i32, i64, usize, u8, u16, u32, u64** +/// +/// **IpAddr, Ipv4Addr, Ipv6Addr, SocketAddrV4, SocketAddrV6, SocketAddr** +/// +/// A value is validated successfully if the `from_str` method for the given +/// type returns successfully. Otherwise, the raw form value is returned as +/// the `Err` value. +/// +/// * **bool** +/// +/// A value is validated successfully as `true` if the the form value is +/// `"true"` or `"on"`, and as a `false` value if the form value is +/// `"false"`, or `"off"`. Otherwise, the raw form value is returned in the +/// `Err` value. +/// +/// * **str** +/// +/// _This implementation always returns successfully._ +/// +/// The raw, undecoded string is returned directly without modification. +/// +/// * **String** +/// +/// URL decodes the form value. If the decode is successful, the decoded +/// string is returned. Otherwise, an `Err` with the original form value is +/// returned. +/// +/// * **Option<T>** _where_ **T: FromFormValue** +/// +/// _This implementation always returns successfully._ +/// +/// The form value is validated by `T`'s `FromFormValue` implementation. If +/// the validation succeeds, a `Some(validated_value)` is returned. +/// Otherwise, a `None` is returned. +/// +/// * **Result<T, T::Error>** _where_ **T: FromFormValue** +/// +/// _This implementation always returns successfully._ +/// +/// The from value is validated by `T`'s `FromFormvalue` implementation. The +/// returned `Result` value is returned. +/// +/// # Example +/// +/// This trait is generally implemented to parse and validate form values. While +/// Rocket provides parsing and validation for many of the standard library +/// types such as `u16` and `String`, you can implement `FromFormValue` for a +/// custom type to get custom validation. +/// +/// Imagine you'd like to verify that some user is over some age in a form. You /// might define a new type and implement `FromFormValue` as follows: /// /// ```rust @@ -31,15 +122,18 @@ use http::uri::URI; /// } /// ``` /// -/// This type can then be used in a `FromForm` struct as follows: +/// The type can then be used in a `FromForm` struct as follows: /// /// ```rust,ignore /// #[derive(FromForm)] -/// struct User { -/// age: AdultAge, -/// ... +/// struct Person { +/// name: String, +/// age: AdultAge /// } /// ``` +/// +/// A form using the `Person` structure as its target will only parse and +/// validate if the `age` field contains a `usize` greater than `21`. pub trait FromFormValue<'v>: Sized { /// The associated error which can be returned from parsing. It is a good /// idea to have the return type be or contain an `&'v str` so that the diff --git a/lib/src/request/form/mod.rs b/lib/src/request/form/mod.rs index 11cfa6d2..cc718b1d 100644 --- a/lib/src/request/form/mod.rs +++ b/lib/src/request/form/mod.rs @@ -9,11 +9,12 @@ //! ``` //! //! Form parameter types must implement the [FromForm](trait.FromForm.html) -//! trait, which is automaForwarp derivable. Automatically deriving `FromForm` -//! for a structure requires that all of its fields implement -//! [FromFormValue](trait.FormFormValue.html). See the -//! [codegen](/rocket_codegen/) documentation or the [forms guide](/guide/forms) -//! for more information on forms and on deriving `FromForm`. +//! trait, which is auto-derivable. Automatically deriving `FromForm` for a +//! structure requires that all of its fields implement +//! [FromFormValue](trait.FormFormValue.html), which parses and validates form +//! fields. See the [codegen](/rocket_codegen/) documentation or the [forms +//! guide](/guide/forms) for more information on forms and on deriving +//! `FromForm`. mod form_items; mod from_form; diff --git a/lib/src/request/param.rs b/lib/src/request/param.rs index 385dc4a8..cea390a7 100644 --- a/lib/src/request/param.rs +++ b/lib/src/request/param.rs @@ -43,7 +43,7 @@ use http::uri::{URI, Segments, SegmentError}; /// Sometimes, a forward is not desired, and instead, we simply want to know /// that the dynamic path segment could not be parsed into some desired type /// `T`. In these cases, types of `Option` or `Result` can be -/// used. These types implement `FromParam` themeselves. Their implementations +/// used. These types implement `FromParam` themselves. Their implementations /// always return successfully, so they never forward. They can be used to /// determine if the `FromParam` call failed and to retrieve the error value /// from the failed `from_param` call.