# `A2UIAgent.CatalogProvider`
[🔗](https://github.com/a2ui-elixir/a2ui/blob/v0.1.1/umbrella/apps/a2ui_agent/lib/a2ui_agent/catalog_provider.ex#L1)

Loads catalog documents into `A2UICore.Catalog`s.

    {:ok, catalog} = A2UIAgent.CatalogProvider.load_file("priv/catalogs/basic.json")

    {:ok, catalog} =
      A2UIAgent.CatalogProvider.load_document(document,
        catalog_id: "acme/forms",
        protocol_version: "v1.0"
      )

Both functions take `:catalog_id` and `:protocol_version`. Each one
supplies what the document omits and must agree with what the document
states: a document that declares `"catalogId": "a"` read with
`catalog_id: "b"` is an error, since one of the two is wrong. When
neither the document nor the options name the catalog or its protocol
version, loading fails, because nothing else can.

Every failure is an `A2UICore.Error` of category `:catalog`.

# `option`
*since 0.1.0* 

```elixir
@type option() :: {:catalog_id, String.t()} | {:protocol_version, String.t()}
```

`:catalog_id` and `:protocol_version`, both optional.

# `load_document`
*since 0.1.0* 

```elixir
@spec load_document(term(), [option()]) ::
  {:ok, A2UICore.Catalog.t()} | {:error, A2UICore.Error.t()}
```

Loads a catalog from a decoded catalog document: a map, or a
`Jason.OrderedObject` (decoded with `objects: :ordered_objects`) to
keep its key order.

# `load_document!`
*since 0.1.0* 

```elixir
@spec load_document!(term(), [option()]) :: A2UICore.Catalog.t()
```

Like `load_document/2`, raising `A2UICore.Error` on failure.

# `load_file`
*since 0.1.0* 

```elixir
@spec load_file(String.t(), [option()]) ::
  {:ok, A2UICore.Catalog.t()} | {:error, A2UICore.Error.t()}
```

Reads a catalog document from a filesystem path or a `file://` URL.

The file must hold a JSON object. Its key order orders the catalog's
components and functions, and the document `A2UICore.Catalog.to_json/2`
writes.

# `load_file!`
*since 0.1.0* 

```elixir
@spec load_file!(String.t(), [option()]) :: A2UICore.Catalog.t()
```

Like `load_file/2`, raising `A2UICore.Error` on failure.

---

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