# `Image.Plug.Provider.IIIF.URL`
[🔗](https://github.com/elixir-image/image_plug/blob/v0.1.0/lib/image/plug/provider/iiif/url.ex#L1)

Recognises [IIIF Image API 3.0](https://iiif.io/api/image/3.0/)
URL forms in `Plug.Conn.path_info` and returns a structured result
the higher-level provider dispatches on.

Two forms are recognised:

* `<mount>/<endpoint>/<identifier>/info.json` — the IIIF discovery
  document. Tagged `:info_json` in the result; the provider routes
  these to the `Format{type: :json}` encoder path.

* `<mount>/<endpoint>/<identifier>/<region>/<size>/<rotation>/<quality>.<format>`
  — the standard image URL. Tagged `:image`; the provider hands the
  five option segments to `Image.Plug.Provider.IIIF.Options.parse/2`.

### Configuration

* `:mount` — string path prefix this plug is mounted under;
  stripped before parsing. Defaults to `""`.

* `:endpoint` — the IIIF version-prefix segment (e.g. `"iiif/3"`,
  `"image"`, or `""` for servers that publish at the mount root).
  Defaults to `"iiif/3"`.

# `recognised`

```elixir
@type recognised() :: %{
  :kind =&gt; :image | :info_json,
  :source =&gt; Image.Plug.Source.t(),
  optional(:options_segments) =&gt;
    {String.t(), String.t(), String.t(), String.t()}
}
```

The recognised URL shape.

* `:kind` is `:image` or `:info_json`.

* `:source` is the resolved `Image.Plug.Source` for the asset.

* `:options_segments` (only for `:kind == :image`) is the four-tuple
  `{region, size, rotation, quality_dot_format}` extracted from the
  URL — left to `Image.Plug.Provider.IIIF.Options.parse/2` to decode.

# `parse`

```elixir
@spec parse(
  Plug.Conn.t(),
  keyword()
) :: {:ok, recognised()} | {:error, Image.Plug.Error.t()}
```

Parses the request path into a recognised IIIF URL shape.

### Arguments

* `conn` is a `Plug.Conn`. Only `path_info` is read.

* `options` is a keyword list — see the Options section.

### Options

* `:mount` — see the moduledoc.

* `:endpoint` — see the moduledoc.

### Returns

* `{:ok, recognised}` on a successful match.

* `{:error, %Image.Plug.Error{}}` when the path doesn't match any
  IIIF form.

### Examples

    iex> conn = %Plug.Conn{path_info: ["iiif", "3", "cat.jpg", "full", "max", "0", "default.jpg"]}
    iex> {:ok, parsed} = Image.Plug.Provider.IIIF.URL.parse(conn, [])
    iex> parsed.kind
    :image

    iex> conn = %Plug.Conn{path_info: ["iiif", "3", "cat.jpg", "info.json"]}
    iex> {:ok, parsed} = Image.Plug.Provider.IIIF.URL.parse(conn, [])
    iex> parsed.kind
    :info_json

---

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