no more refs, upvalues; lexical scoping;pseudo-indices

manual.tex

@@ -291,8 +291,8 @@ Statements are described in \See{stats}.
 A chunk may be stored in a file or in a string inside the host program.
 When a chunk is executed, first it is pre-compiled into bytecodes for
 a virtual machine,
-and then the compiled statements are executed in sequential order,
-by simulating the virtual machine.
+and then the compiled statements are executed
+by an interpreter for the virtual machine.
 All modifications a chunk effects on the global environment persist
 after the chunk ends.
 
@@ -311,15 +311,12 @@ This means that
 variables do not have types; only values do.
 Therefore, there are no type definitions in the language.
 All values carry their own type.
-Besides a type, all values also have a tag \see{tags}.
 
 There are six \Index{basic types} in Lua: \Def{nil}, \Def{number},
 \Def{string}, \Def{function}, \Def{userdata}, and \Def{table}.
 \emph{Nil} is the type of the value \nil,
 whose main property is to be different from any other value.
-\emph{Number} represents real
-%(double-precision floating-point)
-numbers.
+\emph{Number} represents real (double-precision floating-point) numbers.
 \emph{String} represents arrays of characters.
 \index{eight-bit clean}
 Lua is 8-bit clean,
@@ -365,9 +362,9 @@ In particular,
 because functions are first class values,
 table fields may contain functions.
 So, tables may also carry \emph{methods}.
-The form \verb|t:f(x)| is syntactic sugar for \verb|t.f(t,x)|,
-which calls the method \verb|f| from the table \verb|t| passing
-the table itself as the first parameter \see{func-def}.
+%The form \verb|t:f(x)| is syntactic sugar for \verb|t.f(t,x)|,
+%which calls the method \verb|f| from the table \verb|t| passing
+%the table itself as the first parameter \see{func-def}.
 
 Strings, tables, functions, and userdata values are \emph{objects}:
 variables do not actually \emph{contain} these values,
@@ -378,41 +375,9 @@ always manipulate references to these values, and do not imply any kind of copy.
 The library function \verb|type| returns a string describing the type
 of a given value \see{pdf-type}.
 
+\subsubsection{Tags}\label{tags}
 
-\subsection{\Index{Coercion}} \label{coercion}
-
-Lua provides automatic conversion between string and number values at run time.
-Any arithmetic operation applied to a string tries to convert
-that string to a number, following the usual rules.
-Conversely, whenever a number is used when a string is expected,
-the number is converted to a string, in a reasonable format.
-The format is chosen so that
-a conversion from number to string then back to number
-reproduces the original number \emph{exactly}.
-The conversion does not necessarily produces nice-looking text for some numbers.
-For complete control of how numbers are converted to strings,
-use the \verb|format| function \see{format}.
-
-
-\subsection{Variables}
-
-There are two kinds of variables in Lua:
-global variables
-and local variables.
-\Index{Global variables} do not need to be declared.
-Variables are assumed to be global unless explicitly declared local
-\see{localvar}.
-Before the first assignment, the value of a variable is \nil\ %
-(this default can be changed for global variables; see \See{tag-method}).
-
-An ordinary Lua table is used to keep all global names and values.
-This table can be accessed and changed with the \verb|globals| function
-\see{pdf-globals}.
-
-
-\subsection{Tags}\label{tags}
-
-Each type has a \emph{name},
+Each type is denoted both by a \emph{name},
 which is a string,
 and a \IndexEmph{tag},
 which is an integer.
@@ -425,7 +390,7 @@ with both type names and tags.
 The \verb|tag| function returns the tag of a given value \see{pdf-tag}.
 
 
-\subsection{User-defined Types}
+\subsubsection{User-defined Types}
 
 Lua programs can create new types,
 called \IndexEmph{user-defined types}.
@@ -446,6 +411,40 @@ The \verb|settype| function changes the type of a given object
 \see{pdf-settype}.
 
 
