.. index:: arbitrary
.. _arbitrary/0:

.. rst-class:: right

**category**

``arbitrary``
=============

Adds predicates for generating and shrinking random values for selected types to the library ``type`` object. User extensible.

| **Author:** Paulo Moura
| **Version:** 2:13:1
| **Date:** 2020-03-02

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


| **Complements:**
|    :ref:`type <type/0>`
| **Uses:**
|    :ref:`integer <integer/0>`
|    :ref:`list <list/0>`
|    :ref:`random <random/0>`
|    :ref:`type <type/0>`

| **Remarks:**


   - *Logtalk specific types:* ``entity``, ``object``, ``protocol``, ``category``, ``entity_identifier``, ``object_identifier``, ``protocol_identifier``, ``category_identifier``, ``event``, ``predicate``

   - *Prolog module related types (when the backend compiler supports modules):* ``module``, ``module_identifier``, ``qualified_callable``

   - *Prolog base types:* ``term``, ``var``, ``nonvar``, ``atomic``, ``atom``, ``number``, ``integer``, ``float``, ``compound``, ``callable``, ``ground``

   - *Atom derived types:* ``atom(CharSet)``, ``non_empty_atom``, ``non_empty_atom(CharSet)``, ``boolean``, ``character``, ``character(CharSet)``, ``char``, ``char(CharSet)``, ``operator_specifier``

   - *Number derived types:* ``positive_number``, ``negative_number``, ``non_positive_number``, ``non_negative_number``

   - *Float derived types:* ``positive_float``, ``negative_float``, ``non_positive_float``, ``non_negative_float``, ``probability``

   - *Integer derived types:* ``positive_integer``, ``negative_integer``, ``non_positive_integer``, ``non_negative_integer``, ``byte``, ``character_code``, ``character_code(CharSet)``, ``code``, ``code(CharSet)``, ``operator_priority``

   - *List types (compound derived types):* ``list``, ``non_empty_list``, ``partial_list``, ``list_or_partial_list``, ``list(Type)``, ``list(Type,Length)``, ``list(Type,Min,Max)``, ``list(Type,Length,Min,Max)``, ``non_empty_list(Type)``, ``codes``, ``chars``

   - *Difference list types (compound derived types):* ``difference_list``, ``difference_list(Type)``

   - *Other compound derived types:* ``predicate_indicator``, ``non_terminal_indicator``, ``predicate_or_non_terminal_indicator``, ``clause``, ``clause_or_partial_clause``, ``grammar_rule``, ``pair``, ``pair(KeyType,ValueType)``

   - *Other types:* ``between(Type,Lower,Upper)``, ``property(Type,LambdaExpression)``, ``one_of(Type,Set)``, ``var_or(Type)``, ``ground(Type)``, ``types(Types)``

   - *Registering new types:* Add clauses for the ``arbitrary/1-2`` multifile predicates and optionally for the ``shrinker/1`` and ``shrink/3`` multifile predicates. The clauses must have a bound first argument to avoid introducing spurious choice-points.

   - *Character sets:* ``ascii_identifier``, ``ascii_printable``, ``ascii_full``, ``byte``, ``unicode_bmp``, ``unicode_full``

   - *Default character sets:* The default character set when using a parameterizable type that takes a character set parameter depends on the type.

   - *Default character sets:* Entity, predicate, and non-terminal identifier types plus compound and callable types default to an ``ascii_identifier`` functor. Character and character code types default to ``ascii_full``. Other types default to ``ascii_printable``.

   - *Caveats:* The type argument (and any type parameterization) to the predicates is not type-checked (or checked for consistency) for performance reasons.

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

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

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

.. raw:: html

   <div id="arbitrary/1"> </div>

.. index:: arbitrary/1
.. _arbitrary/0::arbitrary/1:

``arbitrary/1``
^^^^^^^^^^^^^^^

Table of defined types for which an arbitrary value can be generated. A new type can be registered by defining a clause for this predicate and adding a clause for the ``arbitrary/2`` multifile predicate.

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

| **Template:**
|    ``arbitrary(Type)``
| **Mode and number of proofs:**
|    ``arbitrary(?callable)`` - ``zero_or_more``


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

.. raw:: html

   <div id="arbitrary/2"> </div>

.. index:: arbitrary/2
.. _arbitrary/0::arbitrary/2:

``arbitrary/2``
^^^^^^^^^^^^^^^

Generates an arbitrary term of the specified type. Fails if the type is not supported. A new generator can be defined by adding a clause for this predicate and registering it via the ``arbitrary/1`` predicate.

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

| **Template:**
|    ``arbitrary(Type,Term)``
| **Mode and number of proofs:**
|    ``arbitrary(@callable,-term)`` - ``zero_or_one``


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

.. raw:: html

   <div id="shrinker/1"> </div>

.. index:: shrinker/1
.. _arbitrary/0::shrinker/1:

``shrinker/1``
^^^^^^^^^^^^^^

Table of defined types for which a shrinker is provided. A new shrinker can be registered by defining a clause for this predicate and adding a definition for the ``shrink/3`` multifile predicate.

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

| **Template:**
|    ``shrinker(Type)``
| **Mode and number of proofs:**
|    ``shrinker(?callable)`` - ``zero_or_more``


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

.. raw:: html

   <div id="shrink/3"> </div>

.. index:: shrink/3
.. _arbitrary/0::shrink/3:

``shrink/3``
^^^^^^^^^^^^

Shrinks a value to a smaller value if possible. Must generate a finite number of solutions. Fails if the type is not supported. A new shrinker can be defined by adding a clause for this predicate and registering it via the ``shrinker/1`` predicate.

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

| **Template:**
|    ``shrink(Type,Large,Small)``
| **Mode and number of proofs:**
|    ``shrink(@callable,@term,-term)`` - ``zero_or_more``


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

.. raw:: html

   <div id="edge_case/2"> </div>

.. index:: edge_case/2
.. _arbitrary/0::edge_case/2:

``edge_case/2``
^^^^^^^^^^^^^^^

Table of type edge cases. Fails if the given type have no defined edge cases. New edge cases for existing or new types can be added by defining a clause for this multifile predicate.

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

| **Template:**
|    ``edge_case(Type,Term)``
| **Mode and number of proofs:**
|    ``edge_case(?callable,?term)`` - ``zero_or_more``


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

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

(no local declarations; see entity ancestors if any)

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

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

.. seealso::

   :ref:`type <type/0>`

