From 902fb6c3d625e12023a72498475574413a6e620a Mon Sep 17 00:00:00 2001 From: Walther Chen Date: Sat, 4 Aug 2018 11:08:11 -0400 Subject: use non-strict parsing to allow round-trip in example --- examples/introduction.rs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'examples') diff --git a/examples/introduction.rs b/examples/introduction.rs index d980719..9878968 100644 --- a/examples/introduction.rs +++ b/examples/introduction.rs @@ -7,6 +7,8 @@ extern crate serde_urlencoded as urlencoded; use rand::Rng; use std::collections::HashMap; +use qs::Config; + #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] struct Address { city: String, @@ -64,9 +66,15 @@ fn main() { // as a list of pairs using serde_urlencoded: let pairs: Vec<(String, String)> = urlencoded::from_str(&encoded).unwrap(); println!("`serde_urlencoded` from_str to pairs:\n\t{:?}", pairs); + // However, the best way is to use serde_qs to deserialize the entire thing // into a struct: - let params: QueryParams = qs::from_str(&encoded).unwrap(); + // + // (For this round trip to work, it's necessary to parse the query string + // in non-strict mode, to allow parsing of url_encoded square brackets + // in the key). + let qs_non_strict = Config::new(5, false); + let params: QueryParams = qs_non_strict.deserialize_str(&encoded).unwrap(); assert_eq!(params, example_params); println!("`serde_qs` from_str to struct:\n\t{:?}", params); -- cgit v1.2.3 From 51b9edc66b0320e4ad8680416f040070c2b3810c Mon Sep 17 00:00:00 2001 From: Sam Scott Date: Sat, 4 Aug 2018 12:13:46 -0400 Subject: Update documentation to clarify strict encoding modes. --- Cargo.toml | 2 +- README.md | 2 +- examples/introduction.rs | 2 +- src/lib.rs | 28 ++++++++++++++++++++++++++++ 4 files changed, 31 insertions(+), 3 deletions(-) (limited to 'examples') diff --git a/Cargo.toml b/Cargo.toml index 8ea1c37..d832662 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,7 +8,7 @@ license = "MIT/Apache-2.0" name = "serde_qs" repository = "https://github.com/samscott89/serde_qs" readme = "README.md" -version = "0.4.1" +version = "0.4.2" [badges] diff --git a/README.md b/README.md index a2ef973..034e9dd 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ This crate works with Cargo and can be found on ```toml [dependencies] -serde_qs = "0.4.1" +serde_qs = "0.4.2" ``` [crates.io]: https://crates.io/crates/serde_qs diff --git a/examples/introduction.rs b/examples/introduction.rs index 9878968..a1f6fc9 100644 --- a/examples/introduction.rs +++ b/examples/introduction.rs @@ -72,7 +72,7 @@ fn main() { // // (For this round trip to work, it's necessary to parse the query string // in non-strict mode, to allow parsing of url_encoded square brackets - // in the key). + // in the key. See the lib.rs documentation for why). let qs_non_strict = Config::new(5, false); let params: QueryParams = qs_non_strict.deserialize_str(&encoded).unwrap(); assert_eq!(params, example_params); diff --git a/src/lib.rs b/src/lib.rs index 2da9b2a..b2bd63c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -70,6 +70,34 @@ //! assert_eq!(rec_params, params); //! //! # } +//! ``` +//! +//! ## Strict vs Non-Strict modes +//! +//! `serde_qs` supports two operating modes, which can be specified using +//! [`Config`](struct.Config.html), and is all about how `serde_qs` handles square brackets. +//! +//! Techncially, square brackets should be encoded in URLs as `%5B` and `%5D`. +//! However, they are often used in their raw format to specify querystrings +//! such as `a[b]=123`. +//! +//! In strict mode, `serde_qs` will only tolerate unencoded square brackets +//! to denote nested keys. So `a[b]=123` will decode as `{"a": {"b": 123}}`. +//! This means that encoded square brackets can actually be part of the key. +//! `a[b%5Bc%5D]=123` becomes `{"a": {"b[c]": 123}}`. +//! +//! However, since some implementations will automatically encode everything +//! in the URL, we also have a non-strict mode. This means that `serde_qs` +//! will assume that any encoded square brackets in the string were meant to +//! be taken as nested keys. From the example before, `a[b%5Bc%5D]=123` will +//! now become `{"a": {"b": {"c": 123 }}}`. +//! +//! Non-strict mode can be useful when, as said before, some middleware +//! automatically encodes the brackets. But care must be taken to avoid +//! using keys with square brackets in them, or unexpected things can +//! happen. +//! +//! #![allow( )] -- cgit v1.2.3