# `Macaw.Layers.Url`
[🔗](https://github.com/dcoai/macaw_layers/blob/v0.4.0/lib/macaw/layers/url.ex#L1)

A URL a document holds, a kernel term (spec/01 §8.2): the text as written, and for a
template whose host rotates over `{s}`, the subdomains it rotates over. Because a URL is a
term of its own, the kernel finds every URL in any document by its type, and a host's
policy (`Macaw.Layers.Url.Policy`) judges them all the same way; no document type lists
its URL fields.

Whether a URL is well formed is the value's, and every host agrees on it: `new/2` judges
it, and the reader of its map form, `{"$url": text}`, calls `new/2`. Whether a host
allows it is the host's, and is never part of the value.

    iex> {:ok, url} = Macaw.Layers.Url.new("https://tiles.example/{z}/{x}/{y}.png")
    iex> Macaw.Layers.Url.text(url)
    "https://tiles.example/{z}/{x}/{y}.png"
    iex> Macaw.Layers.Url.new("/relative/path")
    {:error, :relative}
    iex> Macaw.Layers.Url.new("https://user:secret@host.example/")
    {:error, :userinfo}

`%URI{}` is not used: it holds no template, and parses `{` and `}` as it pleases.

# `reason`

```elixir
@type reason() :: :relative | :malformed | :userinfo | :no_host | :subdomains
```

Why a text is not a URL:
- `:relative`, it has no scheme;
- `:malformed`, it holds whitespace, a control character, invalid UTF-8 or an unclosed
  or unnamed placeholder, or a `data:` URL has no `,`;
- `:userinfo`, it has a user or a password before its host, which a document may never
  carry;
- `:no_host`, an `http:` or `https:` URL without a host;
- `:subdomains`, a `{s}` outside the host, a `{s}` host with no subdomains or subdomains
  with no `{s}`, or a subdomain that is not a host label.

# `t`

```elixir
@type t() :: %Macaw.Layers.Url{subdomains: [String.t()], text: String.t()}
```

A URL: its text, and the subdomains a `{s}` host rotates over.

# `data_type`

```elixir
@spec data_type(t()) :: String.t() | nil
```

A `data:` URL's media type, lower-cased (`"image/png"`), or `nil` for another scheme.

# `hosts`

```elixir
@spec hosts(t()) :: [String.t()]
```

The hosts the URL reaches, lower-cased: its host, or one per subdomain of a `{s}` host;
`[]` for a URL with no host (`data:`).

# `new`

```elixir
@spec new(term(), keyword()) :: {:ok, t()} | {:error, reason()}
```

The URL `text` names, or why it is none. `subdomains:` the hosts' labels a `{s}` host
rotates over, `[]` by default.

    iex> {:ok, url} = Macaw.Layers.Url.new("https://{s}.tile.example/{z}.png", subdomains: ["a", "b"])
    iex> Macaw.Layers.Url.hosts(url)
    ["a.tile.example", "b.tile.example"]
    iex> Macaw.Layers.Url.new("https://{s}.tile.example/{z}.png")
    {:error, :subdomains}

# `scheme`

```elixir
@spec scheme(t()) :: String.t() | nil
```

The URL's scheme, lower-cased.

    iex> Macaw.Layers.Url.scheme(%Macaw.Layers.Url{text: "HTTPS://a.example/"})
    "https"

# `text`

```elixir
@spec text(t()) :: String.t()
```

The URL's text, as written.

---

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