.. _library_optionals:

``optionals``
=============

This library provides an implementation of *optional terms* with an API
modeled after the Java 8 ``Optional`` class (originally due to requests
by users working in Logtalk/Java hybrid applications). An optional term
is an opaque compound term that may or may not hold a value. Optional
terms avoid forcing the user to define a representation for the absence
of a value by providing an API with predicates that depend on the
presence or absence of a value. Optional terms also allow separating the
code that constructs optional terms from the code that processes them,
which is then free to deal if necessary and at its convenience with any
case where the values held by optional terms are not present.

API documentation
-----------------

Open the
`../../apis/library_index.html#optionals <../../apis/library_index.html#optionals>`__
link in a web browser.

Loading
-------

To load all entities in this library, load the ``loader.lgt`` file:

::

   | ?- logtalk_load(optionals(loader)).

Testing
-------

To test this library predicates, load the ``tester.lgt`` file:

::

   | ?- logtalk_load(optionals(tester)).

Usage
-----

The ``optional`` object provides constructors for optional terms. For
example:

::

   | ?- optional::of(1, Optional).
   ...

The created optional terms can then be passed as parameters to the
``optional/1`` parametric object. For example:

::

   | ?- optional::of(1, Optional), optional(Optional)::or_else(Term, 0).
   Optional = optional(1),
   Term = 1
   yes

   | ?- optional::empty(Optional), optional(Optional)::or_else(Term, 0).
   Optional = empty,
   Term = 0
   yes

The ``maybe`` object provides types and predicates for type-checking of
the term held by optional terms. It also provides some predicates for
handling lists of optional terms, including ``sequence/2`` and
``traverse/3``.

The ``optional/1`` parametric object also provides ``map_or_else/3`` for
applying a closure to the value held by the optional term if not empty,
returning a default value otherwise:

::

   | ?- optional::of(a, Optional),
        optional(Optional)::map_or_else(char_code, 0, Value).
   Value = 97
   yes

   | ?- optional::empty(Optional),
        optional(Optional)::map_or_else(char_code, 0, Value).
   Value = 0
   yes

The ``zip/3`` predicate combines two optional terms using a closure when
both are not empty:

::

   | ?- optional::of(1, O1), optional::of(3, O2),
        optional(O1)::zip([X,Y,Z]>>(Z is X+Y), O2, NewOptional).
   NewOptional = optional(4)
   yes

   | ?- optional::of(1, O1), optional::empty(O2),
        optional(O1)::zip([X,Y,Z]>>(Z is X+Y), O2, NewOptional).
   NewOptional = empty
   yes

The ``flatten/1`` predicate unwraps a nested optional term:

::

   | ?- optional::of(1, Inner), optional::of(Inner, Outer),
        optional(Outer)::flatten(NewOptional).
   NewOptional = optional(1)
   yes

   | ?- optional::empty(Inner), optional::of(Inner, Outer),
        optional(Outer)::flatten(NewOptional).
   NewOptional = empty
   yes

The ``to_expected/2`` predicate converts an optional to an expected
term:

::

   | ?- optional::of(1, Optional),
        optional(Optional)::to_expected(missing, Expected).
   Expected = expected(1)
   yes

   | ?- optional::empty(Optional),
        optional(Optional)::to_expected(missing, Expected).
   Expected = unexpected(missing)
   yes

The ``from_goal/3`` and ``from_goal/2`` constructors silently convert
goal exceptions to empty optional terms. Use ``from_goal_or_throw/3`` or
``from_goal_or_throw/2`` if exceptions should be propagated instead:

::

   | ?- optional::from_goal_or_throw(Y is 1+2, Y, Optional).
   Optional = optional(3)
   yes

   | ?- optional::from_goal_or_throw(2 is 3, _, Optional).
   Optional = empty
   yes

   | ?- catch(
          optional::from_goal_or_throw(Y is _, Y, _),
          Error,
          true
        ).
   Error = error(instantiation_error, ...)
   yes

Examples:

::

   | ?- optional::of(1, O1), optional::of(2, O2),
        maybe::sequence([O1, O2], Optional).
   Optional = optional([1,2])
   yes

   | ?- maybe::traverse({optional}/[X,O]>>optional::of(X, O), [1,2], Optional).
   Optional = optional([1,2])
   yes

   | ?- maybe::traverse({optional}/[X,O]>>(
          integer(X) -> optional::of(X, O)
        ; optional::empty(O)
        ), [1,a,2], Optional).
   Optional = empty
   yes

   | ?- optional::of(1, O1), optional::empty(O2),
        maybe::sequence([O1, O2], Optional).
   Optional = empty
   yes

See also
--------

The ``expecteds`` and ``validations`` libraries.