+\subsection{\Index{Coercion}} \label{coercion}
+
+Lua provides automatic conversion between string and number values at run time.
+Any arithmetic operation applied to a string tries to convert
+that string to a number, following the usual rules.
+Conversely, whenever a number is used when a string is expected,
+the number is converted to a string, in a reasonable format.
+The format is chosen so that
+a conversion from number to string then back to number
+reproduces the original number \emph{exactly}.
+The conversion does not necessarily produces nice-looking text for some numbers.
+For complete control of how numbers are converted to strings,
+use the \verb|format| function \see{format}.
+
+
+\subsection{Variables}
+
+There are two kinds of variables in Lua:
+global variables
+and local variables.
+\Index{Global variables} do not need to be declared.
+Variables are assumed to be global unless explicitly declared local
+\see{localvar}.
+Before the first assignment, the value of a variable is \nil\ %
+(this default can be changed for global variables; see \See{tag-method}).
+
+An ordinary Lua table is used to keep all global names and values.
+This table can be accessed and changed with the \verb|globals| function
+\see{pdf-globals}.
+
+\Index{Local variables} are lexically scoped.
+Therefore, local variables can be freely accessed by functions
+defined inside their scope \see{visibility}.
+
 \subsection{Garbage Collection}\label{GC}
 
 Lua does automatic memory management.
@@ -455,9 +454,8 @@ and freeing it when the objects are no longer needed.
 Lua manages memory automatically by running
 a \Index{garbage collector} from time to time
 and
-collecting all ``dead'' objects
-(essentially, all objects that are no longer accessible from Lua
-as the value of a global variable or table field).
+collecting all dead objects
+(all objects that are no longer accessible from Lua).
 All objects in Lua are subject to automatic management:
 tables, userdata, functions, and strings.
 
@@ -476,7 +474,7 @@ One number counts how many bytes of dynamic memory Lua is using,
 and the other is a threshold.
 When the number of bytes crosses the threshold,
 Lua runs the garbage collector,
-which reclaims the memory of all ``dead'' objects.
+which reclaims the memory of all dead objects.
 The byte counter is corrected,
 and then the threshold is reset to twice the value of the byte counter.
 
@@ -624,7 +622,7 @@ in Unix systems \see{lua-sa}.
 \subsection{Variables}\label{variables}
 
 Variables are places that store values.
-In Lua, variables are given by simple identifiers or by table fields.
+%In Lua, variables are given by simple identifiers or by table fields.
 
 A single name can denote a global variable, a local variable,
 or a formal parameter in a function
@@ -638,7 +636,7 @@ Square brackets are used to index a table:
 \produc{var}{exp \ter{[} exp \ter{]}}
 \end{Produc}%
 The first expression should result in a table value,
-from where the field given by the second expression gets the assigned value.
+and the second expression identifies the specific place inside that table.
 
 The syntax \verb|var.NAME| is just syntactic sugar for
 \verb|var["NAME"]|:
@@ -657,8 +655,6 @@ An access to a global variable \verb|x|
 is equivalent to a call \verb|getglobal("x")| and
 an access to an indexed variable \verb|t[i]| is equivalent to
 a call \verb|gettable_event(t,i)|.
