1/*  Part of SWI-Prolog
    2
    3    Author:        Jan Wielemaker
    4    E-mail:        jan@swi-prolog.org
    5    WWW:           https://www.swi-prolog.org
    6    Copyright (c)  2021-2025, SWI-Prolog Solutions b.v.
    7    All rights reserved.
    8
    9    Redistribution and use in source and binary forms, with or without
   10    modification, are permitted provided that the following conditions
   11    are met:
   12
   13    1. Redistributions of source code must retain the above copyright
   14       notice, this list of conditions and the following disclaimer.
   15
   16    2. Redistributions in binary form must reproduce the above copyright
   17       notice, this list of conditions and the following disclaimer in
   18       the documentation and/or other materials provided with the
   19       distribution.
   20
   21    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   22    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   23    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   24    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   25    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   26    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   27    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   28    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   29    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   30    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   31    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   32    POSSIBILITY OF SUCH DAMAGE.
   33*/
   34
   35:- module(prolog_debug_tools,
   36          [ (spy)/1,                % :Spec (some users tend to define these as
   37            (nospy)/1,              % :Spec  an operator)
   38            nospyall/0,
   39            debugging/0,
   40            trap/1,                 % +Exception
   41            notrap/1                % +Exception
   42          ]).   43:- use_module(library(broadcast), [broadcast/1]).   44:- autoload(library(edinburgh), [debug/0]).   45:- autoload(library(gensym), [gensym/2]).   46
   47:- multifile
   48    trap_alias/2.   49
   50:- set_prolog_flag(generate_debug_info, false).   51
   52/** <module> User level debugging tools
   53
   54This  library  provides  tools   to    control   the  Prolog  debuggers.
   55Traditionally this code was  built-in.  Because   these  tools  are only
   56required in (interactive) debugging sessions they   have been moved into
   57the library.
   58*/
   59
   60%!  prolog:debug_control_hook(+Action)
   61%
   62%   Allow user-hooks in the Prolog debugger interaction.  See the calls
   63%   below for the provided hooks.  We use a single predicate with action
   64%   argument to avoid an uncontrolled poliferation of hooks.
   65
   66:- multifile
   67    prolog:debug_control_hook/1.    % +Action
   68
   69:- meta_predicate
   70    spy(:),
   71    nospy(:).   72
   73%!  spy(:Spec) is det.
   74%!  nospy(:Spec) is det.
   75%!  nospyall is det.
   76%
   77%   Set/clear spy-points. A successfully  set   or  cleared spy-point is
   78%   reported using print_message/2, level `informational`,   with one of
   79%   the following terms, where Spec is of the form M:Head.
   80%
   81%       - spy(Spec)
   82%       - nospy(Spec)
   83%
   84%   @see    spy/1 and nospy/1 call the hook prolog:debug_control_hook/1
   85%           to allow for alternative specifications of the thing to
   86%           debug.
   87
   88spy(Spec) :-
   89    '$notrace'(spy_(Spec)).
   90
   91spy_(_:X) :-
   92    var(X),
   93    throw(error(instantiation_error, _)).
   94spy_(_:[]) :- !.
   95spy_(M:[H|T]) :-
   96    !,
   97    spy(M:H),
   98    spy(M:T).
   99spy_(Spec) :-
  100    prolog:debug_control_hook(spy(Spec)),
  101    !.
  102spy_(Spec) :-
  103    '$find_predicate'(Spec, Preds),
  104    '$member'(PI, Preds),
  105        pi_to_head(PI, Head),
  106        '$define_predicate'(Head),
  107        set_spy_point(Head),
  108    fail.
  109spy_(_).
  110
  111set_spy_point(Head) :-
  112    '$get_predicate_attribute'(Head, spy, 1),
  113    !,
  114    print_message(informational, already_spying(Head)).
  115set_spy_point(Head) :-
  116    '$spy'(Head).
  117
  118nospy(Spec) :-
  119    notrace(nospy_(Spec)).
  120
  121nospy_(_:X) :-
  122    var(X),
  123    throw(error(instantiation_error, _)).
  124nospy_(_:[]) :- !.
  125nospy_(M:[H|T]) :-
  126    !,
  127    nospy(M:H),
  128    nospy(M:T).
  129nospy_(Spec) :-
  130    prolog:debug_control_hook(nospy(Spec)),
  131    !.
  132nospy_(Spec) :-
  133    '$find_predicate'(Spec, Preds),
  134    '$member'(PI, Preds),
  135         pi_to_head(PI, Head),
  136        '$nospy'(Head),
  137    fail.
  138nospy_(_).
  139
  140nospyall :-
  141    notrace(nospyall_).
  142
  143nospyall_ :-
  144    prolog:debug_control_hook(nospyall),
  145    fail.
  146nospyall_ :-
  147    spy_point(Head),
  148        '$nospy'(Head),
  149    fail.
  150nospyall_.
  151
  152pi_to_head(M:PI, M:Head) :-
  153    !,
  154    pi_to_head(PI, Head).
  155pi_to_head(Name/Arity, Head) :-
  156    functor(Head, Name, Arity).
  157
  158%!  debugging is det.
  159%
  160%   Report current status of the debugger.
  161
  162:- '$hide'(debugging/0).  163debugging :-
  164    current_prolog_flag(debug, DebugMode),
  165    notrace(debugging_(DebugMode)).
  166
  167debugging_(DebugMode) :-
  168    prolog:debug_control_hook(debugging(DebugMode)),
  169    !.
  170debugging_(DebugMode) :-
  171    print_message(informational, debugging(DebugMode)),
  172    (   DebugMode == true
  173    ->  findall(H, spy_point(H), SpyPoints),
  174        print_message(informational, spying(SpyPoints))
  175    ;   true
  176    ),
  177    trapping,
  178    forall(debugging_hook(DebugMode), true).
  179
  180spy_point(Module:Head) :-
  181    current_predicate(_, Module:Head),
  182    '$get_predicate_attribute'(Module:Head, spy, 1),
  183    \+ predicate_property(Module:Head, imported_from(_)).
  184
  185%!  debugging_hook(+DebugMode)
  186%
  187%   Multifile hook that is   called as forall(debugging_hook(DebugMode),
  188%   true) and that may be used to   extend  the information printed from
  189%   other debugging libraries.
  190
  191:- multifile debugging_hook/1.  192
  193
  194		 /*******************************
  195		 *           EXCEPTIONS		*
  196		 *******************************/
  197
  198%!  trap(+Formal) is det.
  199%!  notrap(+Formal) is det.
  200%
  201%   Install a trap on error(Formal, Context)  exceptions that unify. The
  202%   tracer  is  started  when  a  matching  exception  is  raised.  This
  203%   predicate enables _debug mode_ using  debug/0   to  get more context
  204%   about the exception. Even with debug   mode  disabled exceptions are
  205%   still trapped and thus one may call  nodebug/0 to run in normal mode
  206%   after installing a trap. Exceptions are trapped in any thread. Debug
  207%   mode is only enabled in the calling  thread. To enable debug mode in
  208%   all threads use tdebug/0.
  209%
  210%   Calling debugging/0 lists the enabled  traps. The predicate notrap/1
  211%   removes matching (unifying) traps.
  212%
  213%   In many cases debugging an exception that  is caught is as simple as
  214%   below (assuming run/0 starts your program).
  215%
  216%   ```
  217%   ?- trap(_).
  218%   ?- run.
  219%   ```
  220%
  221%   The multifile hook trap_alias/2 allow for   defining short hands for
  222%   commonly used traps.  Currently this defines
  223%
  224%     - det
  225%       Trap determinism exceptions raised as a result of the det/1
  226%       directive.
  227%     - =>
  228%       Trap rule existence error exceptions.
  229%
  230%   @see gtrap/1 to trap using the graphical debugger.
  231%   @see _Edit exceptions_ menu in PceEmacs and the graphical debugger
  232%   that provide a graphical frontend to trap exceptions.
  233
  234:- dynamic
  235    exception/4,                    % Name, Term, NotCaught, Caught
  236    installed/1.                    % ClauseRef
  237
  238trap(Error) :-
  239    '$notrace'(trap_(Error)).
  240
  241trap_(Spec) :-
  242    expand_trap(Spec, Formal),
  243    gensym(ex, Rule),
  244    asserta(exception(Rule, error(Formal, _), true, true)),
  245    print_message(informational, trap(Rule, error(Formal, _), true, true)),
  246    install_exception_hook,
  247    debug.
  248
  249notrap(Error) :-
  250    '$notrace'(notrap_(Error)).
  251
  252notrap_(Spec) :-
  253    expand_trap(Spec, Formal),
  254    Exception = error(Formal, _),
  255    findall(exception(Name, Exception, NotCaught, Caught),
  256            retract(exception(Name, error(Formal, _), Caught, NotCaught)),
  257            Trapping),
  258    print_message(informational, notrap(Trapping)).
  259
  260expand_trap(Var, _Formal), var(Var) =>
  261    true.
  262expand_trap(Alias, Formal), trap_alias(Alias, For) =>
  263    Formal = For.
  264expand_trap(Explicit, Formal) =>
  265    Formal = Explicit.
  266
  267%!  trap_alias(+Alias, -Error)
  268%
  269%   Define short hands for commonly used exceptions.
  270
  271trap_alias(det,                  determinism_error(_Pred, _Declared, _Observed, property)).
  272trap_alias(=>,			 existence_error(rule, _)).
  273trap_alias(existence_error,      existence_error(_,_)).
  274trap_alias(type_error,           type_error(_,_)).
  275trap_alias(domain_error,         domain_error(_,_)).
  276trap_alias(permission_error,     permission_error(_,_,_)).
  277trap_alias(representation_error, representation_error(_)).
  278trap_alias(resource_error,       resource_error(_)).
  279trap_alias(syntax_error,         syntax_error(_)).
  280
  281trapping :-
  282    findall(exception(Name, Term, NotCaught, Caught),
  283            exception(Name, Term, NotCaught, Caught),
  284            Trapping),
  285    print_message(information, trapping(Trapping)).
  286
  287:- dynamic   prolog:prolog_exception_hook/5.  288:- multifile prolog:prolog_exception_hook/5.  289
  290%!  exception_hook(+ExIn, -ExOut, +Frame, +Catcher, +DebugMode) is
  291%!                 failure.
  292%
  293%   Trap exceptions and consider whether or not to start the tracer.
  294
  295:- public exception_hook/5.  296
  297exception_hook(Ex, Ex, Frame, Catcher, _Debug) :-
  298    thread_self(Me),
  299    thread_property(Me, debug(true)),
  300    broadcast(debug(exception(Ex))),
  301    exception(_, Ex, NotCaught, Caught),
  302    !,
  303    (   Caught == true
  304    ->  true
  305    ;   Catcher == none,
  306        NotCaught == true
  307    ),
  308    \+ direct_catch(Frame),
  309    trace, fail.
  310
  311%!  direct_catch(+Frame) is semidet.
  312%
  313%   True if we are dealing with a  catch(SytemPred, _, _), i.e., a catch
  314%   directly wrapped around a call to  a   built-in.  In that case it is
  315%   highly unlikely that we want the debugger to step in.
  316
  317direct_catch(Frame) :-
  318    prolog_frame_attribute(Frame, parent, Parent),
  319    prolog_frame_attribute(Parent, predicate_indicator, system:catch/3),
  320    prolog_frame_attribute(Frame, level, MyLevel),
  321    prolog_frame_attribute(Parent, level, CatchLevel),
  322    MyLevel =:= CatchLevel+1.
  323
  324%!  install_exception_hook
  325%
  326%   Make sure our handler is the first of the hook predicate.
  327
  328install_exception_hook :-
  329    installed(Ref),
  330    (   nth_clause(_, I, Ref)
  331    ->  I == 1, !                   % Ok, we are the first
  332    ;   retractall(installed(Ref)),
  333        erase(Ref),                 % Someone before us!
  334        fail
  335    ).
  336install_exception_hook :-
  337    asserta((prolog:prolog_exception_hook(Ex, Out, Frame, Catcher, Debug) :-
  338                    exception_hook(Ex, Out, Frame, Catcher, Debug)), Ref),
  339    assert(installed(Ref)).
  340
  341
  342		 /*******************************
  343		 *            MESSAGES		*
  344		 *******************************/
  345
  346:- multifile
  347    prolog:message//1.  348
  349prolog:message(trapping([])) -->
  350    [ 'No exception traps'-[] ].
  351prolog:message(trapping(Trapping)) -->
  352    [ 'Exception traps on'-[], nl ],
  353    trapping(Trapping).
  354prolog:message(trap(_Rule, Error, _Caught, _NotCaught)) -->
  355    [ 'Installed trap for exception '-[] ],
  356    exception(Error),
  357    [ nl ].
  358prolog:message(notrap([])) -->
  359    [ 'No matching traps'-[] ].
  360prolog:message(notrap(Trapping)) -->
  361    [ 'Removed traps from exceptions'-[], nl ],
  362    trapping(Trapping).
  363
  364trapping([]) --> [].
  365trapping([exception(_Rule, Error, _Caught, _NotCaught)|T]) -->
  366    [ '  '-[] ],
  367    exception(Error),
  368    [ nl ],
  369    trapping(T).
  370
  371exception(Term) -->
  372    { copy_term(Term, T2),
  373      numbervars(T2, 0, _, [singletons(true)])
  374    },
  375    [ '~p'-[T2] ]