reduce-historical/r38/doc/help/rdebug.tex

\begin{document}

\begin{Introduction}{Debugging}

The package \name{RDEBUG} helps you to find bugs in algebraic
REDUCE programs by making the functions of the PSL package 
\name{DEBUG} available for algebraic mode.
The following facilities are available:

Entry-exit trace (\nameref{tr}, \nameref{untr}): 
visualize every call of 
explicitly declared functions, printing their arguments and
results.

Assignment trace (\nameref{trst}, \nameref{untrst}): 
report all assignments which
are executed inside explicitly declared functions. This facility
is not available for compiled functions.

Breakpoint (\nameref{br}, \nameref{unbr}): 
interrupt the program execution at
entry and exit of explicitly declared functions, invoking
a \nameref{breakloop}.

Conditional trace (\nameref{trwhen}, \nameref{untrwhen}) 
or break (\nameref{brwhen},\nameref{unbrwhen}).

Rule trace (\nameref{trrl}, \nameref{untrrl}): 
report the arguments and results of a rule whenever it fires.

You can control the debug output using the operator \nameref{trout}
and the variable \nameref{trlimit}.

\end{Introduction}

%=============================================================

\begin{Concept}{breakloop}
\index{debug}
A \name{break loop} is an interrupt of the program execution
where control is given temporarily to the terminal for
entering commands in a standard command - evaluate - print loop. 
When a break occurs, you can inspect the current
 environment or even alter it, and the
interrupted computation may be terminated or continued.
A break can be caused

- by an internal error when the switch \nameref{break} is on,
 
- by an explicit call of \name{lisp break()},

- at entry and exit time of a procedure which has been 
 declared by \nameref{br}.

In a break situation the evaluation  is stopped temporarily
and the control returns to the terminal with a special prompt:
\name{break[1]1:}.
The number in square brackets counts the break level - it is
increased when a break occurs inside a break; the normal
REDUCE statement counter follows. Each break loop supports its
own statement numbers and input and output buffers.
After terminating of a break loop the
previous statement counters and buffers are restored.

In a break loop all REDUCE commands can be
entered. Additionally, there is a set of single character commands
which allow you to control the break environment. All these
begin with an underscore character:


\name{\_a;}  terminate break  and return to the top  REDUCE level

\name{\_c;}  continue execution of interrupted procedure

\name{\_i;}    print a backtrace (list of procedures in the 
               call hierarchy)

\name{\_l} \meta{var}; (local) read the content of the local variable
             \meta{var}

\name{\_m;}  print the last (LISP-) error message  

\name{\_q;}  terminate the break loop and return to the next 
             higher level.


Global variables can be accessed as usual in the REDUCE language.
They can also be set to different values in the break loop.
The inspect values assigned to dummy arguments and scalar variables of
procedures in the actual call hierarchy, you need a special command 
\name{\_l}. These values cannot be altered in the break loop.
\begin{Examples}
  procedure p1(x); \\
    begin scalar y1; y1:=x^2; return p2(y1); end;\\
  procedure p2(q); q^2;\\
  br p2;\\
  x:=22;\\
  p1(alpha);\\
p2 being entered\\

   q:   alpha**2$\\
Break before entering `p2'\\
break[1]1: x; & 22\\
break[1]2: _l x; & alpha\\
break[1]3: _l y1; & alpha^2 \\
break[1]4: _l q;& alpha^2 \\
break[1]6: _c;\\
Break after call `p2', value `(expt (expt alpha 2) 2)'\\
break[1]1: _c;\\
&alpha^4\\
\end{Examples}
In the corresponding break loop caused by calling \name{p2} 
indirectly via \name{p1}, you can access the global \name{x}, the
locals \name{x} and \name{y1} of \name{p1} and the \name{q} of 
\name{p2}.
\end{Concept}

%=========================================================

\begin{Operator}{tr}
\index{trace}\index{debug}
The command \name{tr} puts one or several procedures to
under trace. Every time such a function is executed, a message
is printed during the procedure entry and another one is generated
at the return time. The entry message records the 
actual procedure arguments equated to the dummy parameter
names, and at the exit time the procedure value is printed.
Recursive calls are marked by an indentation and a level number.

