Macaw.Layers.Url (macaw_layers v0.4.0)

Copy Markdown View Source

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

Types

Why a text is not a URL

t()

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.

The URL's scheme, lower-cased.

The URL's text, as written.

Types

reason()

@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()

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

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

Functions

data_type(url)

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

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

hosts(url)

@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(text, opts \\ [])

@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(url)

@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(url)

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

The URL's text, as written.