.. index:: single: validation
.. _validation/0:

.. rst-class:: right

**object**

``validation``
==============

Constructors for validation terms. A validation term is either ``valid(Value)`` or ``invalid(Errors)`` where ``Errors`` is a list of errors. Validation terms allow applicative-style error accumulation.

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

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-02-22

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Provides:**
|    :ref:`type::type/1 <type/0::type/1>`
|    :ref:`type::check/2 <type/0::check/2>`
| **Uses:**
|    :ref:`list <list/0>`
|    :ref:`type <type/0>`

| **Remarks:**

   - Type-checking support: Defines a ``validation`` type for use with the ``type`` library object.

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

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

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

.. index:: of_valid/2
.. _validation/0::of_valid/2:

``of_valid/2``
^^^^^^^^^^^^^^

Constructs a validation term holding a valid value.

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

| **Template:**
|    ``of_valid(Value,Validation)``
| **Mode and number of proofs:**
|    ``of_valid(@term,--nonvar)`` - ``one``


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

.. index:: of_invalid/2
.. _validation/0::of_invalid/2:

``of_invalid/2``
^^^^^^^^^^^^^^^^

Constructs a validation term holding a single error.

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

| **Template:**
|    ``of_invalid(Error,Validation)``
| **Mode and number of proofs:**
|    ``of_invalid(@term,--nonvar)`` - ``one``


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

.. index:: of_invalids/2
.. _validation/0::of_invalids/2:

``of_invalids/2``
^^^^^^^^^^^^^^^^^

Constructs a validation term holding a list of errors.

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

| **Template:**
|    ``of_invalids(Errors,Validation)``
| **Mode and number of proofs:**
|    ``of_invalids(@list,--nonvar)`` - ``one``


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

.. index:: from_goal/4
.. _validation/0::from_goal/4:

``from_goal/4``
^^^^^^^^^^^^^^^

Constructs a validation term holding a value bound by calling the given goal. Otherwise returns a validation term with a single error represented by the ``Error`` argument.

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

| **Template:**
|    ``from_goal(Goal,Value,Error,Validation)``
| **Meta-predicate template:**
|    ``from_goal(0,*,*,*)``
| **Mode and number of proofs:**
|    ``from_goal(+callable,--term,@term,--nonvar)`` - ``one``


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

.. index:: from_goal/3
.. _validation/0::from_goal/3:

``from_goal/3``
^^^^^^^^^^^^^^^

Constructs a validation term holding a value bound by calling the given goal. Otherwise returns a validation term with a single error being the goal error or the atom ``fail`` representing goal failure.

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

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


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

.. index:: from_goal/2
.. _validation/0::from_goal/2:

``from_goal/2``
^^^^^^^^^^^^^^^

Constructs a validation term holding a value bound by calling the given closure. Otherwise returns a validation term with a single error being the closure error or the atom ``fail`` representing closure failure.

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

| **Template:**
|    ``from_goal(Closure,Validation)``
| **Meta-predicate template:**
|    ``from_goal(1,*)``
| **Mode and number of proofs:**
|    ``from_goal(+callable,--nonvar)`` - ``one``


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

.. index:: from_generator/4
.. _validation/0::from_generator/4:

``from_generator/4``
^^^^^^^^^^^^^^^^^^^^

Constructs validation terms with the values generated by calling the given goal. On goal error or failure, returns a validation term with a single error represented by the ``Error`` argument.

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

| **Template:**
|    ``from_generator(Goal,Value,Error,Validation)``
| **Meta-predicate template:**
|    ``from_generator(0,*,*,*)``
| **Mode and number of proofs:**
|    ``from_generator(+callable,--term,@term,--nonvar)`` - ``one_or_more``


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

.. index:: from_generator/3
.. _validation/0::from_generator/3:

``from_generator/3``
^^^^^^^^^^^^^^^^^^^^

Constructs validation terms with the values generated by calling the given goal. On goal error or failure, returns a validation term with, respectively, a single error being the goal error or the atom ``fail`` representing goal failure.

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

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


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

.. index:: from_generator/2
.. _validation/0::from_generator/2:

``from_generator/2``
^^^^^^^^^^^^^^^^^^^^

Constructs validation terms with the values generated by calling the given closure. On closure error or failure, returns a validation term with, respectively, a single error being the closure error or the atom ``fail`` representing closure failure.

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

| **Template:**
|    ``from_generator(Closure,Validation)``
| **Meta-predicate template:**
|    ``from_generator(1,*)``
| **Mode and number of proofs:**
|    ``from_generator(+callable,--nonvar)`` - ``one_or_more``


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

.. index:: from_optional/3
.. _validation/0::from_optional/3:

``from_optional/3``
^^^^^^^^^^^^^^^^^^^

Converts an optional term to a validation term. Returns a valid term holding the value if the optional term is not empty. Returns an invalid term with the given error otherwise.

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

| **Template:**
|    ``from_optional(Optional,Error,Validation)``
| **Mode and number of proofs:**
|    ``from_optional(+nonvar,@term,--nonvar)`` - ``one``


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

.. index:: from_expected/2
.. _validation/0::from_expected/2:

``from_expected/2``
^^^^^^^^^^^^^^^^^^^

Converts an expected term to a validation term. Returns a valid term holding the value if the expected term holds a value. Returns an invalid term with the expected term error otherwise.

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

| **Template:**
|    ``from_expected(Expected,Validation)``
| **Mode and number of proofs:**
|    ``from_expected(+nonvar,--nonvar)`` - ``one``


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

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

(no local declarations; see entity ancestors if any)

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

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

.. seealso::

   :ref:`validation(Validation) <validation/1>`, :ref:`validated <validated/0>`, :ref:`type <type/0>`, :ref:`arbitrary <arbitrary/0>`