# `Sake.Elicit`
[🔗](https://github.com/hattoriai/sake/blob/v0.4.3/lib/sake/elicit.ex#L1)

Asks the person for input from inside a component.

    case Sake.Elicit.form(ctx, :who, "Who should be greeted?", schema) do
      {:ok, %{"name" => name}} -> ...
      :decline -> ...
      :cancel -> ...
      {:error, :unsupported} -> ...
    end

On a modern connection the call ends the handler; Sake answers the client
with an input-required result, and when the client retries, the handler
runs again and the same call returns the answer. So a handler must have
no side effects before its elicitation calls. On a legacy connection the
call blocks until the client answers on the stream; the request carries
the handler's key in `_meta` under `"ai.hattori.sake/key"`, so a client
can tell which question is being asked. Inside a task (see `Sake.Tasks`)
the call waits until the client answers through `tasks/update`; a task
cancelled meanwhile reads as `:cancel`.

# `form`

```elixir
@spec form(Sake.Context.t(), atom() | String.t(), String.t(), map()) ::
  {:ok, map()} | :decline | :cancel | {:error, :unsupported}
```

# `url`

```elixir
@spec url(Sake.Context.t(), atom() | String.t(), String.t(), String.t()) ::
  :ok | :decline | :cancel | {:error, :unsupported}
```

---

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