object

# `optional`

Constructors for optional terms. An optional term is either empty or holds a value. Optional terms should be regarded as opaque terms and always used with the `optional/1` object by passing the optional term as a parameter.

Author: Paulo Moura
Version: 2:1:0
Date: 2021-01-03
Compilation flags:
`static, context_switching_calls`
Provides:
type::type/1
type::check/2
Remarks:

> - Type-checking support: This object also defines a type `optional` for use with the `type` library object.

Inherited public predicates:
(none)

## Public predicates

### `empty/1`

Constructs an empty optional term.

Compilation flags:
`static`
Template:
`empty(Optional)`
Mode and number of proofs:
`empty(--nonvar)` - `one`

### `of/2`

Constructs an optional term holding the given value.

Compilation flags:
`static`
Template:
`of(Value,Optional)`
Mode and number of proofs:
`of(@term,--nonvar)` - `one`

### `from_goal/3`

Constructs an optional term holding a value bound by calling the given goal. Returns an empty optional term if the goal fails or throws an error.

Compilation flags:
`static`
Template:
`from_goal(Goal,Value,Optional)`
Meta-predicate template:
`from_goal(0,*,*)`
Mode and number of proofs:
`from_goal(+callable,--term,--nonvar)` - `one`

### `from_goal/2`

Constructs an optional term holding a value bound by calling the given closure. Returns an empty optional term if the closure fails or throws an error.

Compilation flags:
`static`
Template:
`from_goal(Closure,Optional)`
Meta-predicate template:
`from_goal(1,*)`
Mode and number of proofs:
`from_goal(+callable,--nonvar)` - `one`

### `from_generator/3`

Constructs optional terms with the values generated by calling the given goal. On goal error or failure, returns an empty optional.

Compilation flags:
`static`
Template:
`from_generator(Goal,Value,Optional)`
Meta-predicate template:
`from_generator(0,*,*)`
Mode and number of proofs:
`from_generator(+callable,--term,--nonvar)` - `one_or_more`

### `from_generator/2`

Constructs optional terms with the values generated by calling the given closure. On closure error or failure, returns an empty optional.

Compilation flags:
`static`
Template:
`from_generator(Closure,Optional)`
Meta-predicate template:
`from_generator(1,*)`
Mode and number of proofs:
`from_generator(+from_generator,--nonvar)` - `one_or_more`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

(no local declarations; see entity ancestors if any)

## Operators

(none)

See also

optional(Optional), type