new section describing the debug interface.

1 files changed, 142 insertions, 9 deletions

diff --git a/manual.tex b/manual.tex
index a3b9309e..e210a039 100644
--- a/manual.tex
+++ b/manual.tex
@@ -1,4 +1,4 @@
-% $Id: manual.tex,v 1.5 1996/02/05 14:52:47 roberto Exp roberto $
+% $Id: manual.tex,v 1.6 1996/02/05 21:32:19 roberto Exp roberto $
 
 \documentstyle[A4,11pt,bnf]{article}
 
@@ -32,11 +32,10 @@ Waldemar Celes Filho
 Departamento de Inform\'atica --- PUC-Rio
 }
 
-\date{\small \verb$Date: 1996/02/05 14:52:47 $}
+\date{\small \verb$Date: 1996/02/05 21:32:19 $}
 
 \maketitle
 
-
 \begin{abstract}
 \noindent
 Lua is an extension programming language designed to be used
@@ -572,7 +571,7 @@ into the variable \verb'var'.
 Parameters act as local variables,
 initialized with the argument values.
 \begin{Produc}
-\produc{parlist1}{'name' \rep{\ter{,} name}}
+\produc{parlist1}{name \rep{\ter{,} name}}
 \end{Produc}
 
 Results are returned using the \verb'return' statement (\see{return}).
@@ -704,11 +703,12 @@ is terminated returning an error condition.
 The only argument to the error fallback function is a string describing
 the error.
 The standard I/O library redefines this fallback,
