\chapter{Hackers corner}			\label{sec:hack}

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}	\label{sec:manipstack}

\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}

    \predicate{deterministic}{0}{}
Succeeds if there are no choicepoints that are more recent than the
parent frame.
\end{description}


\section{Intercepting the Tracer}		\label{sec:tracehook}

\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).
\end{description}


\section{Hooks using the exception/3 predicate}	\label{sec:exception3}

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{Hooks for integrating libraries}	\label{sec:intlibs}

Some libraries realise an entirely new programming paradigm on top of
Prolog.  An example is XPCE which adds an object-system to Prolog as
well as an extensive set of graphical primitives.  SWI-Prolog provides
several hooks to improve the integration of such libraries.  See also
\secref{listing} for editing hooks and \secref{printmsg} for hooking
into the message system.

\begin{description}
    \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.

    \predicate{prolog:debug_control_hook}{1}{:Action}
Hook for the debugger-control predicates that allows the creator of
more high-level programming languages to use the common front-end
predicates to control de debugger.  For example, XPCE uses these hooks
to allow for spying methods rather then predicates. \arg{Action} is one
of:

\begin{description}
    \termitem{spy}{Spec}
Hook in spy/1.  If the hook succeeds spy/1 takes no further action.
    \termitem{nospy}{Spec}
Hook in nospy/1.  If the hook succeeds spy/1 takes no further action.
If spy/1 is hooked, it is advised to place a complementary hook for
nospy/1.
    \termitem{nospyall}{}
Hook in nospyall/0.  Should remove all spy-points.  This hook is
called in a failure-driven loop.
    \termitem{debugging}{}
Hook in debugging/0.  It can be used in two ways.  It can report
the status of the additional debug-points controlled by the above
hooks and fail to let the system report the others or it succeed,
overruling the entire behaviour of debugging/0.
\end{description}

    \predicate{prolog:help_hook}{1}{+Action}
Hook into help/0 and help/1.  If the hook succeeds, the built-in actions
are not executed. For example, \exam{?- help(picture).} is caught by the
XPCE help-hook to give help on the class {\em picture}.  Defined actions
are:

\begin{description}
    \termitem{help}{}
User entered plain help/0 to give default help.  The default performs
\exam{help(help/1)}, giving help on help.
    \termitem{help}{What}
Hook in help/1 on the topic \arg{What}.
    \termitem{apropos}{What}
Hook in apropos/1 on the topic \arg{What}.
\end{description}
\end{description}


\section{Readline Interaction}		\label{sec:readline}

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}