From cc117253c83ec32d226a8f2226d5ca144804f873 Mon Sep 17 00:00:00 2001 From: Roberto Ierusalimschy Date: Fri, 21 Aug 1998 14:43:44 -0300 Subject: new implementation for error handling: on error, function _ERRORMESSAGE is called, which in turn calls _ALERT to write a message to stderr. --- manual.tex | 99 +++++++++++++++++++++++++++++--------------------------------- 1 file changed, 47 insertions(+), 52 deletions(-) (limited to 'manual.tex') diff --git a/manual.tex b/manual.tex index 50d4e67e..5f56593c 100644 --- a/manual.tex +++ b/manual.tex @@ -1,8 +1,10 @@ -% $Id: manual.tex,v 1.16 1998/06/19 18:47:06 roberto Exp roberto $ +% $Id: manual.tex,v 1.17 1998/06/29 18:09:28 roberto Exp roberto $ \documentclass[11pt]{article} \usepackage{fullpage,bnf} +\catcode`\_=12 + \newcommand{\See}[1]{Section~\ref{#1}} \newcommand{\see}[1]{(see \See{#1})} \newcommand{\M}[1]{\emph{#1}} @@ -19,7 +21,7 @@ \newcommand{\ff}{$\bullet$\ } -\newcommand{\Version}{3.1} +\newcommand{\Version}{3.2 (alpha)} \makeindex @@ -39,7 +41,7 @@ Waldemar Celes \tecgraf\ --- Computer Science Department --- PUC-Rio } -%\date{\small \verb$Date: 1998/06/19 18:47:06 $} +%\date{\small \verb$Date: 1998/06/29 18:09:28 $} \maketitle @@ -810,7 +812,7 @@ If the function is called in a place that can hold many values (syntactically denoted by the non-terminal \M{exp}), then no adjustment is made. Note that the only place that can hold many values -is the last expression (or the only one) in an assignment +is the last (or the only) expression in an assignment or in a return statement; see examples below. \begin{verbatim} f(); -- adjusted to 0 @@ -1263,22 +1265,20 @@ Because Lua is an extension language, all Lua actions start from C code in the host program calling a function from the Lua library. Whenever an error occurs during Lua compilation or execution, -the \Def{error method} is called, +function \verb|_ERRORMESSAGE| is called \Deffunc{_ERRORMESSAGE} +(provided it is different from \nil), and then the corresponding function from the library (\verb|lua_dofile|, \verb|lua_dostring|, \verb|lua_dobuffer|, or \verb|lua_callfunction|) is terminated, returning an error condition. -The only argument to the error method is a string +The only argument to \verb|_ERRORMESSAGE| is a string describing the error. -The default method prints this message to \verb|stderr|. -If needed, it is possible to change the error method with the -function \verb|seterrormethod|, -which gets the new error handler as its only parameter -\see{pdf-seterrormethod}. -The standard I/O library uses this facility to redefine the error method, -using the debug facilities \see{debugI}, -in order to print some extra information, +The default definition for this function calls \verb|_ALERT|, +which prints the message to \verb|stderr| \see{alert}. +The standard I/O library redefines \verb|_ERRORMESSAGE|, +and uses the debug facilities \see{debugI} +to print some extra information, such as the call stack. To provide more information about errors, @@ -1347,11 +1347,11 @@ For that, you must set \verb|lua_state| back to \verb|NULL| before calling \verb|lua_open|. An easy way to do that is defining an auxiliary function: \begin{verbatim} -lua_State *lua_newstate (void) { - lua_State *old = lua_setstate(NULL); - lua_open(); - return lua_setstate(old); -} + lua_State *lua_newstate (void) { + lua_State *old = lua_setstate(NULL); + lua_open(); + return lua_setstate(old); + } \end{verbatim} This function creates a new state without changing the current state of the interpreter. @@ -1373,14 +1373,14 @@ If \verb|lua_state| is already \verb|NULL|, \verb|lua_close| has no effect. If you are using multiple states, -you may find useful the following function, +you may find useful to define the following function, which releases a given state: \begin{verbatim} -void lua_freestate (lua_State *st) { - lua_State *old = lua_setstate(st); - lua_close(); - if (old != st) lua_setstate(old); -} + void lua_freestate (lua_State *st) { + lua_State *old = lua_setstate(st); + lua_close(); + if (old != st) lua_setstate(old); + } \end{verbatim} \subsection{Exchanging Values between C and Lua} \label{valuesCLua} @@ -1736,18 +1736,10 @@ If the C function has been called from Lua, then the corresponding Lua execution terminates, as if an error had occurred inside Lua code. Otherwise, the whole program terminates with a call to \verb|exit(1)|. -The \verb|message| is passed to the error handler method. +The \verb|message| is passed to the error handler function, +\verb|_ERRORMESSAGE|. If \verb|message| is \verb|NULL|, -the error handler method is not called. - -The error handler method \see{error} can be -changed with: \Deffunc{lua_seterrormethod} -\begin{verbatim} -lua_Object lua_seterrormethod (void); -\end{verbatim} -This function sets the object at the top of C2lua -as the new error method, -and returns the old error method value. +\verb|_ERRORMESSAGE| is not called. Tag methods can be changed with: \Deffunc{lua_settagmethod} \begin{verbatim} @@ -1885,7 +1877,7 @@ and \verb|lua_iolibopen|, declared in \verb|lualib.h|. \subsection{Predefined Functions} \label{predefined} -\subsubsection*{\ff \T{call (func, arg [, mode [, errmethod]])}}\Deffunc{call} +\subsubsection*{\ff \T{call (func, arg [, mode [, errhandler]])}}\Deffunc{call} \label{pdf-call} This function calls function \verb|func| with the arguments given by the table \verb|arg|. @@ -1917,14 +1909,15 @@ if an error occurs during the function call, the error is propagated. If the string \verb|mode| contains \verb|"x"|, then the call is \emph{protected}.\index{protected calls} -In this mode, function \verb|call| does not generate an error, +In this mode, function \verb|call| does not propagate an error, whatever happens during the call. Instead, it returns \nil\ to signal the error -(besides calling the appropriated error method). +(besides calling the appropriated error handler). -If provided, \verb|errmethod| is temporarily set as the error method, -while \verb|func| runs. -As a particular case, if \verb|errmethod| is \nil, +If provided, +\verb|errhandler| is temporarily set as the error function +\verb|_ERRORMESSAGE|, while \verb|func| runs. +As a particular example, if \verb|errhandler| is \nil, no error messages will be issued during the execution of the called function. \subsubsection*{\ff \T{collectgarbage ([limit])}}\Deffunc{collectgarbage} @@ -2055,9 +2048,16 @@ This function receives any number of arguments, and prints their values using the strings returned by \verb|tostring|. This function is not intended for formatted output, but only as a quick way to show a value, -for instance for error messages or debugging. +for instance for debugging. See \See{libio} for functions for formatted output. +\subsubsection*{\ff \T{_ALERT (message)}}\Deffunc{alert}\label{alert} +This function prints its only string argument to \IndexVerb{stderr}. +All error messages in Lua are printed through this function. +Therefore, a program may redefine it +to change the way such messages are shown +(for instance, for systems without \verb|stderr|). + \subsubsection*{\ff \T{tonumber (e [, base])}}\Deffunc{tonumber} This function receives one argument, and tries to convert it to a number. @@ -2164,13 +2164,6 @@ Its full semantics is explained in \See{tag-method}. The string \verb|name| does not need to be a syntactically valid variable name. -\subsubsection*{\ff \T{seterrormethod (newmethod)}} -\label{pdf-seterrormethod} -Sets the error handler \see{error}. -\verb|newmethod| must be a function or \nil, -in which case the error handler does nothing. -Returns the old error handler. - \subsubsection*{\ff \T{settagmethod (tag, event, newmethod)}} \Deffunc{settagmethod} This function sets a new tag method to the given pair \M{(tag, event)}. @@ -2930,7 +2923,7 @@ so any existing program that opens at least one standard library before calling Lua does not need to be modified. \item Function \verb|dostring| no longer accepts an optional second argument, -with a temporary error method. +with a temporary error handler. This facility is now provided by function \verb|call|. \item Function \verb|gsub| no longer accepts an optional fourth argument @@ -2951,8 +2944,10 @@ programs should use an explicit assignment instead, such as \end{itemize} +% restore underscore to usual meaning +\catcode`\_=8 + \newcommand{\indexentry}[2]{\item {#1} #2} -%\catcode`\_=12 \begin{theindex} \input{manual.id} \end{theindex} -- cgit v1.2.3-55-g6feb