As promised, here is the version with the proposed syntax, keeping all of the existing clauses:
defmodule URI do
@moduledoc """
Utilities for working with URIs.
"""
# Type aliases for better readability
$ type scheme() = string() or nil
$ type host() = string() or nil
$ type port() = non_neg_integer() or nil
$ type path() = string() or nil
$ type query() = string() or nil
$ type fragment() = string() or nil
$ type userinfo() = string() or nil
$ type uri_string() = string()
$ type encoding_type() = :www_form or :rfc3986
$ type query_map() = %{string() => string()}
$ type query_enum() = enumerable.t()
$ type query_pair() = {string(), string()}
$ type predicate() = (byte() -> boolean())
$ type authority() = string() or nil
@derive {Inspect, optional: [:authority]}
defstruct [:scheme, :authority, :userinfo, :host, :port, :path, :query, :fragment]
$ string() -> port()
def default_port(scheme) when is_binary(scheme), do: ...
$ string(), port() and not nil -> :ok
def default_port(scheme, port) when is_binary(scheme) and is_integer(port) and port >= 0, do: ...
$ query_enum(), encoding_type() -> string()
def encode_query(enumerable, encoding \\ :www_form), do: ...
$ query_pair(), encoding_type() -> string()
defp encode_kv_pair({key, _}, _encoding) when is_list(key), do: ...
defp encode_kv_pair({_, value}, _encoding) when is_list(value), do: ...
defp encode_kv_pair({key, value}, :rfc3986), do: ...
defp encode_kv_pair({key, value}, :www_form), do: ...
$ string(), map(), encoding_type() -> %{}
def decode_query(query, map \\ %{}, encoding \\ :www_form)
def decode_query(query, %_{} = dict, encoding) when is_binary(query), do: ...
def decode_query(query, map, encoding) when is_binary(query) and is_map(map), do: ...
def decode_query(query, dict, encoding) when is_binary(query), do: ...
$ string(), query_map(), encoding_type() -> query_map()
defp decode_query_into_map(query, map, encoding), do: ...
$ string(), any(), encoding_type() -> any()
defp decode_query_into_dict(query, dict, encoding), do: ...
$ string(), encoding_type() -> enumerable.t()
def query_decoder(query, encoding \\ :www_form) when is_binary(query), do: ...
$ string(), encoding_type() -> {query_pair(), string()} or nil
defp decode_next_query_pair("", _encoding), do: ...
defp decode_next_query_pair(query, encoding), do: ...
$ string(), encoding_type() -> string()
defp decode_with_encoding(string, :www_form), do: ...
defp decode_with_encoding(string, :rfc3986), do: ...
$ byte() -> boolean()
def char_reserved?(character), do: ...
$ byte() -> boolean()
def char_unreserved?(character), do: ...
$ byte() -> boolean()
def char_unescaped?(character), do: ...
$ string(), predicate() -> string()
def encode(string, predicate \\ &char_unescaped?/1)
when is_binary(string) and is_function(predicate, 1), do: ...
$ string() -> string()
def encode_www_form(string) when is_binary(string), do: ...
$ byte(), predicate() -> string()
defp percent(char, predicate), do: ...
$ byte() -> byte()
defp hex(n) when n <= 9, do: ...
defp hex(n), do: ...
$ string() -> string()
def decode(uri), do: ...
$ string() -> string()
def decode_www_form(string) when is_binary(string), do: ...
$ string(), string(), boolean() -> string()
defp unpercent(<<?+, tail::binary>>, acc, true), do: ...
defp unpercent(<<?%, tail::binary>>, acc, spaces), do: ...
defp unpercent(<<head, tail::binary>>, acc, spaces), do: ...
defp unpercent(<<>>, acc, _spaces), do: ...
$ byte() -> byte() or nil
defp hex_to_dec(n) when n in ?A..?F, do: ...
defp hex_to_dec(n) when n in ?a..?f, do: ...
defp hex_to_dec(n) when n in ?0..?9, do: ...
defp hex_to_dec(_n), do: ...
$ t() or uri_string() -> {:ok, t()} or {:error, string()}
def new(%URI{} = uri), do: ...
def new(binary) when is_binary(binary), do: ...
$ t() or uri_string() -> t()
def new!(%URI{} = uri), do: ...
def new!(binary) when is_binary(binary), do: ...
$ map() -> t()
defp uri_from_map(%{path: ""} = map), do: ...
defp uri_from_map(map), do: ...
$ t() or string() -> t()
def parse(%URI{} = uri), do: ...
def parse(string) when is_binary(string), do: ...
$ string() -> query() or nil
defp nilify_query("?" <> query), do: ...
defp nilify_query(_other), do: ...
$ string() -> {authority(), userinfo(), host(), port()}
defp split_authority(""), do: ...
defp split_authority("//"), do: ...
defp split_authority("//" <> authority), do: ...
$ string() -> string() or nil
defp nilify(""), do: ...
defp nilify(other), do: ...
$ t() -> string()
def to_string(uri), do: ...
$ t() or string(), t() or string() -> t()
def merge(uri, rel)
def merge(%URI{scheme: nil}, _rel), do: ...
def merge(_base, %URI{scheme: rel_scheme} = rel) when rel_scheme != nil, do: ...
def merge(%URI{} = base, %URI{host: host} = rel) when host != nil, do: ...
def merge(%URI{} = base, %URI{path: nil} = rel), do: ...
def merge(%URI{host: nil, path: nil} = base, %URI{} = rel), do: ...
def merge(%URI{} = base, %URI{} = rel), do: ...
def merge(base, rel), do: ...
$ path(), path() -> path()
defp merge_paths(nil, rel_path), do: ...
defp merge_paths(_, "/" <> _ = rel_path), do: ...
defp merge_paths(base_path, rel_path), do: ...
$ path() -> path()
defp remove_dot_segments_from_path(nil), do: ...
defp remove_dot_segments_from_path(path), do: ...
$ string() -> [string() or atom()]
defp path_to_segments(path), do: ...
$ [string() or atom()], [string() or atom()] -> [string() or atom()]
defp remove_dot_segments([], acc), do: ...
defp remove_dot_segments([:/ | tail], acc), do: ...
defp remove_dot_segments([_, :+ | tail], acc), do: ...
defp remove_dot_segments(["."], acc), do: ...
defp remove_dot_segments(["." | tail], acc), do: ...
defp remove_dot_segments([".." | tail], [:/]), do: ...
defp remove_dot_segments([".."], [_ | acc]), do: ...
defp remove_dot_segments([".." | tail], [_ | acc]), do: ...
defp remove_dot_segments([head | tail], acc), do: ...
$ [atom() or string()] -> string()
defp join_reversed_segments([:/]), do: ...
defp join_reversed_segments(segments), do: ...
$ t(), string() -> t()
def append_query(%URI{} = uri, query) when is_binary(query) and uri.query in [nil, ""], do: ...
def append_query(%URI{} = uri, query) when is_binary(query), do: ...
$ t(), string() -> t()
def append_path(%URI{}, "//" <> _ = path), do: ...
def append_path(%URI{path: path} = uri, "/" <> rest = all), do: ...
def append_path(%URI{}, path) when is_binary(path), do: ...
end
I suggest that you also preserve and annotate all of the existing clauses, so we can effectively compare how existing code will be typed.
Figured I’d may as well include some self-promo at this point 