zf

query.ex (7670B)

---

 defmodule Plug.Conn.Query do
   @moduledoc """
   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", baz: "bat"})
       "baz=bat&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"
 
   """
 
   @doc """
   Decodes the given `query`.
 
   The `query` is assumed to be encoded in the "x-www-form-urlencoded" format.
   The format is decoded at first. Then, if `validate_utf8` is `true`, the decoded
   result is validated for proper UTF-8 encoding.
 
   `initial` is the initial "accumulator" where decoded values will be added.
 
   `invalid_exception` is the exception module for the exception to raise on
   errors with decoding.
   """
   @spec decode(String.t(), map(), module(), boolean()) :: %{optional(String.t()) => term()}
   def decode(
         query,
         initial \\ %{},
         invalid_exception \\ Plug.Conn.InvalidQueryError,
         validate_utf8 \\ true
       )
 
   def decode("", initial, _invalid_exception, _validate_utf8) do
     initial
   end
 
   def decode(query, initial, invalid_exception, validate_utf8)
       when is_binary(query) do
     parts = :binary.split(query, "&", [:global])
 
     Enum.reduce(
       Enum.reverse(parts),
       initial,
       &decode_www_pair(&1, &2, invalid_exception, validate_utf8)
     )
   end
 
   defp decode_www_pair("", acc, _invalid_exception, _validate_utf8) do
     acc
   end
 
   defp decode_www_pair(binary, acc, invalid_exception, validate_utf8) do
     current =
       case :binary.split(binary, "=") do
         [key, value] ->
           {decode_www_form(key, invalid_exception, validate_utf8),
            decode_www_form(value, invalid_exception, validate_utf8)}
 
         [key] ->
           {decode_www_form(key, invalid_exception, validate_utf8), ""}
       end
 
     decode_pair(current, acc)
   end
 
   defp decode_www_form(value, invalid_exception, validate_utf8) do
     # TODO: Remove rescue as this can't fail from Elixir v1.13
     try do
       URI.decode_www_form(value)
     rescue
       ArgumentError ->
         raise invalid_exception, "invalid urlencoded params, got #{value}"
     else
       binary ->
         if validate_utf8 do
           Plug.Conn.Utils.validate_utf8!(binary, invalid_exception, "urlencoded params")
         end
 
         binary
     end
   end
 
   @doc """
   Decodes the given tuple and stores it in the given accumulator.
 
   It parses the key and stores the value into the current
   accumulator. The keys and values are not assumed to be
   encoded in "x-www-form-urlencoded".
 
   Parameter lists are added to the accumulator in reverse
   order, so be sure to pass the parameters in reverse order.
   """
   @spec decode_pair({String.t(), term()}, acc) :: acc when acc: term()
   def decode_pair({key, value} = _pair, acc) do
     if key != "" and :binary.last(key) == ?] do
       # Remove trailing ]
       subkey = :binary.part(key, 0, byte_size(key) - 1)
 
       # Split the first [ then we will split on remaining ][.
       #
       #     users[address][street #=> [ "users", "address][street" ]
       #
       assign_split(:binary.split(subkey, "["), value, acc, :binary.compile_pattern("]["))
     else
       assign_map(acc, key, value)
     end
   end
 
   defp assign_split(["", rest], value, acc, pattern) do
     parts = :binary.split(rest, pattern)
 
     case acc do
       [_ | _] -> [assign_split(parts, value, :none, pattern) | acc]
       :none -> [assign_split(parts, value, :none, pattern)]
       _ -> acc
     end
   end
 
   defp assign_split([key, rest], value, acc, pattern) do
     parts = :binary.split(rest, pattern)
 
     case acc do
       %{^key => current} when is_list(current) or is_map(current) ->
         Map.put(acc, key, assign_split(parts, value, current, pattern))
 
       %{^key => _} ->
         acc
 
       %{} ->
         Map.put(acc, key, assign_split(parts, value, :none, pattern))
 
       _ ->
         %{key => assign_split(parts, value, :none, pattern)}
     end
   end
 
   defp assign_split([""], nil, acc, _pattern) do
     case acc do
       [_ | _] -> acc
       _ -> []
     end
   end
 
   defp assign_split([""], value, acc, _pattern) do
     case acc do
       [_ | _] -> [value | acc]
       :none -> [value]
       _ -> acc
     end
   end
 
   defp assign_split([key], value, acc, _pattern) do
     assign_map(acc, key, value)
   end
 
   defp assign_map(acc, key, value) do
     case acc do
       %{^key => _} -> acc
       %{} -> Map.put(acc, key, value)
       _ -> %{key => value}
     end
   end
 
   @doc """
   Encodes the given map or list of tuples.
   """
   @spec encode(Enumerable.t(), (term() -> binary())) :: binary()
   def encode(kv, encoder \\ &to_string/1) do
     IO.iodata_to_binary(encode_pair("", kv, encoder))
   end
 
   # covers structs
   defp encode_pair(field, %{__struct__: struct} = map, encoder) when is_atom(struct) do
     [field, ?= | encode_value(map, encoder)]
   end
 
   # covers maps
   defp encode_pair(parent_field, %{} = map, encoder) do
     encode_kv(map, parent_field, encoder)
   end
 
   # covers keyword lists
   defp encode_pair(parent_field, list, encoder) when is_list(list) and is_tuple(hd(list)) do
     encode_kv(Enum.uniq_by(list, &elem(&1, 0)), parent_field, encoder)
   end
 
   # covers non-keyword lists
   defp encode_pair(parent_field, list, encoder) when is_list(list) do
     mapper = fn
       value when is_map(value) and map_size(value) != 1 ->
         raise ArgumentError,
               "cannot encode maps inside lists when the map has 0 or more than 1 element, " <>
                 "got: #{inspect(value)}"
 
       value ->
         [?&, encode_pair(parent_field <> "[]", value, encoder)]
     end
 
     list
     |> Enum.flat_map(mapper)
     |> prune()
   end
 
   # covers nil
   defp encode_pair(field, nil, _encoder) do
     [field, ?=]
   end
 
   # encoder fallback
   defp encode_pair(field, value, encoder) do
     [field, ?= | encode_value(value, encoder)]
   end
 
   defp encode_kv(kv, parent_field, encoder) do
     mapper = fn
       {_, value} when value in [%{}, []] ->
         []
 
       {field, value} ->
         field =
           if parent_field == "" do
             encode_key(field)
           else
             parent_field <> "[" <> encode_key(field) <> "]"
           end
 
         [?&, encode_pair(field, value, encoder)]
     end
 
     kv
     |> Enum.flat_map(mapper)
     |> prune()
   end
 
   defp encode_key(item) do
     item |> to_string |> URI.encode_www_form()
   end
 
   defp encode_value(item, encoder) do
     item |> encoder.() |> URI.encode_www_form()
   end
 
   defp prune([?& | t]), do: t
   defp prune([]), do: []
 end