From cc117253c83ec32d226a8f2226d5ca144804f873 Mon Sep 17 00:00:00 2001
From: Roberto Ierusalimschy <roberto@inf.puc-rio.br>
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