\begin{Syntax}
   \name{tr}\meta{proc1},\meta{proc2},...,\meta{procn};
\end{Syntax}
Here  \meta{proc1},\meta{proc2},...,\meta{procn} 
are names of procedures
to be added to the set of traced procedures. See also
\nameref{trst},\nameref{trwhen}.
\end{Operator}

\begin{Operator}{untr}
\index{trace}\index{debug}
Tracing is stopped for one or several functions by the
command \name{untr}:
\begin{Syntax}
   \name{untr}\meta{proc1},\meta{proc2},...,\meta{procn};
\end{Syntax}
\end{Operator}

%========================================================

\begin{Operator}{trst}
\index{trace}\index{assignment-trace}\index{debug}
Sometimes one needs detailed information about the inner behavior of
a procedure, especially if it is a longer piece of code.
For a procedure declared in a \name{trst} command 
an extended trace is performed:
all executed explicit assignments and all passed labels 
are reported at run time.

\begin{Syntax}
   \name{trst}\meta{proc1},\meta{proc2},...,\meta{procn};
\end{Syntax}
Here  \meta{proc1},\meta{proc2},...,\meta{procn} 
are names of procedures
to be added to the set of traced procedures. 

When your program contains a \nameref{for} loop, 
REDUCE translates this to a sequential piece of
LISP instructions. When using \name{trst}, the printout
is driven by the unfolded code. When the code contains a
\name{for-each-in} statement, the name of the control variable is
internally used to keep the remainder of the list during the loop
control, and you will see the corresponding assignments
in the printout rather than the individual values in the
loop steps.
\end{Operator}

\begin{Operator}{untrst}
\index{trace}\index{assignment-trace}\index{debug}
Extended tracing is stopped for one or several functions by the
command \name{untrst}:
\begin{Syntax}
   \name{untrst}\meta{proc1},\meta{proc2},...,\meta{procn};
\end{Syntax}
\end{Operator}

%=========================================================

\begin{Operator}{trwhen}
\index{trace}\index{debug}
The trace output can be tunrned on or off automatically by
a boolean expression which is linked to a traced procedure
by the command \name{trwhen}:
\begin{Syntax}
   trwhen \meta{name},\meta{booleanexpr};
\end{Syntax}
The boolean expression must follow
standard REDUCE syntax. It may contain references
to global values and to
the actual parameters of the procedure. As long as the
procedure is not compiled, the original names of the dummy arguments
are used. For a compiled procedure the  original names 
are not available; instead the names \name{a1}, \name{a2}, ...
must be used. Example: the following procedure produces trace
output only if the main variable of its argument is \name{x}:
\begin{Examples}
    procedure hugo(u); otto(u);\\
    tr hugo;\\
    trwhen hugo,mainvar(u)=x;\\
\end{Examples}
Note: for a symbolic procedure, the \name{trwhen} command
must be given in symbolic mode or with prefix $symbolic$.

\end{Operator}

\begin{Operator}{untrwhen}
\index{trace}\index{debug}
Conditional trace is stopped for a procedure by calling
\begin{Syntax}
   untrwhen \meta{name};
\end{Syntax}
\end{Operator}

%========================================================

\begin{Switch}{break}
\index{debug}

When the switch \name{break} is set on, every
evaluation error causes a \nameref{breakloop}. Most of these
breaks are non-continuable; however, you have the 
opportunity to read the actual values of local variables
in the environment which caused the error.
\end{Switch}

%=========================================================

\begin{Operator}{br}
\index{break}\index{debug}
The command \name{br} declares one or several procedures 
as breakpoints. When executing such a function, the
computation is interrupted by a \nameref{breakloop}
at function enter and return times.

\begin{Syntax}
   \name{br}\meta{proc1},\meta{proc2},...,\meta{procn};
\end{Syntax}
Here  \meta{proc1},\meta{proc2},...,\meta{procn} 
are names of procedures
to be added to the set of break points. 
See also \nameref{brwhen}.
\end{Operator}

