.. index:: single: dead_code_scanner .. _dead_code_scanner/0:

.. rst-class:: right

object

dead_code_scanner

A tool for detecting likely dead code in compiled Logtalk entities and Prolog modules compiled as objects.

| Availability: | logtalk_load(dead_code_scanner(loader))

| Author: Barry Evans and Paulo Moura | Version: 0:18:0 | Date: 2026-04-05

| Compilation flags: | static, context_switching_calls

| Imports: | public :ref:`tool_diagnostics_common <tool_diagnostics_common/0>` | public :ref:`options <options/0>` | Uses: | :ref:`list <list/0>` | :ref:`logtalk <logtalk/0>` | :ref:`os <os/0>` | :ref:`term_io <term_io/0>` | :ref:`type <type/0>` | :ref:`user <user/0>`

| Remarks:

• Dead code: A predicate or non-terminal that is not called (directly or indirectly) by any scoped predicate or non-terminal. These predicates and non-terminals are not used, cannot be called without breaking encapsulation, and are thus considered dead code.
• Diagnostics targets: The diagnostics predicates accept the targets all, entity(Entity), file(File), directory(Directory), rdirectory(Directory), library(Library), and rlibrary(Library). The entity(Entity) target requires a loaded object or category. The file(File) target accepts a loaded source file specified by name, basename, full path, or library notation. Directory and library targets restrict diagnostics to loaded files found in the given directory, recursively in its sub-directories, in the given library, or recursively in its sub-libraries.
• Known issues: Use of local meta-calls with goal arguments only know at runtime can result in false positives. Calls from non-standard meta-predicates may be missed if the meta-calls are not optimized.
• Requirements: Source files must be compiled with the source_data flag turned on. To avoid false positives do to meta-calls, compilation of source files with the optimized flag turned on is also advised.

| Inherited public predicates: |  :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`tool_diagnostics_protocol/0::diagnostic/2`  :ref:`tool_diagnostics_protocol/0::diagnostic/3`  :ref:`tool_diagnostics_protocol/0::diagnostic_rule/5`  :ref:`tool_diagnostics_protocol/0::diagnostic_rules/1`  :ref:`tool_diagnostics_protocol/0::diagnostic_target/1`  :ref:`tool_diagnostics_protocol/0::diagnostics/2`  :ref:`tool_diagnostics_protocol/0::diagnostics/3`  :ref:`tool_diagnostics_protocol/0::diagnostics_preflight/2`  :ref:`tool_diagnostics_protocol/0::diagnostics_preflight/3`  :ref:`tool_diagnostics_protocol/0::diagnostics_summary/2`  :ref:`tool_diagnostics_protocol/0::diagnostics_summary/3`  :ref:`tool_diagnostics_protocol/0::diagnostics_tool/5`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

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

Public predicates

.. index:: entity/1 .. _dead_code_scanner/0::entity/1:

entity/1 ^^^^^^^^^^^^

Scans a loaded entity for dead code. Fails if the entity does not exist.

| Compilation flags: | static

| Template: | entity(Entity) | Mode and number of proofs: | entity(+entity_identifier) - zero_or_one

---

.. index:: entity/2 .. _dead_code_scanner/0::entity/2:

entity/2 ^^^^^^^^^^^^

Scans a loaded entity for dead code using the given options. Fails if the entity does not exist.

| Compilation flags: | static

| Template: | entity(Entity,Options) | Mode and number of proofs: | entity(+entity_identifier,+list(compound)) - zero_or_one

---

.. index:: file/2 .. _dead_code_scanner/0::file/2:

file/2 ^^^^^^^^^^

Scans all entities in a loaded source file for dead code using the given options. The file can be given by name, basename, full path, or using library notation. Fails if the file is not loaded.

| Compilation flags: | static

| Template: | file(File,Options) | Mode and number of proofs: | file(+atom,+list(compound)) - zero_or_one

---

.. index:: file/1 .. _dead_code_scanner/0::file/1:

file/1 ^^^^^^^^^^

Scans all entities in a loaded source file for dead code using default options. The file can be given by name, basename, full path, or using library notation. Fails if the file is not loaded.

| Compilation flags: | static

| Template: | file(File) | Mode and number of proofs: | file(+atom) - zero_or_one

---

.. index:: directory/2 .. _dead_code_scanner/0::directory/2:

directory/2 ^^^^^^^^^^^^^^^

Scans all entities in all loaded files from a given directory for dead code using the given options.

| Compilation flags: | static

| Template: | directory(Directory,Options) | Mode and number of proofs: | directory(+atom,+list(compound)) - one

---

.. index:: directory/1 .. _dead_code_scanner/0::directory/1:

