# `Stevedore.Reference`
[🔗](https://github.com/oshlabs/stevedore/blob/v0.2.0/lib/stevedore/reference.ex#L1)

A parsed, normalized image reference: registry, repository, and a tag or digest.

Parsing applies Docker/OCI normalization (the `distribution/reference` rules): a name with no
registry component defaults to Docker Hub (`registry-1.docker.io`), a single-segment Hub repo
gets the `library/` prefix, and a reference with neither tag nor digest defaults to the
`latest` tag.

This models only the *name* part. Transport prefixes (`docker://`, `oci:`) are parsed by the
transport layer in a later phase.

Spec: [distribution/reference grammar](https://github.com/distribution/reference/blob/main/reference.go)
and [Docker Registry HTTP API v2](https://distribution.github.io/distribution/spec/api/).

# `t`

```elixir
@type t() :: %Stevedore.Reference{
  digest: Stevedore.Digest.t() | nil,
  registry: String.t(),
  repository: String.t(),
  tag: String.t() | nil
}
```

# `parse`

```elixir
@spec parse(String.t()) :: {:ok, t()} | {:error, {:bad_input, term()}}
```

Parses an image reference string, applying Docker/OCI normalization.

## Examples

    iex> {:ok, ref} = Stevedore.Reference.parse("alpine:3.20")
    iex> {ref.registry, ref.repository, ref.tag}
    {"registry-1.docker.io", "library/alpine", "3.20"}

    iex> {:ok, ref} = Stevedore.Reference.parse("ghcr.io/owner/app")
    iex> {ref.registry, ref.repository, ref.tag}
    {"ghcr.io", "owner/app", "latest"}

    iex> {:ok, ref} = Stevedore.Reference.parse("localhost:5000/app@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
    iex> {ref.registry, ref.tag, ref.digest.algorithm}
    {"localhost:5000", nil, :sha256}

# `to_string`

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

Renders a reference back to its canonical `registry/repository[:tag][@digest]` string.

The output re-parses to an equal reference.

## Examples

    iex> {:ok, ref} = Stevedore.Reference.parse("alpine")
    iex> Stevedore.Reference.to_string(ref)
    "registry-1.docker.io/library/alpine:latest"

---

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