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

Compiles an Express block into A2UI messages.

    {:ok, catalogs} = A2UIAgent.Express.Catalogs.new([catalog])

    A2UIAgent.Express.Compiler.compile(catalogs, ~s(root = Text("Hello")), surface_id: "s1")
    #=> {:ok, [%{"version" => "v1.0", "createSurface" => %{"surfaceId" => "s1", ...}}]}

Statements group into surfaces. `surface("id")` opens a surface (with
`sendDataModel=` and `update=` keywords); assignments before any
`surface` line belong to the default surface. In a surface:

  * a variable assigned a component becomes a component whose id is
    the variable's name (or its `id=` argument); a component written
    inline as an argument becomes a component with the id
    `<parent>_<property>` (`<parent>_<property>_<index>` in a list);
  * a variable assigned anything else is substituted where it is used;
  * `$/a/b = value` writes the data model.

A surface with a `root` component becomes `createSurface` (followed by
`updateComponents` and `updateDataModel` before v1.0); with
`update=true`, or without a `root`, it becomes `updateComponents` and
`updateDataModel`. `deleteSurface("id")` deletes a surface, and a
standalone function call becomes `callRendererFunction` (v1.0) with
the id `call_<n>` unless it has a `functionCallId=` argument.

Positional arguments follow `A2UIAgent.Express.SchemaHelper`'s order,
`_` skips one, and keyword arguments name a property. Check rules
(`?name(...)`) go in the component's check property; a check whose
first parameter is `value` receives the component's bound `value`
unless its first argument is a path, and a trailing string argument is
its message (default `"<Name> check failed"`). In an action property a
function call is written as `{"functionCall": ...}`, and
`Event(name, context)` writes an event.

# `compile`
*since 0.1.0* 

```elixir
@spec compile(A2UIAgent.Express.Catalogs.t(), String.t(), keyword()) ::
  {:ok, [map()]} | {:error, A2UICore.Error.t()}
```

Compiles `block`. Options: `:surface_id`, the surface of assignments
before any `surface` line (default `"default_surface"`), and `:final`
(default true). A block that is not final (its closing tag has not
arrived) compiles the statements before its first syntax error.

A syntax error, or a block that breaks Express's own rules, is a
`:parse` error; a block naming what the catalogs do not define, or
giving a value they do not admit, is a `:validation` error.

# `default_message`
*since 0.1.0* 

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

The message a check rule gets when it names none: the check's name,
capitalized, followed by `check failed`.

    iex> A2UIAgent.Express.Compiler.default_message("regex")
    "Regex check failed"

# `set_path`
*since 0.1.0* 

```elixir
@spec set_path(map(), String.t(), term()) :: map()
```

Writes `value` at an Express data path (`$/a/b`) into `data_model`,
creating the objects on the way. The path `$` writes nothing.

    iex> A2UIAgent.Express.Compiler.set_path(%{"a" => 1}, "$/user/name", "Ada")
    %{"a" => 1, "user" => %{"name" => "Ada"}}

---

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