directory/1 ^^^^^^^^^^^^^^^

Scans all entities in all loaded files from a given directory for dead code using default options.

| Compilation flags: | static

| Template: | directory(Directory) | Mode and number of proofs: | directory(+atom) - one

---

.. index:: rdirectory/2 .. _dead_code_scanner/0::rdirectory/2:

rdirectory/2 ^^^^^^^^^^^^^^^^

Scans all entities in all loaded files from a given directory and its sub-directories for dead code using the given options.

| Compilation flags: | static

| Template: | rdirectory(Directory,Options) | Mode and number of proofs: | rdirectory(+atom,+list(compound)) - one

---

.. index:: rdirectory/1 .. _dead_code_scanner/0::rdirectory/1:

rdirectory/1 ^^^^^^^^^^^^^^^^

Scans all entities in all loaded files from a given directory and its sub-directories for dead code using default options.

| Compilation flags: | static

| Template: | rdirectory(Directory) | Mode and number of proofs: | rdirectory(+atom) - one

---

.. index:: library/2 .. _dead_code_scanner/0::library/2:

library/2 ^^^^^^^^^^^^^

Scans all entities in all loaded files from a given library for dead code using the given options.

| Compilation flags: | static

| Template: | library(Library,Options) | Mode and number of proofs: | library(+atom,+list(compound)) - one

---

.. index:: library/1 .. _dead_code_scanner/0::library/1:

library/1 ^^^^^^^^^^^^^

Scans all entities in all loaded files from a given library for dead code using default options.

| Compilation flags: | static

| Template: | library(Library) | Mode and number of proofs: | library(+atom) - one

---

.. index:: rlibrary/2 .. _dead_code_scanner/0::rlibrary/2:

rlibrary/2 ^^^^^^^^^^^^^^

Scans all entities in all loaded files in a loaded library and its sub-libraries for dead code using the given options.

| Compilation flags: | static

| Template: | rlibrary(Library,Options) | Mode and number of proofs: | rlibrary(+atom,+list(compound)) - one

---

.. index:: rlibrary/1 .. _dead_code_scanner/0::rlibrary/1:

rlibrary/1 ^^^^^^^^^^^^^^

Scans all entities in all loaded files in a loaded library and its sub-libraries for dead code using default options.

| Compilation flags: | static

| Template: | rlibrary(Library) | Mode and number of proofs: | rlibrary(+atom) - one

---

.. index:: all/1 .. _dead_code_scanner/0::all/1:

all/1 ^^^^^^^^^

Scans all entities for dead code using the given options.

| Compilation flags: | static

| Template: | all(Options) | Mode and number of proofs: | all(+list(compound)) - one

---

.. index:: all/0 .. _dead_code_scanner/0::all/0:

all/0 ^^^^^^^^^

Scans all entities for dead code using default options.

| Compilation flags: | static

| Mode and number of proofs: | all - one

---

.. index:: predicates/2 .. _dead_code_scanner/0::predicates/2:

predicates/2 ^^^^^^^^^^^^^^^^

Returns an ordered set of local predicates (and non-terminals) that are not used, directly or indirectly, by scoped predicates for a loaded entity.

| Compilation flags: | static

| Template: | predicates(Entity,Predicates) | Mode and number of proofs: | predicates(+entity_identifier,-list(predicate_indicator)) - one

---

.. index:: predicates/3 .. _dead_code_scanner/0::predicates/3:

predicates/3 ^^^^^^^^^^^^^^^^

Returns an ordered set of local predicates (and non-terminals) that are not used, directly or indirectly, by scoped predicates for a loaded entity using the given options.

| Compilation flags: | static

| Template: | predicates(Entity,Predicates,Options) | Mode and number of proofs: | predicates(+entity_identifier,-list(predicate_indicator),+list(compound)) - one

---

.. index:: predicate/2 .. _dead_code_scanner/0::predicate/2:

predicate/2 ^^^^^^^^^^^^^^^

Enumerates, by backtracking, local predicates (and non-terminals) that are not used, directly or indirectly, by scoped predicates for a loaded entity.

| Compilation flags: | static

| Template: | predicate(Entity,Predicate) | Mode and number of proofs: | predicate(+entity_identifier,?predicate_indicator) - zero_or_more

---

.. index:: predicate/3 .. _dead_code_scanner/0::predicate/3:

predicate/3 ^^^^^^^^^^^^^^^

Enumerates, by backtracking, local predicates (and non-terminals) that are not used, directly or indirectly, by scoped predicates for a loaded entity using the given options.

| Compilation flags: | static

| Template: | predicate(Entity,Predicate,Options) | Mode and number of proofs: | predicate(+entity_identifier,?predicate_indicator,+list(compound)) - 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)