# `Ussd.State`
[🔗](https://github.com/spesohq/ussd/blob/main/lib/ussd/state.ex#L1)

A screen in a USSD flow.

    defmodule MyApp.States.Welcome do
      use Ussd.State, initial: true

      alias Ussd.Decisions.Equal

      transition Equal.new("1"), to: MyApp.States.Airtime
      transition Equal.new("2"), to: MyApp.States.DataBundle

      @impl Ussd.State
      def render(_context) do
        Ussd.Menu.build()
        |> Ussd.Menu.line("Welcome")
        |> Ussd.Menu.listing(["Airtime", "Data Bundle"])
      end
    end

`use Ussd.State` accepts:

  * `:initial` - advisory metadata (default `false`) read by `mix ussd.lint` to
    auto-discover flow entry points when none are given explicitly. It is not
    enforced by `Ussd.use_initial_state/2`.
  * `:continue` - when `true`, also requires `@behaviour Ussd.ContinueState` (a
    `confirm/0` callback), and marks this state eligible as the
    `continuing_state` argument to `Ussd.use_continuing_state/4`.

Inside the module body, five macros build the state's routing:

  * `transition(decision, to: Module, callback: fun \\ nil)` - repeatable; the
    first one whose decision matches the input wins.
  * `back(decision, callback: fun \\ nil)` - returns to whatever state pushed
    this one onto the session's back-stack.
  * `paginate(next: decision, previous: decision \\ nil, callback: fun \\ nil)` -
    requires `use Ussd.Pagination` in the same module.
  * `truncate(limit: n, ending: string, more: decision)` - caps how much of
    `render/1`'s output is returned per screen.
  * `terminate()` - marks this state as ending the session once reached with no
    further input expected.

A state with none of these raises `Ussd.Exceptions.NextStateNotFoundError` the
moment it's reached with input that doesn't match anything - `mix ussd.lint` finds
these before your users do.

# `render`

```elixir
@callback render(Ussd.Context.t()) :: Ussd.Menu.t()
```

# `back`
*macro* 

Registers this state's back-navigation rule.

# `paginate`
*macro* 

Registers this state's pagination rule. Requires `use Ussd.Pagination`.

# `terminate`
*macro* 

Marks this state as ending the session once reached.

# `transition`
*macro* 

Registers a routing rule: when `decision` matches the input, move to `to:`.

# `truncate`
*macro* 

Registers this state's response-truncation rule.

---

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