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.

Availability:
logtalk_load(optionals(loader))
Author: Paulo Moura
Version: 2:2:0
Date: 2026-02-21
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. Also returns an empty optional term if the goal throws an error, silently discarding the error information. Use from_goal_or_throw/3 if exceptions should be propagated or the expected library from_goal/3 predicate if error information should be preserved.

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. Also returns an empty optional term if the closure throws an error, silently discarding the error information. Use from_goal_or_throw/2 if exceptions should be propagated or the expected library from_goal/2 predicate if error information should be preserved.

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 failure, returns an empty optional. On goal error, also returns an empty optional, silently discarding the error information.

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 failure, returns an empty optional. On closure error, also returns an empty optional, silently discarding the error information.

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

from_goal_or_throw/3

Constructs an optional term holding a value bound by calling the given goal. Returns an empty optional term if the goal fails. Propagates any exception thrown by the goal.

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

from_goal_or_throw/2

Constructs an optional term holding a value bound by calling the given closure. Returns an empty optional term if the closure fails. Propagates any exception thrown by the closure.

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

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