category

# `mutator_common`

Mutator common predicate utilities.

Availability:
`logtalk_load(mutation_testing(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-03-20
Compilation flags:
`static`
Implements:
`public` mutator_protocol
Uses:
logtalk
Remarks:
(none)
Inherited public predicates:
coverage_clause_mutator/0 mutation/2 reset/0

## Public predicates

(no local declarations; see entity ancestors if any)

## Protected predicates

### `print_mutation/3`

Prints a term and its mutation when `Flag` is true. Succeeds otherwise.

Compilation flags:
`static`
Template:
`print_mutation(Flag,Original,Mutation)`
Mode and number of proofs:
`print_mutation(+boolean,@callable,@callable)` - `one`

### `target_predicate/3`

True iff `Term` is a candidate for mutation.

Compilation flags:
`static`
Template:
`target_predicate(Term,Entity,Predicate)`
Mode and number of proofs:
`target_predicate(@callable,@entity_identifier,@predicate_indicator)` - `one`

### `target_predicate_clause_index/4`

True iff `Term` is a candidate for mutation while also returning its current 1-based contiguous clause index for the matching predicate or non-terminal.

Compilation flags:
`static`
Template:
`target_predicate_clause_index(Term,Entity,Predicate,ClauseIndex)`
Mode and number of proofs:
`target_predicate_clause_index(@callable,@entity_identifier,@predicate_indicator,-integer)` - `zero_or_one`

### `target_scope_directive/3`

True iff `Term` is a matching predicate or non-terminal scope directive candidate for mutation.

Compilation flags:
`static`
Template:
`target_scope_directive(Term,Entity,Predicate)`
Mode and number of proofs:
`target_scope_directive(@callable,@entity_identifier,@predicate_indicator)` - `one`

### `target_scope_directive_index/4`

True iff `Term` is a matching predicate or non-terminal scope directive candidate for mutation while also returning its 1-based index among matching scope directives for the selected predicate or non-terminal.

Compilation flags:
`static`
Template:
`target_scope_directive_index(Term,Entity,Predicate,DirectiveIndex)`
Mode and number of proofs:
`target_scope_directive_index(@callable,@entity_identifier,@predicate_indicator,-integer)` - `zero_or_one`

### `target_predicate_directive/3`

True iff `Term` is a matching predicate or non-terminal directive candidate for mutation.

Compilation flags:
`static`
Template:
`target_predicate_directive(Term,Entity,Predicate)`
Mode and number of proofs:
`target_predicate_directive(@callable,@entity_identifier,@predicate_indicator)` - `one`

### `target_predicate_directive_index/4`

True iff `Term` is a matching predicate or non-terminal directive candidate for mutation while also returning its 1-based index among matching directives for the selected predicate or non-terminal.

Compilation flags:
`static`
Template:
`target_predicate_directive_index(Term,Entity,Predicate,DirectiveIndex)`
Mode and number of proofs:
`target_predicate_directive_index(@callable,@entity_identifier,@predicate_indicator,-integer)` - `zero_or_one`

### `target_uses_directive/3`

True iff `Term` is a matching `uses/2` directive candidate for mutation.

Compilation flags:
`static`
Template:
`target_uses_directive(Term,Entity,Predicate)`
Mode and number of proofs:
`target_uses_directive(@callable,@entity_identifier,@predicate_indicator)` - `one`

### `target_uses_directive_index/4`

True iff `Term` is a matching `uses/2` directive candidate for mutation while also returning its 1-based index among matching directives for the selected predicate or non-terminal.

Compilation flags:
`static`
Template:
`target_uses_directive_index(Term,Entity,Predicate,DirectiveIndex)`
Mode and number of proofs:
`target_uses_directive_index(@callable,@entity_identifier,@predicate_indicator,-integer)` - `zero_or_one`

### `next_occurrence/1`

Next mutation occurrence.

Compilation flags:
`static`
Template:
`next_occurrence(Occurrence)`
Mode and number of proofs:
`next_occurrence(-integer)` - `one`

## Private predicates

### `current_predicate_clause_index_/2`

Table of current clause indexes per predicate.

Compilation flags:
`dynamic`
Template:
`current_predicate_clause_index_(Predicate,ClauseIndex)`
Mode and number of proofs:
`current_predicate_clause_index_(?predicate_indicator,?integer)` - `zero_or_one`

### `update_target_predicate_clause_index_/2`

Updates and returns the next clause index for the given predicate.

Compilation flags:
`static`
Template:
`update_target_predicate_clause_index_(Predicate,ClauseIndex)`
Mode and number of proofs:
`update_target_predicate_clause_index_(@predicate_indicator,-integer)` - `one`

### `current_scope_directive_index_/2`

Table of current scope directive indexes per predicate.

Compilation flags:
`dynamic`
Template:
`current_scope_directive_index_(Predicate,DirectiveIndex)`
Mode and number of proofs:
`current_scope_directive_index_(?predicate_indicator,?integer)` - `zero_or_one`

### `update_target_scope_directive_index_/2`

Updates and returns the next scope directive index for the given predicate.

Compilation flags:
`static`
Template:
`update_target_scope_directive_index_(Predicate,DirectiveIndex)`
Mode and number of proofs:
`update_target_scope_directive_index_(@predicate_indicator,-integer)` - `one`

### `current_predicate_directive_index_/2`

Table of current predicate directive indexes per predicate.

Compilation flags:
`dynamic`
Template:
`current_predicate_directive_index_(Predicate,DirectiveIndex)`
Mode and number of proofs:
`current_predicate_directive_index_(?predicate_indicator,?integer)` - `zero_or_one`

### `update_target_predicate_directive_index_/2`

Updates and returns the next predicate directive index for the given predicate.

Compilation flags:
`static`
Template:
`update_target_predicate_directive_index_(Predicate,DirectiveIndex)`
Mode and number of proofs:
`update_target_predicate_directive_index_(@predicate_indicator,-integer)` - `one`

### `current_uses_directive_index_/2`

Table of current uses directive indexes per predicate.

Compilation flags:
`dynamic`
Template:
`current_uses_directive_index_(Predicate,DirectiveIndex)`
Mode and number of proofs:
`current_uses_directive_index_(?predicate_indicator,?integer)` - `zero_or_one`

### `update_target_uses_directive_index_/2`

Updates and returns the next uses directive index for the given predicate.

Compilation flags:
`static`
Template:
`update_target_uses_directive_index_(Predicate,DirectiveIndex)`
Mode and number of proofs:
`update_target_uses_directive_index_(@predicate_indicator,-integer)` - `one`

### `seen_/1`

Table of last seen mutation occurrence.

Compilation flags:
`dynamic`
Template:
`seen_(Occurrence)`
Mode and number of proofs:
`seen_(?integer)` - `zero_or_one`

## Operators

(none)