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

A fluent builder for the text a `Ussd.State` renders back to the caller.

Build one with `build/0` and grow it with the pipe operator:

    Ussd.Menu.build()
    |> Ussd.Menu.text("Welcome")
    |> Ussd.Menu.line("Select an option")
    |> Ussd.Menu.listing(["Airtime", "Data Bundle"])

Implements `String.Chars`, so a menu can be interpolated or passed anywhere a
string is expected.

# `t`

```elixir
@type t() :: %Ussd.Menu{content: String.t()}
```

# `append`

```elixir
@spec append(t(), t() | (t() -> t())) :: t()
```

Appends another menu's content, or the menu built by a `(menu -> menu)` function.

# `build`

```elixir
@spec build() :: t()
```

Starts an empty menu.

# `format`

```elixir
@spec format(t(), String.t() | charlist(), [term()]) :: t()
```

Appends `:io_lib.format/2`-formatted text, e.g. `format(menu, "Balance: ~s", ["GHS 10"])`.

# `line`

```elixir
@spec line(t(), String.t()) :: t()
```

Appends text followed by a newline.

# `line_break`

```elixir
@spec line_break(t(), pos_integer()) :: t()
```

Appends `times` blank lines (default 1).

# `listing`

```elixir
@spec listing(t(), [String.Chars.t()], keyword()) :: t()
```

Appends a numbered listing of `items`.

Options:

  * `:numbering` - `(index :: non_neg_integer() -> String.Chars.t())`, defaults to `&(&1 + 1)`
  * `:spacer` - separates the number from the item, defaults to `"."`
  * `:divider` - separates items, defaults to `"\n"`
  * `:page` / `:per_page` - slice `items` before rendering, like Laravel's paginated listings

# `prepend`

```elixir
@spec prepend(t(), t() | (t() -> t())) :: t()
```

Prepends another menu's content, or the menu built by a `(menu -> menu)` function.

# `text`

```elixir
@spec text(t(), String.t()) :: t()
```

Appends raw text with no trailing newline.

# `trans`

```elixir
@spec trans(t(), String.t(), map(), String.t() | nil) :: t()
```

Appends `key` translated via the configured Gettext backend (see `trans/4`).

# `trans_line`

```elixir
@spec trans_line(t(), String.t(), map(), String.t() | nil) :: t()
```

Like `trans/4`, but followed by a newline - the translated counterpart to `line/2`.

---

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