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.
Summary
Functions
A data: URL's media type, lower-cased ("image/png"), or nil for another scheme.
The hosts the URL reaches, lower-cased: its host, or one per subdomain of a {s} host;
[] for a URL with no host (data:).
The URL text names, or why it is none. subdomains: the hosts' labels a {s} host
rotates over, [] by default.
The URL's scheme, lower-cased.
The URL's text, as written.
Types
@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 adata:URL has no,;:userinfo, it has a user or a password before its host, which a document may never carry;:no_host, anhttp:orhttps: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.
A URL: its text, and the subdomains a {s} host rotates over.
Functions
A data: URL's media type, lower-cased ("image/png"), or nil for another scheme.
The hosts the URL reaches, lower-cased: its host, or one per subdomain of a {s} host;
[] for a URL with no host (data:).
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}
The URL's scheme, lower-cased.
iex> Macaw.Layers.Url.scheme(%Macaw.Layers.Url{text: "HTTPS://a.example/"})
"https"
The URL's text, as written.