\chapter{Hackers corner}

This appendix describes a number of predicates which enable the Prolog
user to inspect the Prolog environment and manipulate (or even redefine)
the debugger.  They can be used as entry points for experiments with
debugging tools for Prolog. The predicates described here should be
handled with some care as it is easy to corrupt the consistency of the
Prolog system by misusing them.

\section{Examining the Environment Stack}

\begin{description}
    \predicate{prolog_current_frame}{1}{-Frame}
Unify \arg{Frame} with an integer providing a reference to the parent of
the current local stack frame.  A pointer to the current local frame
cannot be provided as the predicate succeeds deterministically and
therefore its frame is destroyed immediately after succeeding.

    \predicate{prolog_frame_attribute}{3}{+Frame, +Key, -Value}
Obtain information about the local stack frame \arg{Frame}.  \arg{Frame}
is a frame reference as obtained through prolog_current_frame/1, 
prolog_trace_interception/4 or this predicate.  The key values are
described below.

\begin{description}
    \termitem{alternative}{}
\arg{Value} is unified with an integer reference to the local stack
frame in which execution is resumed if the goal associated with
\arg{Frame} fails. Fails if the frame has no alternative frame.
    \termitem{has_alternatives}{}
\arg{Value} is unified with \const{true} if \arg{Frame} still is a
candidate for backtracking. \const{false} otherwise.
    \termitem{goal}{}
\arg{Value} is unified with the goal associated with \arg{Frame}. If the
definition module of the active predicate is not \const{user} the goal
is represented as \mbox{\tt <module>:<goal>}. Do not instantiate
variables in this goal unless you {\bf know} what you are doing!
    \termitem{clause}{}
\arg{Value} is unified with a reference to the currently running clause.
Fails if the current goal is associated with a foreign (C) defined
predicate. See also nth_clause/3 and clause_property/2.
    \termitem{level}{}
\arg{Value} is unified with the recursion level of \arg{Frame}. The top
level frame is at level `0'.
    \termitem{parent}{}
\arg{Value} is unified with an integer reference to the parent local
stack frame of \arg{Frame}. Fails if \arg{Frame} is the top frame.
    \termitem{context_module}{}
\arg{Value} is unified with the name of the context module of the
environment.
    \termitem{top}{}
\arg{Value} is unified with \const{true} if \arg{Frame} is the top Prolog
goal from a recursive call back from the foreign language. \const{false}
otherwise.
    \termitem{hidden}{}
\arg{Value} is unified with \const{true} if the frame is hidden from the
user, either because a parent has the hide-childs attribute (all system
predicates), or the system has no trace-me attribute.
    \termitem{pc}{}
\arg{Value} is unified with the program-pointer saved on behalve of the
parent-goal if the parent-goal is not owned by a foreign predicate.
    \termitem{argument}{N}
\arg{Value} is unified with the \arg{N}-th slot of the frame. Argument
1 is the first argument of the goal. Arguments above the arity
refer to local variables. Fails silently if \arg{N} is out of range.
\end{description}
\end{description}


\section{Intercepting the Tracer}

\begin{description}
    \predicate{prolog_trace_interception}{4}{+Port, +Frame, +PC, -Action}
Dynamic predicate, normally not defined. This predicate is called from
the SWI-Prolog debugger just before it would show a port. If this
predicate succeeds the debugger assumes the trace action has been taken
care of and continues execution as described by \arg{Action}. Otherwise
the normal Prolog debugger actions are performed.

\arg{Port} is one of \const{call}, \const{redo}, \const{exit}, \const{fail} or
\const{unify}. \arg{Frame} is an integer reference to the current local
stack frame. \arg{PC} is the current value of the program-counter,
relative to the start of the current clause, or 0 if it is invalid,
for example because the current frame runs a foreign predicate, or
no clause has been selected yet. \arg{Action} should be unified with one
of the atoms \const{continue} (just continue execution), \const{retry}
(retry the current goal) or \const{fail} (force the current goal to fail).
Leaving it a variable is identical to \const{continue}.

Together with the predicates described in \secref{debugger}
and the other predicates of this chapter this predicate enables the
Prolog user to define a complete new debugger in Prolog. Besides this it
enables the Prolog programmer monitor the execution of a program. The
example below records all goals trapped by the tracer in the database.

\begin{code}
prolog_trace_interception(Port, Frame, _PC, continue) :-
        prolog_frame_attribute(Frame, goal, Goal), 
        prolog_frame_attribute(Frame, level, Level), 
        recordz(trace, trace(Port, Level, Goal)).
\end{code}

To trace the execution of `go' this way the following query should be
given:

