\section{KEYBOARD Initiate Interactive Debug Session}

\subsection{Usage}

The \verb|keyboard| statement is used to initiate an
interactive session at a specific point in a function.
The general syntax for the \verb|keyboard| statement is
\begin{verbatim}
   keyboard
\end{verbatim}
A \verb|keyboard| statement can be issued in a \verb|script|,
in a \verb|function|, or from within another \verb|keyboard| session.
The result of a \verb|keyboard| statement is that execution
of the program is halted, and you are given a prompt
of the form:
\begin{verbatim}
 [scope,n] -->
\end{verbatim}
where \verb|scope| is the current scope of execution (either
the name of the function we are executing, or \verb|base| otherwise).
And \verb|n| is the depth of the \verb|keyboard| session. If, for example,
we are in a \verb|keyboard| session, and we call a function that issues
another \verb|keyboard| session, the depth of that second session 
will be one higher.  Put another way, \verb|n| is the number of \verb|return|
statements you have to issue to get back to the base workspace.
Incidentally, a \verb|return| is how you exit the \verb|keyboard| session
and resume execution of the program from where it left off.  A
\verb|retall| can be used to shortcut execution and return to the base
workspace.

The \verb|keyboard| statement is an excellent tool for debugging
FreeMat code, and along with \verb|eval| provide a unique set of
capabilities not usually found in compiled environments.  Indeed,
the \verb|keyboard| statement is equivalent to a debugger breakpoint in 
more traditional environments, but with significantly more inspection
power.
\subsection{Example}

Here we demonstrate a two-level \verb|keyboard| situation.  We have
a simple function that calls \verb|keyboard| internally:
\begin{verbatim}
    key_one.m
function c = key_one(a,b)
c = a + b;
keyboard
\end{verbatim}
Now, we execute the function from the base workspace, and
at the \verb|keyboard| prompt, we call it again.  This action
puts us at depth 2.  We can confirm that we are in the second
invocation of the function by examining the arguments.  We
then issue two \verb|return| statements to return to the base
workspace.
\begin{verbatim}
--> key_one(1,2)
[key_one,3]--> key_one(5,7)
[key_one,3]--> a
ans = 
  <int32>  - size: [1 1]
 5  
[key_one,3]--> b
ans = 
  <int32>  - size: [1 1]
 7  
[key_one,3]--> c
ans = 
  <int32>  - size: [1 1]
 12  
[key_one,3]--> return
ans = 
  <int32>  - size: [1 1]
 12  
[key_one,3]--> a
ans = 
  <int32>  - size: [1 1]
 1  
[key_one,3]--> b
ans = 
  <int32>  - size: [1 1]
 2  
[key_one,3]--> c
ans = 
  <int32>  - size: [1 1]
 3  
[key_one,3]--> return
ans = 
  <int32>  - size: [1 1]
 3  

\end{verbatim}