-Of course,
-\verb|i| and \verb|val| can be complicated expressions.
 See \See{tag-method} for a complete description of these functions
 (\verb|setglobal| and \verb|getglobal| are in the basic library;
 \T{settable\_event} and \T{gettable\_event}
@@ -915,17 +911,12 @@ If present, an initial assignment has the same semantics
 of a multiple assignment \see{assignment}.
 Otherwise, all variables are initialized with \nil.
 
-The scope of local variables begins \emph{after}
-the declaration and lasts until the end of the block.
-Thus, the code
-\verb|local print=print|
-creates a local variable named \verb|print| whose
-initial value is that of the \emph{global} variable of the same name.
-
 A chunk is also a block \see{chunks},
 and so local variables can be declared outside any explicit block.
 Such local variables die when the chunk ends.
 
+Visibility rules for local variables are explained in \See{visibility}.
+
 
 \subsection{\Index{Expressions}}\label{expressions}
 
@@ -937,14 +928,12 @@ The basic expressions in Lua are the following:
 \produc{exp}{number}
 \produc{exp}{literal}
 \produc{exp}{var}
-\produc{exp}{upvalue}
 \produc{exp}{function}
 \produc{exp}{functioncall}
 \produc{exp}{tableconstructor}
 \end{Produc}%
 
-An expression enclosed in parentheses always results in only one value
-(the only expressions that can result in multiple values are function calls).
+An expression enclosed in parentheses always results in only one value.
 Thus,
 \verb|(f(x,y,z))| is always a single value,
 even if \verb|f| returns several values.
@@ -953,7 +942,6 @@ or \nil\ if \verb|f| does not return any values.)
 
 \emph{Numbers} and \emph{literal strings} are explained in \See{lexical};
 variables are explained in \See{variables};
-upvalues are explained in \See{upvalue};
 function definitions are explained in \See{func-def};
 function calls are explained in \See{functioncall};
 table constructors are explained in \See{tableconstructor}.
@@ -972,7 +960,7 @@ numbers \see{coercion},
 then all operations except exponentiation have the usual meaning;
 otherwise, an appropriate tag method is called \see{tag-method}.
 An exponentiation always calls a tag method.
-The standard mathematical library redefines this method for numbers,
+The standard mathematical library defines this method for numbers,
 giving the expected meaning to \Index{exponentiation}
 \see{mathlib}.
 
@@ -986,26 +974,13 @@ These operators return \nil\ as false and a value different from \nil\ as true.
 Equality (\verb|==|) first compares the type of its operands.
 If the types are different, then the result is \nil.
 Otherwise, the values of the operands are compared.
-Numbers are compared in the usual way.
-Strings, tables, userdata, and functions are compared \emph{by reference},
+Numbers and strings are compared in the usual way.
+Tables, userdata, and functions are compared \emph{by reference},
 that is,
 two tables are considered equal only if they are the \emph{same} table.
-In particular,
-equality is a constant-time operation and does not depend on the size of the
-strings or tables.
 
-Every time you create a new table (or string, userdata, or function),
+Every time you create a new table (or userdata, or function),
 this new value is different from any previously existing value.
-In particular,
-this is true for strings,
-even if a string is built in different ways.
-For example, all strings below are equal,
-that is, they are the \emph{same} string:
-\begin{verbatim}
-       "Lua" .. " 4.1"
-       "Lua " .. "4.1"
-       "Lua 4.1"
-\end{verbatim}
 
 \NOTE
 The conversion rules of \See{coercion}
@@ -1020,18 +995,9 @@ The operator \verb|~=| is exactly the negation of equality (\verb|==|).
 The order operators work as follows.
 If both arguments are numbers, then they are compared as such.
 Otherwise, if both arguments are strings,
-then their values are compared according to the current locale (see below).
+then their values are compared according to the current locale.
 Otherwise, the ``lt'' tag method is called \see{tag-method}.
 
