Conveniences for decoding and encoding URL-encoded queries.

Plug allows developers to build query strings that map to Elixir structures in order to make manipulation of such structures easier on the server side. Here are some examples:

iex> decode("foo=bar")["foo"]
"bar"

If a value is given more than once, the last value takes precedence:

iex> decode("foo=bar&foo=baz")["foo"]
"baz"

Nested structures can be created via [key]:

iex> decode("foo[bar]=baz")["foo"]["bar"]
"baz"

Lists are created with []:

iex> decode("foo[]=bar&foo[]=baz")["foo"]
["bar", "baz"]

Keys without values are treated as empty strings, according to https://url.spec.whatwg.org/#application/x-www-form-urlencoded:

iex> decode("foo")["foo"]
""

Maps can be encoded:

iex> encode(%{foo: "bar"})
"foo=bar"

Encoding keyword lists preserves the order of the fields:

iex> encode([foo: "bar", baz: "bat"])
"foo=bar&baz=bat"

When encoding keyword lists with duplicate keys, the key that comes first takes precedence:

iex> encode([foo: "bar", foo: "bat"])
"foo=bar"

Encoding named lists:

iex> encode(%{foo: ["bar", "baz"]})
"foo[]=bar&foo[]=baz"

Encoding nested structures:

iex> encode(%{foo: %{bar: "baz"}})
"foo[bar]=baz"

It is only possible to encode maps inside lists if those maps have exactly one element. In this case it is possible to encode the parameters using maps instead of lists:

iex> encode(%{"list" => [%{"a" => 1, "b" => 2}]})
** (ArgumentError) cannot encode maps inside lists when the map has 0 or more than 1 element, got: %{"a" => 1, "b" => 2}

iex> encode(%{"list" => %{0 => %{"a" => 1, "b" => 2}}})
"list[0][a]=1&list[0][b]=2"

For stateful decoding, see decode_init/0, decode_each/2, and decode_done/2.