# `Moar.Sugar`
[🔗](https://github.com/synchronal/moar/blob/main/lib/sugar.ex#L1)

Syntactic sugar functions.

These functions are intended to be used by importing the functions or the whole module:

```
import Moar.Sugar, only: [noreply: 1]

def handle_event("foo", _params, socket) do
  socket |> assign(foo: "bar") |> noreply()
end
```

# `cont`

```elixir
@spec cont(term()) :: {:cont, term()}
```

Wraps a term in a :cont tuple. Useful in pipelines.

```elixir
iex> %{} |> Map.put(:count, "unknown") |> Moar.Sugar.cont()
{:cont, %{count: "unknown"}}
```

# `cont!`

```elixir
@spec cont!({:cont, term()}) :: term()
```

Unwraps a :cont tuple, raising if the term is not an :cont tuple.

```elixir
iex> {:cont, 1} |> Moar.Sugar.cont!()
1
```

# `error`

```elixir
@spec error(term()) :: {:error, term()}
```

Wraps a term in an :error tuple. Useful in pipelines.

```elixir
iex> %{} |> Map.put(:count, "unknown") |> Moar.Sugar.error()
{:error, %{count: "unknown"}}
```

# `error!`

```elixir
@spec error!({:error, term()}) :: term()
```

Unwraps an :error tuple, raising if the term is not an :error tuple.

```elixir
iex> {:error, 1} |> Moar.Sugar.error!()
1
```

# `halt`

```elixir
@spec halt(term()) :: {:halt, term()}
```

Wraps a term in a :halt tuple. Useful in pipelines.

```elixir
iex> %{} |> Map.put(:count, "unknown") |> Moar.Sugar.halt()
{:halt, %{count: "unknown"}}
```

# `halt!`

```elixir
@spec halt!({:halt, term()}) :: term()
```

Unwraps a :halt tuple, raising if the term is not an :halt tuple.

```elixir
iex> {:halt, 1} |> Moar.Sugar.halt!()
1
```

# `noreply`

```elixir
@spec noreply(term()) :: {:noreply, term()}
```

Wraps a term in a :noreply tuple. Useful in pipelines.

```elixir
iex> %{} |> Map.put(:count, 0) |> Moar.Sugar.noreply()
{:noreply, %{count: 0}}
```

# `noreply!`

```elixir
@spec noreply!({:noreply, term()}) :: term()
```

Unwraps a :noreply tuple, raising if the term is not an :noreply tuple.

```elixir
iex> {:noreply, 1} |> Moar.Sugar.noreply!()
1
```

# `ok`

```elixir
@spec ok(term()) :: {:ok, term()}
```

Wraps a term in an :ok tuple. Useful in pipelines.

```elixir
iex> %{} |> Map.put(:count, 10) |> Moar.Sugar.ok()
{:ok, %{count: 10}}
```

# `ok!`

```elixir
@spec ok!({:ok, term()}) :: term()
```

Unwraps an :ok tuple, raising if the term is not an :ok tuple.

```elixir
iex> {:ok, 1} |> Moar.Sugar.ok!()
1
```

# `reply`

```elixir
@spec reply(term(), term()) :: {:reply, term(), term()}
```

Wraps two terms in a :reply tuple, reversing the terms. Useful in pipelines.

```elixir
iex> %{} |> Map.put(:count, 0) |> Moar.Sugar.reply(:ok)
{:reply, :ok, %{count: 0}}
```

# `returning`

```elixir
@spec returning(any(), any()) :: any()
```

Accepts two arguments and returns the second.

Useful at the end of the pipeline when you want to return a different value than the last result of the pipeline,
such as when the pipeline has side effects.

```elixir
iex> %{} |> Map.put(:count, 20) |> Moar.Sugar.returning(:count_updated)
:count_updated
```

# `then_if`

```elixir
@spec then_if(term(), term(), (term() -> term())) :: term()
```

Accepts an argument and passes it into the given function if the condition is truthy.

``` elixir
iex> 1 |> Moar.Sugar.then_if(nil, &(&1 + 1))
1
iex> 1 |> Moar.Sugar.then_if(false, &(&1 + 1))
1

iex> 1 |> Moar.Sugar.then_if("exists", &(&1 + 1))
2
```

---

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