A2UICore.Catalog (A2UICore v0.1.1)

A versioned set of component and function definitions: the model of a catalog document.

from_json/2 reads a document into the model and to_json/2 writes it back, so from_json(document) |> to_json() equals the document (apart from components and functions its anyComponent / anyFunction unions leave out). Each component and function keeps its schema as written, with its allOf mixins and references; the catalog keeps the document's top-level fields. Two derived views are computed when a catalog is built:

validation_schema/1 (also the :schema field) — the self-contained JSON Schema messages are validated against (A2UICore.Catalog.ValidationSchema): components flattened, common types bundled, every reference local;
resolved_component_schema/2 and resolved_function_schema/2 — an entry's schema with references to the catalog's own $defs and to peer catalogs written inline, references to common types kept.

Peer catalogs

A catalog may reuse definitions of a catalog it holds, its peer, through an external $ref such as simplified_catalog_v1_0.json#/components/Text. with_peer_catalogs/2 returns a copy linked to peers, and link_catalogs/2 links a set of catalogs to one another; a reference that names no peer stays as written, so validating against it fails.

Loading rules

a catalogId must be known (option or document); the protocol version defaults to the document's protocolVersion, else 0.9;
components maps names to schema objects; functions is a map of name to definition or a list of %{"name" => …} definitions;
$defs.anyComponent / $defs.anyFunction, when they list #/components/X / #/functions/X references, restrict the catalog to those names;
from v1.0 on, component, property, function and argument names must be UAX #31 identifiers (no @ prefix: that namespace belongs to system functions);
the theme is read from a top-level theme, else $defs.theme.

Failures are {:error, %A2UICore.Error{category: :catalog}}.

Summary

Types

t()

Functions

common_definitions(version)

The $defs of the protocol version's common_types.json, with cross-document references made local. Empty for an unsupported version.

copy_with(catalog, options \\ [])

