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

Blank/present functions for terms.

A term is considered present when it is not blank.

A term is considered blank when:

* it is `nil`
* it is `false`
* it is a string, and its length after being trimmed is 0
* it is an empty list
* it is an empty map

# `blank?`

```elixir
@spec blank?(any()) :: boolean()
```

Returns true if the term is blank, nil, false, or empty.

```elixir
iex> Moar.Term.blank?(nil)
true

iex> Moar.Term.blank?("   ")
true

iex> Moar.Term.blank?([])
true

iex> Moar.Term.blank?(%{})
true
```

# `blank?`

```elixir
@spec blank?(any(), blank: [any()], present: [any()]) :: boolean()
```

Like `blank?/1` but takes a keyword list containing `blank` and/or `present` keys that override the default behavior.

```elixir
iex> Moar.Term.blank?("--")
false

iex> Moar.Term.blank?("--", blank: ["--"], present: [0, false])
true
```

# `presence`

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

Returns the value if it is present (via `present?`), or else returns the default value.

```elixir
iex> Moar.Term.presence(20, 100)
20

iex> Moar.Term.presence(nil, 100)
100
```

# `present?`

```elixir
@spec present?(any()) :: boolean()
```

Returns true if the term is not blank, nil, false, or empty.

```elixir
iex> Moar.Term.present?(1)
true

iex> Moar.Term.present?([1])
true

iex> Moar.Term.present?(%{a: 1})
true

iex> Moar.Term.present?("1")
true
```

# `present?`

```elixir
@spec present?(
  any(),
  keyword()
) :: boolean()
```

Like `present?/1` but takes a keyword list containing `blank` and/or `present` keys that override the default behavior.

```elixir
iex> Moar.Term.present?(false)
false

iex> Moar.Term.present?(false, blank: ["--"], present: [0, false])
true
```

# `when_present`

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

Returns `present_value` when `term` is present (via `present?`), and `blank_value` when `term` is blank.
If `present_value` and/or `blank_value` are functions, they are called with `term` as their argument.

```elixir
iex> Moar.Term.when_present(20, "continue", "value missing")
"continue"

iex> Moar.Term.when_present(nil, "continue", "value missing")
"value missing"

iex> Moar.Term.when_present(20, fn value -> value * 2 end, "value missing")
40

iex> Moar.Term.when_present(nil, "continue", fn value -> "expected a number, got: #{inspect(value)}" end)
"expected a number, got: nil"
```

---

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