-using the debug API, in order to print some extra informations,
+using the debug facilities (\see{debugI},
+in order to print some extra informations,
 like the stack of calls.
 For more information about an error,
 the Lua program can include the compilation pragma \verb'$debug'.
-\index{debug pragma}
+\index{debug pragma}\label{pragma}
 This pragma must be written in a line by itself.
 When an error occurs in a program compiled with this option,
 the error routine is able to print also the lines where the calls
@@ -1454,6 +1454,135 @@ hours ([0-23]), minutes, and seconds.
 % This function then returns and the execution of the program continues.
 
 
+
+\section{The Debuger Interface} \label{debugI}
+
+Lua has no built in debuger facilities.
+Instead, it offers a special interface,
+by means of functions and {\em hooks},
+which allows the construction of different
+kinds of debugers, profiles, and other tools
+that need ``inside'' information from the interpreter.
+This interface is declared in the file \verb'luadebug.h'.
+
+\subsection{Stack and Function Information}
+
+The main function to get information about the interpreter stack
+is
+\begin{verbatim}
+lua_Function lua_stackedfunction (int level);
+\end{verbatim}
+It returns a handle (\verb'lua_Function') to the {\em activation record}
+of the function executing at a given level.
+Level 0 is the current running function,
+while level $n+1$ is the function that has called level $n$.
+When called with a level greater than the stack depth,
+\verb'lua_stackedfunction' returns \verb'LUA_NOOBJECT'.
+
+The type \verb'lua_Function' is just another name
+to \verb'lua_Object'.
+Although, in this library,
+a \verb'lua_Function' can be used wherever a \verb'lua_Object' is required,
+a parameter \verb'lua_Function' accepts only a handle returned by
+\verb'lua_stackedfunction'.
+
+Three other functions produce extra information about a function:
+\begin{verbatim}
+void lua_funcinfo (lua_Object func, char **filename, int *linedefined);
+int lua_currentline (lua_Function func);
+char *lua_getobjname (lua_Object o, char **name);
+\end{verbatim}
+\verb'lua_funcinfo' gives the file name and the line where the
+given function has been defined.
+If the ``function'' is in fact the main code of a chunk,
+\verb'linedefined' is 0.
+If the function is a C function,
+\verb'linedefined' is -1, and \verb'filename' is \verb'"(C)"'.
+
+The function \verb'lua_currentline' gives the current line where
+a given function is executing.
+It only works if the function has been pre-compiled with debug
+information (\see{pragma}).
+When no line information is available, it returns -1.
+
+Function \verb'lua_getobjname' tries to find a reasonable name for
+a given function.
+Because functions in Lua are first class values,
+they do not have a fixed name.
+Some functions may be the value of many global variables,
+while others may be stored only in a table field.
+Function \verb'lua_getobjname' first checks whether the given
+function is a fallback.
+If so, it returns the string \verb'"fallback"',
+and \verb'name' is set to point to the fallback name.
+Otherwise, if the given function is the value of a global variable,
+\verb'lua_getobjname' returns the string \verb'"global"',
+while \verb'name' points to the variable name.
+If the given function is neither a fallback nor a global variable,
+\verb'lua_getobjname' returns the empty string,
+and \verb'name' is set to \verb'NULL'.
+
+\subsection{Manipulating Local Variables}
+
+The following functions allow the manipulation of the
+local variables of a given activation record.
+They only work if the function has been pre-compiled with debug
+information (\see{pragma}).
+\begin{verbatim}
+lua_Object lua_getlocal (lua_Function func, int local_number, char **name);
+int lua_setlocal (lua_Function func, int local_number);
+\end{verbatim}
+The first one returns the value of a local variable,
+and sets \verb'name' to point to the variable name.
+\verb'local_number' is an index for local variables.
+The first parameter has index 1, and so on, until the
+last active local variable.
+When called with a \verb'local_number' greater than the
+number of active local variables,
+or if the activation record has no debug information,
+\verb'lua_getlocal' returns \verb'LUA_NOOBJECT'.
+
+The function \verb'lua_setlocal' sets the local variable
+\verb'local_number' to the value previously pushed on the stack
+(\see{valuesCLua}).
+If the function succeeds it returns 1.
+If \verb'local_number' is greater than the number
+of active local variables,
+or if the activation record has no debug information,
+this function fails and returns 0.
+
+\subsection{Hooks}
+
+The Lua interpreter offers two hooks for debug purposes:
+\begin{verbatim}
+typedef void (*lua_CHFunction) (lua_Function func, char *file, int line);
+typedef void (*lua_LHFunction) (int line);
+\end{verbatim}
+The first one is called whenever the interpreter enters or leaves a
+function.
+When entering a function,
+its parameters are a handle to the function activation record,
+plus the file and the line where the function is defined (the same
+information which is provided by \verb'lua_funcinfo');
+when leaving a function, \verb'func' is \verb'LUA_NOOBJECT',
+\verb'file' is \verb'"(return)"', and \verb'line' is 0.
+
+The other hook is called every time the interpreter changes
+the line of code it is executing.
+Its only parameter is the line number
+(the same information which is provided by the call
+\verb'lua_currentline(lua_stackedfunction(0))').
+This second hook is only called if the active function
+has been pre-compiled with debug information (\see{pragma}).
+
+To set these hooks, there are the functions:
+\begin{verbatim}
+lua_LHFunction lua_setlinehook (lua_LHFunction hook);
+lua_CHFunction lua_setcallhook (lua_CHFunction hook);
+\end{verbatim}
+Both return the previous hook.
+
+
 \section{Some Examples}
 
 This section gives examples showing some features of Lua.
@@ -1473,7 +1602,8 @@ Arrays can be indexed by 0, negative numbers, or any other value (but \nil).
 Records are also trivially implemented by the syntactic sugar
 \verb'a.x'.
 
-The best way to implement a set is to use the indices of a table.
+The best way to implement a set is to store
+its elements as indices of a table.
 The statement \verb's = {}' creates an empty set \verb's'. 
 The statement \verb's[x] = 1' inserts the value of \verb'x' into
 the set \verb's'.
@@ -1874,8 +2004,8 @@ The authors would like to thank CENPES/PETROBR\'AS which,
 jointly with TeCGraf, used extensively early versions of
 this system and gave valuable comments.
 The authors would also like to thank Carlos Henrique Levy,
-who found the name of the game%
-\footnote{BTW, Lua means {\em moon} in Portuguese.}.
+who found the name of the game.
+Lua means {\em moon} in Portuguese.
 
 
 
@@ -1945,7 +2075,10 @@ Special care should be taken with macros like
 \verb'lua_getindexed' and \verb'lua_getfield'.
 \end{itemize}
 
+\pagebreak
+\tableofcontents
 \newcommand{\indexentry}[2]{\item {#1} #2}
+%\catcode`\_=12
 \begin{theindex}
 \input{manual.idx}
 \end{theindex}