-String comparison according to the current locale
-means that
-if you sort strings using \verb|<=|,
-then
-\emph{\'agua} will appear before \emph{book}
-and close to all other strings beginning with \emph{ag},
-even though \emph{\'a}~appears after \emph{b} in the usual ISO Latin encoding.
-\index{string comparison}
-
 
 \subsubsection{Logical Operators}
 The \Index{logical operators} in Lua are
@@ -1141,7 +1107,7 @@ is equivalent to
 If the last expression in the list is a function call,
 then all values returned by the call enter the list consecutively
 \see{functioncall}.
-To avoid this,
+If you want to avoid this,
 enclose the function call in parentheses.
 
 The form \emph{ffieldlist1} initializes other fields in a table:
@@ -1168,7 +1134,7 @@ An expression like \verb|{x = 1, y = 4}| is
 in fact syntactic sugar for \verb|{["x"] = 1, ["y"] = 4}|.
 
 Both forms may have an optional trailing comma
-(for convinence of machine-generated code),
+(for convenience of machine-generated code),
 and can be used in the same constructor separated by
 a semi-colon.
 For example, all forms below are correct.
@@ -1285,12 +1251,11 @@ whose value has type \emph{function}.
 When Lua pre-compiles a chunk,
 all its function bodies are pre-compiled too.
 Then, whenever Lua executes the function definition,
-its upvalues (if any) are fixed \see{upvalue},
-and the function is \emph{instantiated} (or \emph{closed}).
+the function is \emph{instantiated} (or \emph{closed}).
 This function instance (or \emph{closure})
 is the final value of the expression.
 Different instances of the same function
-may have different upvalues.
+may refer to different non-local variables \see{visibility}.
 
 Parameters act as local variables,
 initialized with the argument values:
@@ -1350,62 +1315,61 @@ is syntactic sugar for
 \begin{verbatim}
        t.a.b.c.f = function (self, ...) ... end
 \end{verbatim}
-Note that the function gets an extra formal parameter called \verb|self|.
-
-
-\subsection{Visibility and Upvalues} \label{upvalue}
-\index{visibility}\index{upvalues}
-
-A function body may refer to its own local variables
-(which include its parameters) and to global variables,
-as long as they are not \emph{shadowed} by local
-variables with the same name from enclosing functions.
-A function \emph{cannot} access a local
-variable from an enclosing function,
-since such variables may no longer exist when the function is called.
-However, a function may access the \emph{value} of a local variable
-from an enclosing function, using \emph{upvalues},
-whose syntax is
-\begin{Produc}
-\produc{upvalue}{\ter{\%} name}
-\end{Produc}%
 
-An upvalue is somewhat similar to a variable expression,
-but whose value is \emph{frozen} when the function in which it
-appears is instantiated.
-The name used in an upvalue may be the name of any variable visible
-at the point where the function is defined,
-that is,
-global variables and local variables
-from the \emph{immediately enclosing} function.
 
-Note that when the upvalue is a table,
-only the \emph{reference} to that table
-(which is the value of the upvalue) is frozen;
-the table contents can be changed at will.
-Using table values as upvalues is a technique for having
-writable but private state attached to functions.
+\subsection{Visibility Rules} \label{visibility}
+\index{visibility}
 
-Here are some examples:
+Lua is a lexically scoped language.
+The scope of local variables begins at the first statement \emph{after}
+their declaration and lasts until the end of the innermost block that
+includes the declaration.
+For instance:
 \begin{verbatim}
-       a,b,c = 1,2,3   -- global variables
-       local d
-       function f (x)
-         local b = {}  -- x and b are local to f; b shadows the global b
-         local g = function (a)
-           local y     -- a and y are local to g
-           p = a       -- OK, access local `a'
-           p = c       -- OK, access global `c'
-           p = b       -- ERROR: cannot access a variable in outer function
-           p = %b      -- OK, access frozen value of `b' (local to `f')
-           %b = 3      -- ERROR: cannot change an upvalue
-           %b.x = 3    -- OK, change the table contents
-           p = %c      -- OK, access frozen value of global `c'
-           p = %y      -- ERROR: `y' is not visible where `g' is defined
-           p = %d      -- ERROR: `d' is not visible where `g' is defined
-         end           -- g
-       end             -- f
+  x = 10                -- global variable
+  do                    -- new block
+    local x = x         -- new `x', with value 10
+    print(x)            --> 10
+    x = x+1
+    do                  -- another block
+      local x = x+1     -- another x
+      print(x)          --> 12
+    end
+    print(x)            --> 11
+  end
+  print(x)              --> 10  (the global one)
 \end{verbatim}
+Notice that, in a declaration like \verb|local x = x|,
+the new \verb|x| being declared is not in scope yet,
+so the second \verb|x| refers to the ``outside'' variable.
+
+Because of this \Index{lexical scoping} rules,
+local variables can be freely accessed by functions
+defined inside their scope.
+For instance:
+\begin{verbatim}
+  local counter = 0
+  function inc (x) 
+    counter = counter + x
+    return counter
+  end
+\end{verbatim}
+
+Notice that each execution of a \rwd{local} statement
+``creates'' new local variables.
+Consider the following example:
+\begin{verbatim}
+  a = {}
+  local x = 20
+  for i=1,10 do
+    local y = 0
+    a[i] = function () y=y+1; return x+y end
+  end
+\end{verbatim}
+In that code,
+each function uses a different \verb|y| variable,
+while all of them share the same \verb|x|.
+
 
 
 \subsection{Error Handling} \label{error}
@@ -1437,9 +1401,9 @@ The default definition for
 this function calls \verb|_ALERT|, \DefLIB{_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}
+and uses the debug interface \see{debugI}
 to print some extra information,
-such as a call stack traceback.
+such as a call-stack traceback.
 
 Lua code can explicitly generate an error by calling the
 function \verb|error| \see{pdf-error}.
@@ -1458,7 +1422,7 @@ Lua selects the tag method called for any specific event
 according to the types of the values involved
 in the event \see{TypesSec}.
 The function \IndexLIB{settagmethod} changes the tag method
-associated with a given pair (\M{type}, \M{event}).
+associated with a given (\M{type}, \M{event}) pair.
 The first parameter to \verb|settagmethod| is the type
 (represented by its name or tag),
 the second parameter is the event name (a string; see below),
@@ -1466,7 +1430,7 @@ and the third parameter is the new method (a function),
 or \nil\ to restore the default behavior for the pair.
 A companion function \IndexLIB{gettagmethod}
 receives a type and an event name and returns the
-current method associated with the pair.
+current method associated to them.
 
 Tag methods are called in the following events,
 identified by the given names.
@@ -1850,11 +1814,11 @@ For convenience,
 most query operations in the API do not follow a strict stack discipline.
 Instead, they can refer to any element in the stack by using an \emph{index}:
 A positive index represents an \emph{absolute} stack position
-(starting at~1, not 0 as in C);
+(starting at~1);
 a negative index represents an \emph{offset} from the top of the stack.
 More specifically, if the stack has \M{n} elements,
 then index~1 represents the first element
-(that is, the first element pushed onto the stack),
+(that is, the element that was pushed onto the stack first),
 and
 index~\M{n} represents the last element;
 index~\Math{-1} also represents the last element
@@ -1886,8 +1850,8 @@ Whenever Lua calls C, \DefAPI{LUA_MINSTACK}
 it ensures that
 at least \verb|LUA_MINSTACK| positions are still available.
 \verb|LUA_MINSTACK| is defined in \verb|lua.h| and is at least~16,
-so that usually you have to worry about stack space only
-when your code has loops pushing elements onto the stack.
+so that usually you do not have to worry about stack space
+unless your code has loops pushing elements onto the stack.
 
 Most query functions accept as indices any value inside the
 available stack space.
@@ -1899,6 +1863,15 @@ as follows:
 \end{verbatim}
 Note that 0 is not an acceptable index.
 
+Unless otherwise noticed,
+any function that accepts valid indices can also be called with
+\Index{pseudo-indices},
+which represent some Lua values that are accessible to the C~code
+but are not in the stack.
+
+Pseudo-indices are used to access the registry
+and the upvalues of a C function \see{c-closure}.
+
 \subsection{Stack Manipulation}
 The API offers the following functions for basic stack manipulation:
 \begin{verbatim}
@@ -1930,6 +1903,8 @@ shifting down the elements above that position to fill the gap.
 \verb|lua_insert| moves the top element into the given position,
 shifting up the elements above that position to open space.
 These functions accept only valid indices.
+(Obviously, you cannot call \verb|lua_remove| or \verb|lua_insert| with
+pseudo-indices, as they do not represent a stack position.)
 
 As an example, if the stack starts as \verb|10 20 30 40 50*|
 (from bottom to top; the \verb|*| marks the top),
@@ -1946,6 +1921,7 @@ then
 \end{verbatim}
 
 
+
 \subsection{Querying the Stack}
 
 To check the type of a stack element,
@@ -2036,8 +2012,10 @@ otherwise, the function returns \verb|NULL|.
 If the value is a number,
 then \verb|lua_tostring| also
 \emph{changes the actual value in the stack to a string}.
-This change confuses \verb|lua_next| when \verb|lua_tostring| is applied to keys.
-\verb|lua_tostring| returns a fully aligned pointer to a string inside the Lua environment.
+(This change confuses \verb|lua_next|
+when \verb|lua_tostring| is applied to keys.)
+\verb|lua_tostring| returns a fully aligned pointer
+to a string inside the Lua environment.
 This string always has a zero (\verb|'\0'|)
 after its last character (as in~C),
 but may contain other zeros in its body.
@@ -2047,7 +2025,7 @@ Because Lua has garbage collection,
 there is no guarantee that the pointer returned by \verb|lua_tostring|
 will be valid after the corresponding value is removed from the stack.
 So, if you need the string after the current function returns,
-then you should duplicate it (or lock it; see \See{lock}).
+then you should duplicate it (or put it into the registry \see{registry}).
 
 \verb|lua_tocfunction| converts a value in the stack to a C~function.
 This value must be a C~function;
@@ -2078,7 +2056,7 @@ These functions receive a C~value,
 convert it to a corresponding Lua value,
 and push the result onto the stack.
 In particular, \verb|lua_pushlstring| and \verb|lua_pushstring|
-make an \emph{internal copy} of the given string.
+make an internal copy of the given string.
 \verb|lua_pushstring| can only be used to push proper C~strings
 (that is, strings that end with a zero and do not contain embedded zeros);
 otherwise, you should use the more general \verb|lua_pushlstring|,
@@ -2141,7 +2119,7 @@ By default, all userdata are created with a standard tag,
 
 When Lua collects a userdata created by \verb|lua_newuserdata|,
 it automatically frees its corresponding memory.
-On the other hand, Lua never uses pointers in
+On the other hand, Lua never accesses pointers in
 userdata created with \verb|lua_newuserdatabox|;
 it is up to you to free any associated memory,
 setting a garbage-collection tag method, for instance.
@@ -2392,7 +2370,8 @@ A typical traversal looks like this:
 \end{verbatim}
 
 NOTE:
-Do not call \verb|lua_tostring| on a key,
+While traversing a table,
+do not call \verb|lua_tostring| on a key,
 unless you know the key is actually a string.
 Recall that \verb|lua_tostring| \emph{changes} the value at the given index;
 this confuses \verb|lua_next|.
@@ -2406,7 +2385,7 @@ The following functions control the weak mode of a table:
 Both functions operate over the table at the top of the stack.
 Modes are described as bit sets, so that
 \verb|LUA_WEAK_KEY| means weak keys,
-\verb|LUA_WEAK_VALUE| means weak values,
+\verb|LUA_WEAK_VALUE| means weak values, the combination
 \verb"LUA_WEAK_KEY | LUA_WEAK_VALUE" means both,
 and zero means none.
 
@@ -2609,93 +2588,51 @@ by calling
        lua_register(L, "average", foo);
 \end{verbatim}
 
-\subsection{Defining C Closures}
+\subsection{Defining C Closures} \label{c-closure}
 
 When a C~function is created,
-it is possible to associate some \emph{upvalues} to it
-\see{upvalue},
+it is possible to associate some values to it,
 thus creating a \IndexEmph{C~closure};
-these values are passed to the function whenever it is called,
-as ordinary arguments.
-To associate upvalues to a C~function,
+these values are then accessible to the function whenever it is called.
+To associate values to a C~function,
 first these values should be pushed onto the stack
-(when there are multiple upvalues,
-the first upvalue is pushed first).
+(when there are multiple values, the first value is pushed first).
 Then the function
 \begin{verbatim}
        void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
 \end{verbatim}
 \DefAPI{lua_pushcclosure}
 is used to push the C~function onto the stack,
-with the argument \verb|n| telling how many upvalues should be
+with the argument \verb|n| telling how many values should be
 associated with the function
-(these upvalues are popped from the stack);
+(\verb|lua_pushcclosure| also pops these values from the stack);
 in fact, the macro \verb|lua_pushcfunction| is defined as
 \verb|lua_pushcclosure| with \verb|n| set to 0.
+
 Then, whenever the C~function is called,
-these upvalues are inserted as the \emph{last} arguments to the function,
-after the actual arguments provided in the call.
-This makes it easy to get the upvalues without knowing how many arguments
-the function received (recall that functions in Lua can receive any number of
-arguments): The \M{i}-th upvalue is in the stack at index \Math{i-(n+1)},
-where \M{n} is the number of upvalues.
-(A C~function that uses upvalues must know beforehand how many it expects.)
+those values are located at specific pseudo-indices.
+Those pseudo-indices are produced by a macro \IndexAPI{lua_upvalueindex}.
+The first value associated with a function is at position
+\verb|lua_upvalueindex(1)|, and so on.
 
 For examples of C~functions and closures, see files
 \verb|lbaselib.c|, \verb|liolib.c|, \verb|lmathlib.c|, and \verb|lstrlib.c|
 in the official Lua distribution.
 
-\subsection{References to Lua Values} \label{lock}
 
-If the C~code needs to keep a Lua value
-outside the life span of a C~function,
-then it must create a \Def{reference} to the value.
-The functions to manipulate references are the following:
-\begin{verbatim}
-       int   lua_ref    (lua_State *L, int lock);
-       int   lua_getref (lua_State *L, int ref);
-       void  lua_unref  (lua_State *L, int ref);
-\end{verbatim}
-\DefAPI{lua_ref}\DefAPI{lua_getref}\DefAPI{lua_unref}
-
-\verb|lua_ref| pops a value from
-the stack, creates a reference to it,
-and returns this reference.
-For a \nil\ value,
-the reference is always \verb|LUA_REFNIL|.\DefAPI{LUA_REFNIL}
-%% TODO: why LUA_REFNIL? pode-se chamar lua_getref(L,LUA_REFNIL)?
-(\verb|lua.h| also defines a constant \verb|LUA_NOREF| \DefAPI{LUA_NOREF}
-that
-is different from any valid reference.)
-%% TODO: give example of use of LUA_NOREF
-If \verb|lock| is not zero, then the object is \emph{locked}:
-this means the object will not be garbage collected.
-\emph{Unlocked references may be garbage collected}.
-
-Whenever the referenced object is needed in~C,
-a call to \verb|lua_getref|
-pushes that object onto the stack;
-if the object has been collected,
-\verb|lua_getref| returns 0 (and does not push anything).
-
-When a reference is no longer needed,
-it should be released with a call to \verb|lua_unref|.
-
-
-\subsubsection*{Registry}
-%% TODO: nao precisa de secao propria? explicar melhor o uso.
-
-When Lua starts, it registers a table at position
-\IndexAPI{LUA_REFREGISTRY}.
-It can be accessed through the macro
-\begin{verbatim}
-       #define lua_getregistry(L)      lua_getref(L, LUA_REFREGISTRY)
-\end{verbatim}
-\DefAPI{lua_getregistry}
-This table can be used by C~libraries as a general registry mechanism.
+\subsubsection*{Registry} \label{registry}
+
+Lua provides a pre-defined table that can be used by any C~code to
+store whatever Lua value it needs to store,
+especially if the C~code needs to keep that Lua value
+outside the life span of a C~function.
+This table is always located at pseudo-index
+\IndexAPI{LUA_REGISTRYINDEX}.
 Any C~library can store data into this table,
 as long as it chooses a key different from other libraries.
-
+The integer keys in the registry are used by the reference mechanism,
+implemented by the auxiliar library,
+and therefore should not be used by other purposes.
 
 
 %------------------------------------------------------------------------------
@@ -2823,7 +2760,7 @@ If the function is a global variable,
 \verb|namewhat| is \verb|"global"|;
 if the function is a tag method,
 \verb|namewhat| is \verb|"tag-method"|;
-otherwise, \verb|namewhat| is \verb|""| (the empty string).
+otherwise, it is \verb|""| (the empty string).
 
 \item[nups]
 Number of upvalues of the function.
@@ -2899,7 +2836,7 @@ set their corresponding hooks and return their previous values.
 
 The call hook is called whenever the
 interpreter enters or leaves a function.
-The \verb|event| field of \verb|ar| has the strings \verb|"call"|
+The \verb|event| field of \verb|ar| has the string \verb|"call"|
 or \verb|"return"|.
 This \verb|ar| can then be used in calls to \verb|lua_getinfo|,
 \verb|lua_getlocal|, and \verb|lua_setlocal|
@@ -2909,7 +2846,7 @@ local variables.
 The line hook is called every time the interpreter changes
 the line of code it is executing.
 The \verb|event| field of \verb|ar| has the string \verb|"line"|,
-and the \verb|currentline| field has the line number.
+and the \verb|currentline| field has the new line number.
 Again, you can use this \verb|ar| in other calls to the debug API.
 
 While Lua is running a hook, it disables other calls to hooks.
@@ -3013,11 +2950,6 @@ then Lua immediately runs the garbage collector \see{GC}.
 If \verb|limit| is absent, it defaults to zero
 (thus forcing a garbage-collection cycle).
 
-\subsubsection*{\ff \T{copytagmethods (tagto, tagfrom)}}
-\DefLIB{copytagmethods}
-Copies all tag methods from one tag to another;
-returns \verb|tagto|.
-
 \subsubsection*{\ff \T{dofile (filename)}}\DefLIB{dofile}
 Receives a file name,
 opens the named file, and executes its contents as a Lua chunk.
@@ -3044,13 +2976,13 @@ The optional parameter \verb|chunkname|
 is the ``name of the chunk'',
 used in error messages and debug information.
 
-\subsubsection*{\ff \T{error (message)}}\DefLIB{error}\label{pdf-error}
+\subsubsection*{\ff \T{error ([message])}}\DefLIB{error}\label{pdf-error}
 Calls the error handler \see{error} and then terminates
 the last protected function called
 (in~C: \verb|lua_dofile|, \verb|lua_dostring|,
 \verb|lua_dobuffer|, or \verb|lua_callfunction|;
 in Lua: \verb|dofile|, \verb|dostring|, or \verb|call| in protected mode).
-If \verb|message| is \nil, then the error handler is not called.
+If \verb|message| is absent, the error handler is not called.
 Function \verb|error| never returns.
 
 \subsubsection*{\ff \T{foreach (table, func)}}\DefLIB{foreach}
@@ -3522,11 +3454,11 @@ Here are some examples:
    --> x="4+5 = 9"
 
    local t = {name="Lua", version="4.1"}
-   x = gsub("$name - $version", "%$(%w+)", function (v) return %t[v] end)
+   x = gsub("$name - $version", "%$(%w+)", function (v) return t[v] end)
    --> x="Lua - 4.1"
 
-   local t = {n=0}
-   gsub("first second word", "(%w+)", function (w) tinsert(%t, w) end)
+   local t = {}
+   gsub("first second word", "(%w+)", function (w) tinsert(t, w) end)
    --> t={"first", "second", "word"; n=3}
 \end{verbatim}