\begin{code}
?- trace, go, notrace.
\end{code}

    \predicate{prolog_skip_level}{2}{-Old, +New}
Unify \arg{Old} with the old value of `skip level' and than set this
level according to \arg{New}.  New is an integer, or the special atom
\const{very_deep} (meaning don't skip).  The `skip level' is a global
variable of the Prolog system that disables the debugger on all
recursion levels deeper than the level of the variable.  Used to
implement the trace options `skip' (sets skip level to the level of the
frame) and `up' (sets skip level to the level of the parent frame (i.e.\
the level of this frame minus 1).

    \predicate{prolog_list_goal}{1}{:Goal}
Hook, normally not defined. This hook is called by the 'L' command of
the tracer in the module \module{user} to list the currently called
predicate. This hook may be defined to list only relevant clauses of the
indicated \arg{Goal} and/or show the actual source-code in an editor.
See also portray/1 and multifile/1.
\end{description}


\section{Hooks using the exception/3 predicate}

This section describes the predicate exception/3, which may be defined
by the user in the module \module{user} as a multifile predicate. Unlike
the name suggests, this is actually a \jargon{hook} predicate.
Exceptions are handled by the ISO predicates catch/3 and throw/1.  They
all frames created after the matching catch/3 to be discarded
immediately.

The predicate exception/3 is called by the kernel on a couple of events,
allowing the user to alter the behaviour on some predefined events.

\begin{description}
    \predicate{exception}{3}{+Exception, +Context, -Action}
Dynamic predicate, normally not defined.  Called by the Prolog system on
run-time exceptions.  Currently exception/3 is only used for trapping
undefined predicates.  Future versions might handle signal handling, 
floating exceptions and other runtime errors via this mechanism. The
values for \arg{Exception} are described below.

\begin{description}
    \termitem{undefined_predicate}{}
If \arg{Exception} is \const{undefined_predicate} \arg{Context} is
instantiated to a term \arg{Name}/\arg{Arity}. \arg{Name} refers to the
name and \arg{Arity} to the arity of the undefined predicate. If the
definition module of the predicate is not \arg{user}, \arg{Context} will
be of the form \mbox{\tt <Module>:<Name>/<Arity>}. If the predicate
fails Prolog will generate an \except{esistence_error} exception. If the
predicate succeeds it should instantiate the last argument either to the
atom \const{fail} to tell Prolog to fail the predicate, the atom
\const{retry} to tell Prolog to retry the predicate or \const{error} to
make the system generate an exception. The action \const{retry} only
makes sense if the exception handler has defined the predicate.
\end{description}
\end{description}


\section{Readline Interaction}

The following predicates are available if
\exam{current_prolog_flag(readline, true)} succeeds. They allow for
direct interaction with the GNU readline library. See also
\manref{readline}{3}

\begin{description}
    \predicate{rl_read_init_file}{1}{+File}
Read a readline initialisation file.  Readline by default reads
\file{~/.inputrc}.  This predicate may be used to read alternative
readline initialisation files.
    \predicate{rl_add_history}{1}{+Line}
Add a line to the Control-P/Control-N history system of the readline library.
\end{description}