category

# `arbitrary`

Adds predicates for generating random values for selected types to the library “type” object.

Author: Paulo Moura
Version: 2.3
Date: 2019/3/27
Compilation flags:
`static`

## Public interface

### `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 given type is not supported. A new generator can be added by defining a clause for this predicate and registering it by adding a clause for the arbitrary/1 multifile 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. Fails if the given type is not supported or if shrinking the value is not possible. Support for a new type can be added by defining a clause for this predicate. Must always generate a finite number of solutions.

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`

## Protected interface

(see related entities)

## Private predicates

(see related entities)

## Operators

(none)

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

- Base types from Prolog: {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 (same as character), char(CharSet) (same as character(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 (same as character_code), code(CharSet) (same as character_code(CharSet)), operator_priority}

- List types (compound derived types): {list, non_empty_list, partial_list, list_or_partial_list, list(Type), list(Type, Min, Max), non_empty_list(Type), difference_list, difference_list(Type), codes (same as list(character_code)), chars (same as list(character))}

- 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: New types can be registered by defining clauses for the arbitrary/1-2 multifile predicates and optionally for the shrinker/1 and shrink/3 multifile predicates. Clauses for the predicates must have a bound first argument to avoid introducing spurious choice-points.

- Character sets: When generating character or character codes, or terms that contain them (e.g. atom), it is possible to choose a character set (ascii_identifier, ascii_printable, ascii_full, byte, unicode_bmp, or unicode_full) using the parameterizable types. Default 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 to the predicates is not type-checked for performance reasons.

See also

type