@spec fix(binary() | nil) :: binary() | nil

Applies some fixes to a URI string if necessary. Returns nil when given nil.

Adds a default path if one is not given:

iex> Moar.URI.fix("https://www.example.com")
"https://www.example.com/"

iex> Moar.URI.fix("https://www.example.com/")
"https://www.example.com/"

iex> Moar.URI.fix("https://www.example.com/index.html")
"https://www.example.com/index.html"

Adds an https scheme if no scheme is given:

iex> Moar.URI.fix("www.example.com/")
"https://www.example.com/"

iex> Moar.URI.fix("http://www.example.com/")
"http://www.example.com/"

Lowercases the scheme:

iex> Moar.URI.fix("HttpS://www.example.com/")
"https://www.example.com/"

Unwraps CDATA:

iex> Moar.URI.fix("<![CDATA[http://example.com/]]>")
"http://example.com/"

@spec format(URI.t() | binary(), atom()) :: binary()

Formats a URI as a string with the given format. Format options:

scheme_host_port: converts to <scheme>://<host>[:<port>] format, where the port is only rendered if the original URI includes the port.

scheme_host_port_path: converts to <scheme>://<host>[:<port>]/<path> format, where the port is only rendered if the original URI included the port, and the path is rendered as / if the original URI does not include a path.

simple_string: converts to a simplified string representation of a URI for display purposes. Scheme, port, params, and fragments are removed. nil is converted to an empty string. The return value is not a valid URI.

iex> url = "https://www.example.com:446/crackers/potato%20chips/fruit?a=1&b=2#something"
iex> Moar.URI.format(url, :scheme_host_port)
"https://www.example.com:446"

iex> url = "https://www.example.com:446/crackers/potato%20chips/fruit?a=1&b=2#something"
iex> Moar.URI.format(url, :scheme_host_port_path)
"https://www.example.com:446/crackers/potato%20chips/fruit"

iex> url = "https://www.example.com:446/crackers/potato%20chips/fruit?a=1&b=2#something"
iex> Moar.URI.format(url, :simple_string)
"www.example.com/crackers/potato chips/fruit"

iex> Moar.URI.format(nil, :simple_string)
""

@spec to_simple_string(binary() | URI.t() | nil) :: binary()

Returns a simplified string representation of a URI for display purposes. Scheme, port, params, and fragments are removed. nil is converted to an empty string.

@spec valid?(URI.t()) :: boolean()

Returns false if the given URI does not have a scheme. For URIs whose scheme is mailto, returns true if the path is not blank (you can use https://hex.pm/packages/ex_email to validate the email address). For other schemes, returns true if the URI has a host, and if it has a path, the path does not contain spaces.

iex> Moar.URI.valid?(%URI{path: "alice@example.com", scheme: "mailto"})
true

iex> Moar.URI.valid?(%URI{host: "example.com", path: "users/1", scheme: "https"})
true

iex> Moar.URI.valid?(%URI{path: " ", scheme: "mailto"})
false

iex> Moar.URI.valid?(%URI{host: "example.com", path: "users/1", scheme: nil})
false

iex> Moar.URI.valid?(%URI{host: "example.com", path: "spaces not allowed", scheme: "https"})
false

@spec web_url?(nil | binary() | URI.t()) :: boolean()

Returns true when given a valid URI string with an http or https scheme.

iex> Moar.URI.web_url?(nil)
false

iex> Moar.URI.web_url?("ftp://example.org")
false

iex> Moar.URI.web_url?("http://example.org")
true