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:18:1
Date: 2021-04-02
Compilation flags:
`static`
Complements:
type
Uses:
fast_random
integer
list
type
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)`, `atom(CharSet,Length)`, `non_quoted_atom`, `non_empty_atom`, `non_empty_atom(CharSet)`, `boolean`, `character`, `character(CharSet)`, `char`, `char(CharSet)`, `operator_specifier`, `hex_char`

> - 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`, `hex_code`

> - 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)

- Public predicates

  - `arbitrary/1`

  - `arbitrary/2`

  - `shrinker/1`

  - `shrink/3`

  - `edge_case/2`

  - `get_seed/1`

  - `set_seed/1`

- Protected predicates

- Private predicates

- Operators

## Public predicates

### `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`

### `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`

### `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`

### `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`

### `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`

### `get_seed/1`

Gets the current random generator seed. Seed should be regarded as an opaque ground term.

Compilation flags:
`static`
Template:
`get_seed(Seed)`
Mode and number of proofs:
`get_seed(-ground)` - `one`

### `set_seed/1`

Sets the random generator seed to a given value returned by calling the `get_seed/1` predicate.

Compilation flags:
`static`
Template:
`set_seed(Seed)`
Mode and number of proofs:
`set_seed(+ground)` - `one`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

(no local declarations; see entity ancestors if any)

## Operators

(none)

See also

type