.. index:: debuggerp
.. _debuggerp/0:

.. rst-class:: right

**protocol**

``debuggerp``
=============

Debugger protocol.

| **Availability:** 
|    ``logtalk_load(debugger(loader))``

| **Author:** Paulo Moura
| **Version:** 3:3:0
| **Date:** 2024-06-19

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


| **Dependencies:**
|   (none)


| **Remarks:**

   - Debugger help: Type the character ``h`` (condensed help) or the character ``?`` (extended help) at a leashed port.
   - Predicate breakpoint: Specified as a ground term ``Functor/Arity``.
   - Non-terminal breakpoint: Specified as a ground term ``Functor//Arity``.
   - Clause breakpoint: Specified as an ``Entity-Line`` term with both ``Entity`` and ``Line`` bound. ``Line`` must be the first source file line of an entity clause.
   - Conditional breakpoint: Specified as an ``Entity-Line`` term with both ``Entity`` and ``Line`` bound and a condition. ``Line`` must be the first source file line of an entity clause.
   - Hit count breakpoint: Specified as an ``Entity-Line`` term with both ``Entity`` and ``Line`` bound and an unification count expression as a condition. ``Line`` must be the first source file line of an entity clause.
   - Triggered breakpoint: Specified as an ``Entity-Line`` term with both ``Entity`` and ``Line`` bound and another breakpoint as a condition. ``Line`` must be the first source file line of an entity clause.
   - Context breakpoint: Specified as a ``(Sender, This, Self, Goal)`` tuple.
   - Log point: Specified as an ``(Entity, Line, Message)`` tuple.
   - Leash port shorthands: ``none`` - ``[]``, ``loose`` - ``[fact,rule,call]``, ``half`` - ``[fact,rule,call,redo]``, ``tight`` - ``[fact,rule,call,redo,fail,exception]``, and ``full`` - ``[fact,rule,call,exit,redo,fail,exception]``.

| **Inherited public predicates:**
|    (none)

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

Public predicates
-----------------

.. index:: reset/0
.. _debuggerp/0::reset/0:

``reset/0``
^^^^^^^^^^^

Resets all debugging settings (including breakpoints, log points, and leashed ports) and turns off debugging.

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

| **Mode and number of proofs:**
|    ``reset`` - ``one``

| **See also:**
|    :ref:`debuggerp/0::nospyall/0`


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

.. index:: debug/0
.. _debuggerp/0::debug/0:

``debug/0``
^^^^^^^^^^^

Starts debugging for all defined breakpoints.

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

| **Mode and number of proofs:**
|    ``debug`` - ``one``


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

.. index:: nodebug/0
.. _debuggerp/0::nodebug/0:

``nodebug/0``
^^^^^^^^^^^^^

Stops debugging for all defined breakpoints. Also turns off tracing. Does not remove defined breakpoints.

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

| **Mode and number of proofs:**
|    ``nodebug`` - ``one``

| **See also:**
|    :ref:`debuggerp/0::reset/0`


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

.. index:: debugging/0
.. _debuggerp/0::debugging/0:

``debugging/0``
^^^^^^^^^^^^^^^

Reports current debugging settings, including breakpoints and log points.

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

| **Mode and number of proofs:**
|    ``debugging`` - ``one``


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

.. index:: debugging/1
.. _debuggerp/0::debugging/1:

``debugging/1``
^^^^^^^^^^^^^^^

Enumerates, by backtracking, all entities compiled in debug mode.

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

| **Template:**
|    ``debugging(Entity)``
| **Mode and number of proofs:**
|    ``debugging(?entity_identifier)`` - ``zero_or_more``


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

.. index:: trace/0
.. _debuggerp/0::trace/0:

``trace/0``
^^^^^^^^^^^

Starts tracing all calls compiled in debug mode.

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

| **Mode and number of proofs:**
|    ``trace`` - ``one``


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

.. index:: notrace/0
.. _debuggerp/0::notrace/0:

``notrace/0``
^^^^^^^^^^^^^

Stops tracing of calls compiled in debug mode. Debugger will still stop at defined breakpoints.

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

| **Mode and number of proofs:**
|    ``notrace`` - ``one``


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

.. index:: leash/1
.. _debuggerp/0::leash/1:

``leash/1``
^^^^^^^^^^^

Sets the debugger leash ports using an abbreviation (``none``, ``loose``, ``half``, ``tight``, or ``full``) or a list of ports (valid ports are ``fact``, ``rule``, ``call``, ``exit``, ``redo``, ``fail``, and ``exception``).

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

| **Template:**
|    ``leash(Ports)``
| **Mode and number of proofs:**
|    ``leash(+atom)`` - ``one``
|    ``leash(+list(atom))`` - ``one``


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

.. index:: leashing/1
.. _debuggerp/0::leashing/1:

``leashing/1``
^^^^^^^^^^^^^^

Enumerates, by backtracking, all leashed ports (valid ports are ``fact``, ``rule``, ``call``, ``exit``, ``redo``, ``fail``, and ``exception``).

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

| **Template:**
|    ``leashing(Port)``
| **Mode and number of proofs:**
|    ``leashing(?atom)`` - ``zero_or_more``


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

.. index:: spy/1
.. _debuggerp/0::spy/1:

``spy/1``
^^^^^^^^^

