# `Moar.URI`
[🔗](https://github.com/synchronal/moar/blob/main/lib/uri.ex#L1)

URI/URL-related functions.

# `fix`

```elixir
@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:

```elixir
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:

```elixir
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:

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

Unwraps CDATA:

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

# `format`

```elixir
@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.

```elixir
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)
""
```

# `to_simple_string`

> This function is deprecated. Use `Moar.URI.format/2` with the `:simple_string` argument..

```elixir
@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.

# `valid?`

```elixir
@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.

```elixir
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
```

# `web_url?`

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

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

```elixir
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
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*