.. index:: single: options_protocol
.. _options_protocol/0:

.. rst-class:: right

**protocol**

``options_protocol``
====================

Options protocol.

| **Availability:** 
|    ``logtalk_load(options(loader))``

| **Author:** Paulo Moura
| **Version:** 1:2:0
| **Date:** 2022-01-03

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

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

Public predicates
-----------------

.. index:: check_option/1
.. _options_protocol/0::check_option/1:

``check_option/1``
^^^^^^^^^^^^^^^^^^

Succeeds if the option is valid. Throws an error otherwise.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_option(Option)``
| **Mode and number of proofs:**
|    ``check_option(@term)`` - ``one_or_error``

| **Exceptions:**
|    ``Option`` is a variable:
|        ``instantiation_error``
|    ``Option`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    ``Option`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``


------------

.. index:: check_options/1
.. _options_protocol/0::check_options/1:

``check_options/1``
^^^^^^^^^^^^^^^^^^^

Succeeds if all the options in a list are valid. Throws an error otherwise.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``check_options(Options)``
| **Mode and number of proofs:**
|    ``check_options(@term)`` - ``one_or_error``

| **Exceptions:**
|    ``Options`` is a variable:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is a variable:
|        ``instantiation_error``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``


------------

.. index:: valid_option/1
.. _options_protocol/0::valid_option/1:

``valid_option/1``
^^^^^^^^^^^^^^^^^^

Succeeds if the option is valid.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_option(Option)``
| **Mode and number of proofs:**
|    ``valid_option(@term)`` - ``zero_or_one``


------------

.. index:: valid_options/1
.. _options_protocol/0::valid_options/1:

``valid_options/1``
^^^^^^^^^^^^^^^^^^^

Succeeds if all the options in a list are valid.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_options(Options)``
| **Mode and number of proofs:**
|    ``valid_options(@term)`` - ``one``


------------

.. index:: default_option/1
.. _options_protocol/0::default_option/1:

``default_option/1``
^^^^^^^^^^^^^^^^^^^^

Enumerates, by backtracking, the default options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``default_option(Option)``
| **Mode and number of proofs:**
|    ``default_option(?compound)`` - ``zero_or_more``


------------

.. index:: default_options/1
.. _options_protocol/0::default_options/1:

``default_options/1``
^^^^^^^^^^^^^^^^^^^^^

Returns a list of the default options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``default_options(Options)``
| **Mode and number of proofs:**
|    ``default_options(-list(compound))`` - ``one``


------------

.. index:: option/2
.. _options_protocol/0::option/2:

``option/2``
^^^^^^^^^^^^

True iff ``Option`` unifies with the first occurrence of the same option in the ``Options`` list.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``option(Option,Options)``
| **Mode and number of proofs:**
|    ``option(+compound,+list(compound))`` - ``zero_or_one``


------------

.. index:: option/3
.. _options_protocol/0::option/3:

``option/3``
^^^^^^^^^^^^

True iff ``Option`` unifies with the first occurrence of the same option in the ``Options`` list or, when that is not the case, if ``Option`` unifies with ``Default``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``option(Option,Options,Default)``
| **Mode and number of proofs:**
|    ``option(+compound,+list(compound),+compound)`` - ``zero_or_one``


------------

Protected predicates
--------------------

.. index:: merge_options/2
.. _options_protocol/0::merge_options/2:

``merge_options/2``
^^^^^^^^^^^^^^^^^^^

Merges the user options with the default options, returning the final list of options. Calls the ``fix_options/2`` predicate to preprocess the options after merging. Callers must ensure, if required, that the user options are valid.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``merge_options(UserOptions,Options)``
| **Mode and number of proofs:**
|    ``merge_options(+list(compound),-list(compound))`` - ``one``


------------

.. index:: fix_options/2
.. _options_protocol/0::fix_options/2:

``fix_options/2``
^^^^^^^^^^^^^^^^^

Fixes a list of options, returning the list of options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``fix_options(Options,FixedOptions)``
| **Mode and number of proofs:**
|    ``fix_options(+list(compound),-list(compound))`` - ``one``


------------

.. index:: fix_option/2
.. _options_protocol/0::fix_option/2:

``fix_option/2``
^^^^^^^^^^^^^^^^

Fixes an option.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``fix_option(Option,FixedOption)``
| **Mode and number of proofs:**
|    ``fix_option(+compound,-compound)`` - ``zero_or_one``


------------

Private predicates
------------------

(none)

Operators
---------

(none)

.. seealso::

   :ref:`options <options/0>`