# `serde_html_form`

(De-)serialization support for the `application/x-www-form-urlencoded` format.

This crate is a Rust library for serializing to and deserializing from
the [`application/x-www-form-urlencoded`][urlencoded] format. It is built
upon [`serde`], a high performance generic serialization framework and
[`form_urlencoded`], a urlencoded parser for Rust (part of Servo).

It is a fork of [`serde_urlencoded`], with additional support for maps or
structs with fields of sequence type (e.g. `Vec<String>`). It also supports
`Option`al numerical values, treating `foo=` as `foo: None`.

[`form_urlencoded`]: https://crates.io/crates/form_urlencoded
[`serde`]: https://crates.io/crates/serde
[urlencoded]: https://url.spec.whatwg.org/#application/x-www-form-urlencoded
[`serde_urlencoded`]: https://crates.io/crates/serde_urlencoded

## Examples

Sequences like `value=x&value=y`:

```rust
use serde::Deserialize;

#[derive(Debug, PartialEq, Deserialize)]
struct Form {
    // By default, at least one occurrence of this field must be present (this
    // is mandated by how serde works).
    //
    // Since this is usually not desired, use `serde(default)` to instantiate
    // this struct's field with a `Default` value if input doesn't contain that
    // field.
    #[serde(default)]
    value: Vec<String>,
}

assert_eq!(
    serde_html_form::from_str("value=&value=abc"),
    Ok(Form { value: vec!["".to_owned(), "abc".to_owned()] })
);
assert_eq!(
    serde_html_form::from_str(""),
    Ok(Form { value: vec![] })
);
```

Sequences like `value[]=x&value[]=y`:

```rust
use serde::Deserialize;

#[derive(Debug, PartialEq, Deserialize)]
struct Form {
    // If you want to support `value[]=x&value[]=y`, you can use
    // `serde(rename)`. You could even use `serde(alias)` instead to allow both,
    // but note that mixing both in one input string would also be allowed then.
    #[serde(default, rename = "value[]")]
    value: Vec<String>,
}

assert_eq!(
    serde_html_form::from_str("value[]=x&value[]=y"),
    Ok(Form { value: vec!["x".to_owned(), "y".to_owned()] })
);
assert_eq!(
    serde_html_form::from_str("value[]=hello"),
    Ok(Form { value: vec!["hello".to_owned()] })
);
```

Optional values:

```rust
use serde::Deserialize;

#[derive(Debug, PartialEq, Deserialize)]
struct Form {
    // Finally, this crate also supports deserializing empty values as `None`
    // if your values are `Option`s.
    // Note that serde's `Deserialize` derive implicitly allows omission of
    // `Option`-typed fields (except when combined with some other attributes).
    single: Option<u32>,
    // Not using `serde(default)` here to require at least one occurrence.
    at_least_one: Vec<Option<u32>>,
}

assert_eq!(
    serde_html_form::from_str("at_least_one=5"),
    Ok(Form {
        // Implicit `serde(default)` in action.
        single: None,
        // `serde_html_form`'s support for optional values being used.
        at_least_one: vec![Some(5)],
    })
);
assert_eq!(
    serde_html_form::from_str("at_least_one=&single=1&at_least_one=5"),
    Ok(Form {
        single: Some(1),
        at_least_one: vec![
            // Empty strings get deserialized as `None` for fields of builtin
            // numerical types. Use `serde_html_form::empty_as_none` if you want
            // this behavior for fields of other types.
            None,
            // It's no problem that the `at_least_one` field repetitions are
            // not consecutive (single comes in between).
            Some(5),
        ]
    })
);
assert!(
    serde_html_form::from_str::<Form>("").is_err(),
    "at_least_one is not part of the input"
);
```

## License

This crate is licensed under the [MIT license](https://opensource.org/license/mit/).