A copy of catalog for catalog transformers. Options: :components and :functions (the copy's entries; default: this catalog's) and :defs (its own $defs; default: this catalog's, without those only dropped entries referenced). An authored anyComponent / anyFunction union no longer describes changed entries, so it is listed from them instead.

cross_document?(catalog)

Whether the catalog document has a $ref that may name a peer catalog.

derive(catalog, catalog_id, options \\ [])

Returns a copy of catalog under another id, optionally without its functions (functions: false).

from_json(document, options \\ [])

Builds a catalog from a catalog document: a map, or a Jason.OrderedObject (Jason.decode(text, objects: :ordered_objects)), whose key order then orders the components and functions, as the anyComponent / anyFunction unions of the validation schema list them. A map's entries are ordered by name.

from_json!(document, options \\ [])

Like from_json/2, raising A2UICore.Error on failure.

get_component(catalog, name)

Looks a component up by name.

get_function(catalog, name)

Looks a function up by name. As in the reference, a name that differs from a declared one only in the case of its first letter also matches.

inline_refs(catalog, node, root, options \\ [])

Writes the local references of node (resolved in root, usually the catalog's document) and its references into the catalog's peers inline, keeping references to common types. A prompt uses this to find the common types a catalog reaches through its peers.

link_catalogs(catalogs, extra_peers \\ [])

The catalogs linked to one another for cross-catalog references: each catalog with a reference into another document is replaced by a copy whose peers are extra_peers followed by the other catalogs; the others are returned unchanged.

new(catalog_id, protocol_version, options \\ [])

Assembles a catalog from parts (a catalog defined in code).

new!(catalog_id, protocol_version, options \\ [])

Like new/3, raising A2UICore.Error on failure.

put_implementations(catalog, implementations)

Attaches function implementations by name. Names the catalog does not declare are ignored.

put_system_functions(catalog, functions)

Adds functions the runtime supplies (system functions such as @index), replacing any of the same name. They are evaluated like the catalog's own but are not part of its document or validation schema.

ref_spec(catalog, name)

The child-reference analysis of a component, or nil for an unknown one.

resolved_component_schema(catalog, name)

A component's schema with references to the catalog's own $defs and to peers written inline, or nil for an unknown component.

resolved_function_schema(catalog, name)

A function's schema with references resolved (see resolved_component_schema/2), or nil.

resolved_theme_schema(catalog)

The theme schema with references resolved.

to_json(catalog, options \\ [])

The catalog document, with references left as written: common types stay external (common_types.json#/$defs/X) and nothing is bundled. For the schema messages validate against, see validation_schema/1.

to_schema(catalog)

The self-contained catalog schema document; see validation_schema/1.

v1?(catalog)

Whether the catalog's protocol version is v1.0 or later.

validation_schema(catalog)

The self-contained schema messages validate against.

with_peer_catalogs(catalog, peers)

A copy of catalog that resolves cross-catalog references into peers, after the peers it already has (without duplicates). For a peer derived from another catalog by copy_with/2 (a pruned catalog), the catalog it was derived from comes first, so references to entries pruned from it still resolve. Returns catalog itself when peers adds none.

Types

t()

(since 0.1.0)

@type t() :: %A2UICore.Catalog{
  catalog_id: String.t(),
  common_types_uri: String.t(),
  component_order: [String.t()],
  components: %{optional(String.t()) => A2UICore.Catalog.Component.t()},
  declared_protocol_version: String.t() | nil,
  declares_catalog_id: boolean(),
  declares_components: boolean(),
  defs: map(),
  description: String.t() | nil,
  document_order: Jason.OrderedObject.t() | nil,
  extras: map(),
  function_order: [String.t()],
  functions: %{optional(String.t()) => A2UICore.Catalog.Function.t()},
  functions_form: :map | :list | nil,
  instructions: String.t() | nil,
  layout: map(),
  linked_from: t() | nil,
  peers: [t()],
  protocol_version: String.t(),
  ref_specs: %{optional(String.t()) => A2UICore.Catalog.RefSpec.t()},
  resolved: map(),
  schema: map(),
  schema_dialect: String.t() | nil,
  schema_id: String.t() | nil,
  source: t() | nil,
  theme: map(),
  theme_location: String.t() | nil,
  title: String.t() | nil,
  union_defs: %{optional(String.t()) => map() | nil} | nil
}

Functions

common_definitions(version)

(since 0.1.0)

@spec common_definitions(String.t()) :: map()

The $defs of the protocol version's common_types.json, with cross-document references made local. Empty for an unsupported version.

copy_with(catalog, options \\ [])

(since 0.1.0)

@spec copy_with(t(), keyword()) :: t()

cross_document?(catalog)

(since 0.1.0)

@spec cross_document?(t()) :: boolean()

Whether the catalog document has a $ref that may name a peer catalog.

derive(catalog, catalog_id, options \\ [])

(since 0.1.0)

@spec derive(t(), String.t(), keyword()) :: t()

Returns a copy of catalog under another id, optionally without its functions (functions: false).

from_json(document, options \\ [])

(since 0.1.0)

@spec from_json(map() | Jason.OrderedObject.t(), keyword()) ::
  {:ok, t()} | {:error, A2UICore.Error.t()}

Options: :catalog_id and :protocol_version take precedence over the document's catalogId / protocolVersion.

from_json!(document, options \\ [])

(since 0.1.0)

@spec from_json!(map() | Jason.OrderedObject.t(), keyword()) :: t()

Like from_json/2, raising A2UICore.Error on failure.

get_component(catalog, name)

(since 0.1.0)

@spec get_component(t(), term()) :: A2UICore.Catalog.Component.t() | nil

Looks a component up by name.

get_function(catalog, name)

(since 0.1.0)

@spec get_function(t(), term()) :: A2UICore.Catalog.Function.t() | nil

Looks a function up by name. As in the reference, a name that differs from a declared one only in the case of its first letter also matches.

inline_refs(catalog, node, root, options \\ [])

(since 0.1.0)

@spec inline_refs(t(), term(), map(), keyword()) :: term()

With ordered: true the peers' documents are read as to_json(peer, ordered: true), so that a node read from an ordered document keeps its key order wherever it is inlined.

link_catalogs(catalogs, extra_peers \\ [])

(since 0.1.0)

@spec link_catalogs([t()], [t()]) :: [t()]

new(catalog_id, protocol_version, options \\ [])

(since 0.1.0)

@spec new(String.t(), String.t(), keyword()) ::
  {:ok, t()} | {:error, A2UICore.Error.t()}

Assembles a catalog from parts (a catalog defined in code).

Options: :components and :functions (lists of A2UICore.Catalog.Component / A2UICore.Catalog.Function), :theme (a schema), :instructions, :defs (the catalog's own $defs).

new!(catalog_id, protocol_version, options \\ [])

(since 0.1.0)

@spec new!(String.t(), String.t(), keyword()) :: t()

Like new/3, raising A2UICore.Error on failure.

put_implementations(catalog, implementations)

(since 0.1.0)

@spec put_implementations(t(), %{
  optional(String.t()) => A2UICore.Catalog.Function.execute()
}) :: t()

Attaches function implementations by name. Names the catalog does not declare are ignored.

put_system_functions(catalog, functions)

(since 0.1.0)

@spec put_system_functions(t(), [A2UICore.Catalog.Function.t()]) :: t()

ref_spec(catalog, name)

(since 0.1.0)

@spec ref_spec(t(), String.t()) :: A2UICore.Catalog.RefSpec.t() | nil

The child-reference analysis of a component, or nil for an unknown one.

resolved_component_schema(catalog, name)

(since 0.1.0)

@spec resolved_component_schema(t(), String.t()) :: term()

A component's schema with references to the catalog's own $defs and to peers written inline, or nil for an unknown component.

resolved_function_schema(catalog, name)

(since 0.1.0)

@spec resolved_function_schema(t(), String.t()) :: term()

A function's schema with references resolved (see resolved_component_schema/2), or nil.

resolved_theme_schema(catalog)

(since 0.1.0)

@spec resolved_theme_schema(t()) :: map()

The theme schema with references resolved.

to_json(catalog, options \\ [])

(since 0.1.0)

@spec to_json(t(), keyword()) :: map() | Jason.OrderedObject.t()

With ordered: true the objects of the document are Jason.OrderedObjects, so that Jason.encode!/1 writes it in the reference's key order: the top-level fields in a fixed order, and what was read from a document decoded with objects: :ordered_objects in that document's order.

to_schema(catalog)

(since 0.1.0)

@spec to_schema(t()) :: map()

The self-contained catalog schema document; see validation_schema/1.

v1?(catalog)

(since 0.1.0)

@spec v1?(t()) :: boolean()

Whether the catalog's protocol version is v1.0 or later.

validation_schema(catalog)

(since 0.1.0)

@spec validation_schema(t()) :: map()

The self-contained schema messages validate against.

with_peer_catalogs(catalog, peers)

(since 0.1.0)

@spec with_peer_catalogs(t(), [t()]) :: t()