Sets a predicate or clause breakpoint (removing any existing log point or breakpoint defined for the same location, or a list of breakpoints. Fails if a breakpoint is invalid.

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

| **Template:**
|    ``spy(Breakpoint)``
| **Mode and number of proofs:**
|    ``spy(@spy_point)`` - ``zero_or_one``
|    ``spy(@list(spy_point))`` - ``zero_or_one``


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

.. index:: spying/1
.. _debuggerp/0::spying/1:

``spying/1``
^^^^^^^^^^^^

Enumerates, by backtracking, all defined predicate and clause breakpoints.

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

| **Template:**
|    ``spying(Breakpoint)``
| **Mode and number of proofs:**
|    ``spying(?spy_point)`` - ``zero_or_more``


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

.. index:: nospy/1
.. _debuggerp/0::nospy/1:

``nospy/1``
^^^^^^^^^^^

Removes all matching predicate and clause breakpoints.

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

| **Template:**
|    ``nospy(Breakpoint)``
| **Mode and number of proofs:**
|    ``nospy(@var)`` - ``one``
|    ``nospy(@spy_point)`` - ``one``
|    ``nospy(@list(spy_point))`` - ``one``


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

.. index:: spy/3
.. _debuggerp/0::spy/3:

``spy/3``
^^^^^^^^^

Sets a conditional or triggered breakpoint (removing any existing log point or breakpoint defined for the same location). The condition can be a unification count expression, a lambda expression, or another breakpoint. Fails if the breakpoint is invalid.

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

| **Template:**
|    ``spy(Entity,Line,Condition)``
| **Mode and number of proofs:**
|    ``spy(+atom,+integer,@callable)`` - ``zero_or_one``

| **Remarks:**

    - Unification count expression conditions: ``>(Count)``, ``>=(Count)``, ``=:=(Count)``, ``=<(Count)``, ``<(Count)``, ``mod(M)``, and ``Count``.
    - Lambda expression conditions: ``[Count,N,Goal]>>Condition`` and ``[Goal]>>Condition`` where ``Count`` is the unification count, ``N`` is the invocation number, and ``Goal`` is the goal that unified with the clause head; ``Condition`` is called in the context of ``user``.
    - Triggered breakpoint conditions: ``Entity-Line``.


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

.. index:: spying/3
.. _debuggerp/0::spying/3:

``spying/3``
^^^^^^^^^^^^

Enumerates, by backtracking, all conditional and triggered breakpoints.

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

| **Template:**
|    ``spying(Entity,Line,Condition)``
| **Mode and number of proofs:**
|    ``spying(?atom,?integer,?callable)`` - ``zero_or_more``


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

.. index:: nospy/3
.. _debuggerp/0::nospy/3:

``nospy/3``
^^^^^^^^^^^

Removes all matching conditional and triggered breakpoints.

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

| **Template:**
|    ``nospy(Entity,Line,Condition)``
| **Mode and number of proofs:**
|    ``nospy(@term,@term,@term)`` - ``one``


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

.. index:: spy/4
.. _debuggerp/0::spy/4:

``spy/4``
^^^^^^^^^

Sets a context breakpoint.

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

| **Template:**
|    ``spy(Sender,This,Self,Goal)``
| **Mode and number of proofs:**
|    ``spy(@term,@term,@term,@term)`` - ``one``


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

.. index:: spying/4
.. _debuggerp/0::spying/4:

``spying/4``
^^^^^^^^^^^^

Enumerates, by backtracking, all defined context breakpoints.

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

| **Template:**
|    ``spying(Sender,This,Self,Goal)``
| **Mode and number of proofs:**
|    ``spying(?term,?term,?term,?term)`` - ``zero_or_more``


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

.. index:: nospy/4
.. _debuggerp/0::nospy/4:

``nospy/4``
^^^^^^^^^^^

Removes all matching context breakpoints.

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

| **Template:**
|    ``nospy(Sender,This,Self,Goal)``
| **Mode and number of proofs:**
|    ``nospy(@term,@term,@term,@term)`` - ``one``


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

.. index:: nospyall/0
.. _debuggerp/0::nospyall/0:

``nospyall/0``
^^^^^^^^^^^^^^

Removes all breakpoints and log points.

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

| **Mode and number of proofs:**
|    ``nospyall`` - ``one``

| **See also:**
|    :ref:`debuggerp/0::reset/0`


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

.. index:: log/3
.. _debuggerp/0::log/3:

``log/3``
^^^^^^^^^

Sets a log point (removing any existing breakpoint defined for the same location). Fails if the log point is invalid.

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

| **Template:**
|    ``log(Entity,Line,Message)``
| **Mode and number of proofs:**
|    ``log(@object_identifier,+integer,+atom)`` - ``zero_or_one``
|    ``log(@category_identifier,+integer,+atom)`` - ``zero_or_one``
|    ``log(?object_identifier,?integer,?atom)`` - ``zero_or_more``
|    ``log(?category_identifier,?integer,?atom)`` - ``zero_or_more``
|    ``log(@var_or(object_identifier),@var_or(integer),@var_or(atom))`` - ``one``
|    ``log(@var_or(category_identifier),@var_or(integer),@var_or(atom))`` - ``one``


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

.. index:: logging/3
.. _debuggerp/0::logging/3:

``logging/3``
^^^^^^^^^^^^^

Enumerates, by backtracking, all defined log points.

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

| **Template:**
|    ``logging(Entity,Line,Message)``

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

.. index:: nolog/3
.. _debuggerp/0::nolog/3:

``nolog/3``
^^^^^^^^^^^

Removes all matching log points.

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

| **Template:**
|    ``nolog(Entity,Line,Message)``

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

.. index:: nologall/0
.. _debuggerp/0::nologall/0:

``nologall/0``
^^^^^^^^^^^^^^

Removes all log points.

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

| **Mode and number of proofs:**
|    ``nologall`` - ``one``

| **See also:**
|    :ref:`debuggerp/0::reset/0`


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

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

(none)

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

(none)

Operators
---------

(none)

.. seealso::

   :ref:`debugger <debugger/0>`

