.. index:: single: optional .. _optional/0:

.. rst-class:: right

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: | :ref:`type::type/1 <type/0::type/1>` | :ref:`type::check/2 <type/0::check/2>`

| Remarks:

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

| Inherited public predicates: | (none)

.. contents:: :local: :backlinks: top

Public predicates

.. index:: empty/1 .. _optional/0::empty/1:

empty/1 ^^^^^^^^^^^

Constructs an empty optional term.

| Compilation flags: | static

| Template: | empty(Optional) | Mode and number of proofs: | empty(--nonvar) - one

---

.. index:: of/2 .. _optional/0::of/2:

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

---

.. index:: from_goal/3 .. _optional/0::from_goal/3:

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

---

.. index:: from_goal/2 .. _optional/0::from_goal/2:

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

---

.. index:: from_generator/3 .. _optional/0::from_generator/3:

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

---

.. index:: from_generator/2 .. _optional/0::from_generator/2:

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

---

.. index:: from_goal_or_throw/3 .. _optional/0::from_goal_or_throw/3:

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

---

.. index:: from_goal_or_throw/2 .. _optional/0::from_goal_or_throw/2:

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)

.. seealso::

:ref:`optional(Optional) <optional/1>`, :ref:`type <type/0>`