.. index:: 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:12:0
| **Date:** 2023-05-29

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Uses:**
|    :ref:`list <list/0>`
|    :ref:`logtalk <logtalk/0>`
|    :ref:`os <os/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.
   - 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:**
|    (none)

.. 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:: file/1
.. _dead_code_scanner/0::file/1:

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

Scans all entities in a loaded source file for dead code. 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/1
.. _dead_code_scanner/0::directory/1:

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

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

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``directory(Directory)``
| **Mode and number of proofs:**
|    ``directory(+atom)`` - ``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.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``rdirectory(Directory)``
| **Mode and number of proofs:**
|    ``rdirectory(+atom)`` - ``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.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``library(Library)``
| **Mode and number of proofs:**
|    ``library(+atom)`` - ``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.

| **Compilation flags:**
|    ``static``

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


------------

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

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

Scans all entities for dead code.

| **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:: 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``


------------

Protected predicates
--------------------

(no local declarations; see entity ancestors if any)

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

