# `MonEx.Option`
[🔗](https://github.com/youroff/monex/blob/v0.2.1/lib/monex/option.ex#L1)

An `Option` represents a value that may or may not be present:

  * `some(value)` — a value is present
  * `none()` — no value

Pattern matching on either form requires the parentheses. The runtime
representation is just a tuple (`{:some, value}` or `{:none}`), so it
costs nothing.

# `t`

```elixir
@type t(a) :: {:some, a} | {:none}
```

Option type.
`some(a)` and `none()` expand to `{:some, a}` and `{:none}` respectively.

# `get`

```elixir
@spec get(t(a)) :: a when a: any()
```

Returns the wrapped value if the argument is `some()`. If `none()`,
raises a `RuntimeError` with the message `"Can't get value of None"`.

## Examples
    iex> some(5) |> get
    5

# `get_or_else`

```elixir
@spec get_or_else(t(a), a | (-> a)) :: a when a: any()
```

Returns the wrapped value if the argument is `some()`. If `none()`,
returns the second argument — either a value directly, or a 0-arity
function returning one.

## Examples
    iex> some(5) |> get_or_else(2)
    5

    iex> none() |> get_or_else(2)
    2

    iex> none() |> get_or_else(fn -> 1 end)
    1

# `is_none`

```elixir
@spec is_none(t(any())) :: boolean()
```

Returns `true` if the argument is `none()`, `false` if `some()`.

## Examples
    iex> is_none(none())
    true

    iex> is_none(some(5))
    false

# `is_some`

```elixir
@spec is_some(t(any())) :: boolean()
```

Returns `true` if the argument is `some()`, `false` if `none()`.

## Examples
    iex> is_some(some(5))
    true

    iex> is_some(none())
    false

# `none`
*macro* 

Constructor macro: `none()` expands to `{:none}`. Works in both
expressions and patterns.

# `ok_or_else`

```elixir
@spec ok_or_else(t(a), err | (-> err)) :: MonEx.Result.t(a, err)
when a: any(), err: any()
```

Converts an `Option` into a `Result`. `some(val)` becomes `ok(val)`;
`none()` becomes `error(...)` carrying the second argument (or the
result of calling it, if a 0-arity function is supplied).

## Examples
    iex> some(5) |> ok_or_else(2)
    {:ok, 5} # same as ok(5)

    iex> none() |> ok_or_else(:missing_value)
    {:error, :missing_value} # same as error(:missing_value)

    iex> none() |> ok_or_else(fn -> :oh_no end)
    {:error, :oh_no}

# `or_else`

```elixir
@spec or_else(t(a), t(a) | (-> t(a))) :: t(a) when a: any()
```

Returns the input as-is if it is `some()`. If `none()`, returns the
second argument — either an `Option` directly, or a 0-arity function
returning one.

## Examples
    iex> some(5) |> or_else(some(2))
    some(5)

    iex> none() |> or_else(some(2))
    some(2)

    iex> none() |> or_else(fn -> some(1) end)
    some(1)

# `some`
*macro* 

Constructor macro: `some(val)` expands to `{:some, val}`. Works in both
expressions and patterns.

# `to_option`

```elixir
@spec to_option(a) :: t(a) when a: any()
```

Lifts an arbitrary term into an `Option`: `some(term)` if non-`nil`,
`none()` otherwise.

## Examples
    iex> to_option(5)
    some(5)

    iex> to_option(nil)
    none()

---

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