\begin{Operator}{unbr}
\index{break}\index{debug}
The break property 
can be removed by the command \name{unbr}:
\begin{Syntax}
   \name{unbr}\meta{proc1},\meta{proc2},...,\meta{procn};
\end{Syntax}
\end{Operator}

% =============================================================

\begin{Operator}{brwhen}
\index{break}\index{debug}
The break point (see \nameref{br})
 can be tunrned on or off automatically by
a boolean expression which is linked to a breakpoint procedure
by the command \name{brwhen}:
\begin{Syntax}
   brwhen \meta{name},\meta{booleanexpr};
\end{Syntax}
The boolean expression must follow
standard REDUCE syntax. It may contain references
to global values and to
the actual parameters of the procedure. As long as the
procedure is not compiled, the original names of the dummy arguments
are used. For a compiled procedure the  original names 
are not available; instead the names \name{a1}, \name{a2}, ...
must be used. Example: the following procedure is broken 
only if the main variable of its argument is \name{x}:
\begin{Examples}
    procedure hugo(u); otto(u);\\
    br hugo;\\
    brwhen hugo,mainvar(u)=x;\\
\end{Examples}
Note: for a symbolic procedure, the \name{brwhen} command
must be given in symbolic mode or with prefix $symbolic$.

\end{Operator}

\begin{Operator}{unbrwhen}
\index{break}\index{debug}
Conditional break is removed for a procedure by calling
\begin{Syntax}
   unbrwhen \meta{name};
\end{Syntax}
\end{Operator}

% ==============================================================

\begin{Operator}{trrl}
\index{debug}\index{rule}\index{ruleset}
The command \name{trrl} allows you to trace individual rules
or rule sets when they fire.
\begin{Syntax}
   trrl \meta{rs1},\meta{rs2},...,\meta{rsn};
\end{Syntax}
where each of the \meta{rsi} is

- a rule or a rule set,

- a name of a rule or rule set (that is a non--indexed variable which
      is bound to a rule or rule list),

- an operator name, representing the rules assigned to this
      operator.

The specified rules are (re-) activated in REDUCE in
a style that each of them prints a report every time if fires.
The report is composed of the name or the rule or the 
name of the rule set plus the number of the rule in the set,
the form matching the left hand side  and the 
resulting right hand side. 
For an explicitly given rule, \name{trrl} assigns a generated name.
\end{Operator}

\begin{Operator}{untrrl}
\index{debug}\index{rule}\index{ruleset}
With \name{untrrl} you can remove the tracing from rules
\begin{Syntax}
   untrrl \meta{rs1},\meta{rs2},...,\meta{rsn};
\end{Syntax}
The rules are reactivated in their original form. Alternatively
you can use the command \nameref{clearrules} to remove the
rules totally from the system. Please do not modify the
rules between \name{trrl} and \name{untrrl} -- the result
may be unpredictable. 
\end{Operator}  

%==============================================================

\begin{Operator}{trout}
\index{debug}\index{io}
The trace output can be redirected to a separate file
by using the command \name{trout}, followed
by a file name in string quotes. A second call of \name{trout}
closes the actual output file and assigns a new one. 
The file name NIL (without string quotes) causes the trace output 
to be redirected to the standard output device.

Remark: under Windows a file name starting with "win:" causes
a new window to be opened which receives the complete 
output of the debugging services.
\end{Operator}

%==============================================================

\begin{Variable}{trlimit}
\index{debug}\index{io}
The integer valued share variable \name{trlimit} defines
an upper limit for the number of items printed in formula
collections. The
initial value is 5. A different value can be assigned to
increase or lower the output size.
\begin{Examples}
   trlimit:=7;\\
\end{Examples}
\end{Variable}

%==============================================================

\begin{Variable}{trprinter}
\index{debug}\index{io}
If you want to select LISP style printing instead of
algebraic printing during trace, set \name{trprinter!*}
to \name{printx}:
\begin{Syntax}
   lisp(trprinter!* := 'printx);
\end{syntax}
\end{Variable}