.. index:: single: mutator_common .. _mutator_common/0:

.. rst-class:: right

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 :ref:`mutator_protocol <mutator_protocol/0>` | Uses: | :ref:`logtalk <logtalk/0>`

| Remarks: | (none)

| Inherited public predicates: |  :ref:`mutator_protocol/0::coverage_clause_mutator/0`  :ref:`mutator_protocol/0::mutation/2`  :ref:`mutator_protocol/0::reset/0`  

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

Public predicates

(no local declarations; see entity ancestors if any)

Protected predicates

.. index:: print_mutation/3 .. _mutator_common/0::print_mutation/3:

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

---

.. index:: target_predicate/3 .. _mutator_common/0::target_predicate/3:

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

---

.. index:: target_predicate_clause_index/4 .. _mutator_common/0::target_predicate_clause_index/4:

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

---

.. index:: target_scope_directive/3 .. _mutator_common/0::target_scope_directive/3:

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

---

.. index:: target_scope_directive_index/4 .. _mutator_common/0::target_scope_directive_index/4:

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

---

.. index:: target_predicate_directive/3 .. _mutator_common/0::target_predicate_directive/3:

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

---

.. index:: target_predicate_directive_index/4 .. _mutator_common/0::target_predicate_directive_index/4:

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

---

.. index:: target_uses_directive/3 .. _mutator_common/0::target_uses_directive/3:

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

---

.. index:: target_uses_directive_index/4 .. _mutator_common/0::target_uses_directive_index/4:

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

---

.. index:: next_occurrence/1 .. _mutator_common/0::next_occurrence/1:

next_occurrence/1 ^^^^^^^^^^^^^^^^^^^^^

Next mutation occurrence.

| Compilation flags: | static

| Template: | next_occurrence(Occurrence) | Mode and number of proofs: | next_occurrence(-integer) - one

---

Private predicates

.. index:: current_predicate_clause_index_/2 .. _mutator_common/0::current_predicate_clause_index_/2:

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

---

.. index:: update_target_predicate_clause_index_/2 .. _mutator_common/0::update_target_predicate_clause_index_/2:

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

---

.. index:: current_scope_directive_index_/2 .. _mutator_common/0::current_scope_directive_index_/2:

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

---

.. index:: update_target_scope_directive_index_/2 .. _mutator_common/0::update_target_scope_directive_index_/2:

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

---

.. index:: current_predicate_directive_index_/2 .. _mutator_common/0::current_predicate_directive_index_/2:

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

---

.. index:: update_target_predicate_directive_index_/2 .. _mutator_common/0::update_target_predicate_directive_index_/2:

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

---

.. index:: current_uses_directive_index_/2 .. _mutator_common/0::current_uses_directive_index_/2:

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

---

.. index:: update_target_uses_directive_index_/2 .. _mutator_common/0::update_target_uses_directive_index_/2:

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

---

.. index:: seen_/1 .. _mutator_common/0::seen_/1:

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)