diff --git a/Makefile b/Makefile index 7fa91c858bb1..119110d2f010 100644 --- a/Makefile +++ b/Makefile @@ -46,7 +46,7 @@ TO_MAN= lua.1 luac.1 # Lua version and release. V= 5.3 -R= $V.0 +R= $V.4 # Targets start here. all: $(PLAT) diff --git a/README b/README index 32fb68e77e31..0b31908a06cb 100644 --- a/README +++ b/README @@ -1,5 +1,5 @@ -This is Lua 5.3.0, released on 06 Jan 2015. +This is Lua 5.3.4, released on 12 Jan 2017. For installation instructions, license details, and further information about Lua, see doc/readme.html. diff --git a/doc/contents.html b/doc/contents.html index e59e4215eee3..445556f96415 100644 --- a/doc/contents.html +++ b/doc/contents.html @@ -3,43 +3,42 @@ Lua 5.3 Reference Manual - contents + - -

- +Lua Lua 5.3 Reference Manual

The reference manual is the official definition of the Lua language. +
For a complete introduction to Lua programming, see the book Programming in Lua. -

+

start · contents · index -
+· +other versions +
+ +

-Copyright © 2015 Lua.org, PUC-Rio. +Copyright © 2015–2017 Lua.org, PUC-Rio. Freely available under the terms of the Lua license.

Contents

- @@ -4219,7 +4319,7 @@ Pushes a boolean value with value b onto the stack.

lua_pushcclosure

-[-n, +1, e] +[-n, +1, m] 

void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);

@@ -4247,7 +4347,7 @@ The maximum value for n is 255.

When n is zero, -this function creates a light C function, +this function creates a light C function, which is just a pointer to the C function. In that case, it never raises a memory error. @@ -4261,26 +4361,17 @@ In that case, it never raises a memory error.

Pushes a C function onto the stack. -This function receives a pointer to a C function +This function receives a pointer to a C function and pushes onto the stack a Lua value of type function that, when called, invokes the corresponding C function.

-Any function to be registered in Lua must +Any function to be callable by Lua must follow the correct protocol to receive its parameters and return its results (see lua_CFunction). -

-lua_pushcfunction is defined as a macro: - -

-     #define lua_pushcfunction(L,f)  lua_pushcclosure(L,f,0)
-

-Note that f is used twice. - - @@ -4309,7 +4400,7 @@ The conversion specifiers can only be '%%' (inserts the character '%'), '%s' (inserts a zero-terminated string, with no size restrictions), '%f' (inserts a lua_Number), -'%L' (inserts a lua_Integer), +'%I' (inserts a lua_Integer), '%p' (inserts a pointer as a hexadecimal numeral), '%d' (inserts an int), '%c' (inserts an int as a one-byte character), and @@ -4318,6 +4409,12 @@ The conversion specifiers can only be +

+Unlike other push functions, +this function checks for the stack space it needs, +including the slot for its result. + + @@ -4365,20 +4462,19 @@ light userdata with the same C address.

lua_pushliteral

-[-0, +1, e] +[-0, +1, m] 

const char *lua_pushliteral (lua_State *L, const char *s);

-This macro is equivalent to lua_pushlstring, -but can be used only when s is a literal string. -It automatically provides the string length. +This macro is equivalent to lua_pushstring, +but should be used only when s is a literal string.

lua_pushlstring

-[-0, +1, e] +[-0, +1, m] 

const char *lua_pushlstring (lua_State *L, const char *s, size_t len);

@@ -4421,7 +4517,7 @@ Pushes a float with value n onto the stack.

lua_pushstring

-[-0, +1, e] +[-0, +1, m] 

const char *lua_pushstring (lua_State *L, const char *s);

@@ -4468,7 +4564,7 @@ onto the stack.

lua_pushvfstring

-[-0, +1, e] +[-0, +1, m] 

const char *lua_pushvfstring (lua_State *L,
                               const char *fmt,
                               va_list argp);
@@ -4488,7 +4584,7 @@ instead of a variable number of arguments.

Returns 1 if the two values in indices index1 and index2 are primitively equal -(that is, without calling metamethods). +(that is, without calling the __eq metamethod). Otherwise returns 0. Also returns 0 if any of the indices are not valid. @@ -4515,8 +4611,8 @@ Similar to lua_gettable, but does a raw

Pushes onto the stack the value t[n], where t is the table at the given index. -The access is raw; -that is, it does not invoke metamethods. +The access is raw, +that is, it does not invoke the __index metamethod.

@@ -4535,7 +4631,7 @@ Pushes onto the stack the value t[k], where t is the table at the given index and k is the pointer p represented as a light userdata. The access is raw; -that is, it does not invoke metamethods. +that is, it does not invoke the __index metamethod.

@@ -4563,7 +4659,7 @@ for other values, it is 0.

lua_rawset

-[-2, +0, e] +[-2, +0, m] 

void lua_rawset (lua_State *L, int index);

@@ -4575,7 +4671,7 @@ Similar to lua_settable, but does a raw

lua_rawseti

-[-1, +0, e] +[-1, +0, m] 

void lua_rawseti (lua_State *L, int index, lua_Integer i);

@@ -4586,28 +4682,28 @@ and v is the value at the top of the stack.

This function pops the value from the stack. -The assignment is raw; -that is, it does not invoke metamethods. +The assignment is raw, +that is, it does not invoke the __newindex metamethod.

lua_rawsetp

-[-1, +0, e] +[-1, +0, m] 

void lua_rawsetp (lua_State *L, int index, const void *p);

-Does the equivalent of t[k] = v, +Does the equivalent of t[p] = v, where t is the table at the given index, -k is the pointer p represented as a light userdata, +p is encoded as a light userdata, and v is the value at the top of the stack.

This function pops the value from the stack. -The assignment is raw; -that is, it does not invoke metamethods. +The assignment is raw, +that is, it does not invoke __newindex metamethod. @@ -4640,7 +4736,7 @@ The reader function may return pieces of any size greater than zero. 

void lua_register (lua_State *L, const char *name, lua_CFunction f);

-Sets the C function f as the new value of global name. +Sets the C function f as the new value of global name. It is defined as a macro: 

@@ -4672,7 +4768,7 @@ because a pseudo-index is not an actual stack position.
 

 Moves the top element into the given valid index
 without shifting any element
-(therefore replacing the value at the given index),
+(therefore replacing the value at that given index),
 and then pops the top element.
 
 
@@ -4684,7 +4780,7 @@ and then pops the top element.
 
int lua_resume (lua_State *L, lua_State *from, int nargs);

 
 

-Starts and resumes a coroutine in a given thread.
+Starts and resumes a coroutine in the given thread L.
 
 
 

@@ -4706,7 +4802,7 @@ or an error code in case of errors (see lua_pcall
@@ -4731,12 +4827,16 @@ this parameter can be NULL.
 
void lua_rotate (lua_State *L, int idx, int n);

 
 

-Rotates the stack elements from idx to the top n positions
-in the direction of the top, for a positive n,
+Rotates the stack elements between the valid index idx
+and the top of the stack.
+The elements are rotated n positions in the direction of the top,
+for a positive n,
 or -n positions in the direction of the bottom,
 for a negative n.
 The absolute value of n must not be greater than the size
 of the slice being rotated.
+This function cannot be called with a pseudo-index,
+because a pseudo-index is not an actual stack position.
 
 
 
@@ -4857,7 +4957,7 @@ If index is 0, then all stack elements are removed.
 
 

 Pops a value from the stack and sets it as
-the new value associated to the userdata at the given index.
+the new value associated to the full userdata at the given index.
 
 
 
@@ -4993,13 +5093,13 @@ indicates whether the operation succeeded.
 
 
 
lua_tolstring

-[-0, +0, e]
+[-0, +0, m]
 
const char *lua_tolstring (lua_State *L, int index, size_t *len);

 
 

 Converts the Lua value at the given index to a C string.
 If len is not NULL,
-it also sets *len with the string length.
+it sets *len with the string length.
 The Lua value must be a string or a number;
 otherwise, the function returns NULL.
 If the value is a number,
@@ -5010,7 +5110,7 @@ when lua_tolstring is applied to keys during a table traversal.)
 
 
 

-lua_tolstring returns a fully aligned pointer
+lua_tolstring returns a pointer
 to a string inside the Lua state.
 This string always has a zero ('\0')
 after its last character (as in C),
@@ -5072,14 +5172,14 @@ There is no way to convert the pointer back to its original value.
 
 
 

-Typically this function is used only for debug information.
+Typically this function is used only for hashing and debug information.
 
 
 
 
 
 
lua_tostring

-[-0, +0, e]
+[-0, +0, m]
 
const char *lua_tostring (lua_State *L, int index);

 
 

@@ -5127,7 +5227,7 @@ Returns the type of the value in the given valid index,
 or LUA_TNONE for a non-valid (but acceptable) index.
 The types returned by lua_type are coded by the following constants
 defined in lua.h:
-LUA_TNIL,
+LUA_TNIL (0),
 LUA_TNUMBER,
 LUA_TBOOLEAN,
 LUA_TSTRING,
@@ -5177,11 +5277,13 @@ the running function (see §4.4).
 
 
 
lua_version

-[-0, +0, v]
+[-0, +0, –]
 
const lua_Number *lua_version (lua_State *L);

 
 

-Returns the address of the version number stored in the Lua core.
+Returns the address of the version number
+(a C static variable)
+stored in the Lua core.
 When called with a valid lua_State,
 returns the address of the version used to create that state.
 When called with NULL,
@@ -5269,7 +5371,7 @@ that will be passed as results to lua_resume<
 

 When the coroutine is resumed again,
 Lua calls the given continuation function k to continue
-the execution of the C function that yielded (see §4.7).
+the execution of the C function that yielded (see §4.7).
 This continuation function receives the same stack
 from the previous function,
 with the n results removed and
@@ -5285,9 +5387,9 @@ when the coroutine eventually resumes,
 it continues executing the continuation function.
 However, there is one special case,
 which is when this function is called
-from inside a line hook (see §4.9).
+from inside a line or a count hook (see §4.9).
 In that case, lua_yieldk should be called with no continuation
-(probably in the form of lua_yield),
+(probably in the form of lua_yield) and no results,
 and the hook should return immediately after the call.
 Lua will yield and,
 when the coroutine resumes again,
@@ -5618,24 +5720,26 @@ it returns 0.
 
const char *lua_getupvalue (lua_State *L, int funcindex, int n);

 
 

-Gets information about a closure's upvalue.
-(For Lua functions,
-upvalues are the external local variables that the function uses,
-and that are consequently included in its closure.)
-lua_getupvalue gets the index n of an upvalue,
-pushes the upvalue's value onto the stack,
+Gets information about the n-th upvalue
+of the closure at index funcindex.
+It pushes the upvalue's value onto the stack
 and returns its name.
-funcindex points to the closure in the stack.
-(Upvalues have no particular order,
-as they are active through the whole function.
-So, they are numbered in an arbitrary order.)
+Returns NULL (and pushes nothing)
+when the index n is greater than the number of upvalues.
 
 
 

-Returns NULL (and pushes nothing)
-when the index is greater than the number of upvalues.
 For C functions, this function uses the empty string ""
 as a name for all upvalues.
+(For Lua functions,
+upvalues are the external local variables that the function uses,
+and that are consequently included in its closure.)
+
+
+

+Upvalues have no particular order,
+as they are active through the whole function.
+They are numbered in an arbitrary order.
 
 
 
@@ -5680,10 +5784,10 @@ that is, they cannot call lua_yieldk,
 
 

 Hook functions can yield under the following conditions:
-Only count and line events can yield
-and they cannot yield any value;
-to yield a hook function must finish its execution
-calling lua_yield with nresults equal to zero.
+Only count and line events can yield;
+to yield, a hook function must finish its execution
+calling lua_yield with nresults equal to zero
+(that is, with no values).
 
 
 
@@ -5700,7 +5804,7 @@ Sets the debugging hook function.
 

 Argument f is the hook function.
 mask specifies on which events the hook will be called:
-it is formed by a bitwise or of the constants
+it is formed by a bitwise OR of the constants
 LUA_MASKCALL,
 LUA_MASKRET,
 LUA_MASKLINE,
@@ -5748,9 +5852,7 @@ A hook is disabled by setting mask to zero.
 
 

 Sets the value of a local variable of a given activation record.
-Parameters ar and n are as in lua_getlocal
-(see lua_getlocal).
-lua_setlocal assigns the value at the top of the stack
+It assigns the value at the top of the stack
 to the variable and returns its name.
 It also pops the value from the stack.
 
@@ -5761,6 +5863,10 @@ when the index is greater than
 the number of active local variables.
 
 
+

+Parameters ar and n are as in function lua_getlocal.
+
+
 
 
 
@@ -5773,13 +5879,15 @@ Sets the value of a closure's upvalue.
 It assigns the value at the top of the stack
 to the upvalue and returns its name.
 It also pops the value from the stack.
-Parameters funcindex and n are as in the lua_getupvalue
-(see lua_getupvalue).
 
 
 

 Returns NULL (and pops nothing)
-when the index is greater than the number of upvalues.
+when the index n is greater than the number of upvalues.
+
+
+

+Parameters funcindex and n are as in function lua_getupvalue.
 
 
 
@@ -5792,9 +5900,6 @@ when the index is greater than the number of upvalues.
 

 Returns a unique identifier for the upvalue numbered n
 from the closure at index funcindex.
-Parameters funcindex and n are as in the lua_getupvalue
-(see lua_getupvalue)
-(but n cannot be greater than the number of upvalues).
 
 
 

@@ -5805,6 +5910,11 @@ Lua closures that share an upvalue
 will return identical ids for those upvalue indices.
 
 
+

+Parameters funcindex and n are as in function lua_getupvalue,
+but n cannot be greater than the number of upvalues.
+
+
 
 
 
@@ -5880,7 +5990,7 @@ in alphabetical order.
 
 
 
luaL_addchar

-[-?, +?, e]
+[-?, +?, m]
 
void luaL_addchar (luaL_Buffer *B, char c);

 
 

@@ -5892,7 +6002,7 @@ Adds the byte c to the buffer B
 
 
 
luaL_addlstring

-[-?, +?, e]
+[-?, +?, m]
 
void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);

 
 

@@ -5906,7 +6016,7 @@ The string can contain embedded zeros.
 
 
 
luaL_addsize

-[-?, +?, e]
+[-?, +?, –]
 
void luaL_addsize (luaL_Buffer *B, size_t n);

 
 

@@ -5919,7 +6029,7 @@ buffer area (see luaL_prepbuffer).
 
 
 
luaL_addstring

-[-?, +?, e]
+[-?, +?, m]
 
void luaL_addstring (luaL_Buffer *B, const char *s);

 
 

@@ -5932,7 +6042,7 @@ to the buffer B
 
 
 
luaL_addvalue

-[-1, +?, e]
+[-1, +?, m]
 
void luaL_addvalue (luaL_Buffer *B);

 
 

@@ -5972,7 +6082,7 @@ If it is not, raises an error with a standard message (see luaL_buffinitsize

-[-?, +?, e]
+[-?, +?, m]
 
char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);

 
 

@@ -6246,7 +6356,7 @@ returns the userdata address (see lua_touserdata
 
 
 
luaL_checkversion

-[-0, +0, –]
+[-0, +0, v]
 
void luaL_checkversion (lua_State *L);

 
 

@@ -6321,7 +6431,7 @@ as return luaL_error(args).
 
 
 
luaL_execresult

-[-0, +3, e]
+[-0, +3, m]
 
int luaL_execresult (lua_State *L, int stat);

 
 

@@ -6334,7 +6444,7 @@ process-related functions in the standard library
 
 
 
luaL_fileresult

-[-0, +(1|3), e]
+[-0, +(1|3), m]
 
int luaL_fileresult (lua_State *L, int stat, const char *fname);

 
 

@@ -6347,7 +6457,7 @@ file-related functions in the standard library
 
 
 
luaL_getmetafield

-[-0, +(0|1), e]
+[-0, +(0|1), m]
 
int luaL_getmetafield (lua_State *L, int obj, const char *e);

 
 

@@ -6362,14 +6472,14 @@ pushes nothing and returns LUA_TNIL.
 
 
 
luaL_getmetatable

-[-0, +1, –]
+[-0, +1, m]
 
int luaL_getmetatable (lua_State *L, const char *tname);

 
 

 Pushes onto the stack the metatable associated with name tname
-in the registry (see luaL_newmetatable).
-If there is no metatable associated with tname,
-returns false and pushes nil.
+in the registry (see luaL_newmetatable)
+(nil if there is no metatable associated with that name).
+Returns the type of the pushed value.
 
 
 
@@ -6392,7 +6502,7 @@ and false if it creates a new table.
 
 
 
luaL_gsub

-[-0, +1, e]
+[-0, +1, m]
 
const char *luaL_gsub (lua_State *L,
                        const char *s,
                        const char *p,
@@ -6462,7 +6572,7 @@ The string mode works as in function lua_
 
 
 
luaL_loadfile

-[-0, +1, e]
+[-0, +1, m]
 
int luaL_loadfile (lua_State *L, const char *filename);

 
 

@@ -6473,7 +6583,7 @@ Equivalent to luaL_loadfilex with 
luaL_loadfilex

-[-0, +1, e]
+[-0, +1, m]
 
int luaL_loadfilex (lua_State *L, const char *filename,
                                             const char *mode);

 
@@ -6493,7 +6603,8 @@ The string mode works as in function lua_
 

 This function returns the same results as lua_load,
 but it has an extra error code LUA_ERRFILE
-if it cannot open/read the file or the file has a wrong mode.
+for file-related errors
+(e.g., it cannot open or read the file).
 
 
 

@@ -6527,7 +6638,7 @@ it does not run it.
 
 
 
luaL_newlib

-[-0, +1, e]
+[-0, +1, m]
 
void luaL_newlib (lua_State *L, const luaL_Reg l[]);

 
 

@@ -6549,7 +6660,7 @@ not a pointer to it.
 
 
 
luaL_newlibtable

-[-0, +1, e]
+[-0, +1, m]
 
void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);

 
 

@@ -6570,7 +6681,7 @@ not a pointer to it.
 
 
 
luaL_newmetatable

-[-0, +1, e]
+[-0, +1, m]
 
int luaL_newmetatable (lua_State *L, const char *tname);

 
 

@@ -6624,6 +6735,27 @@ Opens all standard Lua libraries into the given state.
 
 
 
+
luaL_opt

+[-0, +0, e]
+
T luaL_opt (L, func, arg, dflt);

+
+

+This macro is defined as follows:
+
+
+     (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
+

+In words, if the argument arg is nil or absent,
+the macro results in the default dflt.
+Otherwise, it results in the result of calling func
+with the state L and the argument index arg as
+parameters.
+Note that it evaluates the expression dflt only if needed.
+
+
+
+
+
 
luaL_optinteger

 [-0, +0, v]
 
lua_Integer luaL_optinteger (lua_State *L,
@@ -6660,6 +6792,14 @@ Otherwise, raises an error.
 

 If l is not NULL,
 fills the position *l with the result's length.
+If the result is NULL
+(only possible when returning d and d == NULL),
+its length is considered zero.
+
+
+

+This function uses lua_tolstring to get its result,
+so all conversions and caveats of that function apply here.
 
 
 
@@ -6698,7 +6838,7 @@ Otherwise, raises an error.
 
 
 
luaL_prepbuffer

-[-?, +?, e]
+[-?, +?, m]
 
char *luaL_prepbuffer (luaL_Buffer *B);

 
 

@@ -6710,7 +6850,7 @@ with the predefined size LUAL_BUFFERSIZE
luaL_prepbuffsize

-[-?, +?, e]
+[-?, +?, m]
 
char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);

 
 

@@ -6726,7 +6866,7 @@ it to the buffer.
 
 
 
luaL_pushresult

-[-?, +1, e]
+[-?, +1, m]
 
void luaL_pushresult (luaL_Buffer *B);

 
 

@@ -6738,7 +6878,7 @@ the top of the stack.
 
 
 
luaL_pushresultsize

-[-?, +1, e]
+[-?, +1, m]
 
void luaL_pushresultsize (luaL_Buffer *B, size_t sz);

 
 

@@ -6749,7 +6889,7 @@ Equivalent to the sequence luaL_addsize
 
 
 
luaL_ref

-[-1, +0, e]
+[-1, +0, m]
 
int luaL_ref (lua_State *L, int t);

 
 

@@ -6820,7 +6960,7 @@ Leaves a copy of the module on the stack.
 
 
 
luaL_setfuncs

-[-nup, +0, e]
+[-nup, +0, m]
 
void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);

 
 

@@ -6884,7 +7024,7 @@ this function receives the file handle as its sole argument and
 must return either true (in case of success)
 or nil plus an error message (in case of error).
 Once Lua calls this field,
-the field value is changed to NULL
+it changes the field value to NULL
 to signal that the handle is closed.
 
 
@@ -6892,7 +7032,7 @@ to signal that the handle is closed.
 
 
 
luaL_testudata

-[-0, +0, e]
+[-0, +0, m]
 
void *luaL_testudata (lua_State *L, int arg, const char *tname);

 
 

@@ -6918,7 +7058,7 @@ the function also sets *len with the string length.
 
 
 

-If the value has a metatable with a "__tostring" field,
+If the value has a metatable with a __tostring field,
 then luaL_tolstring calls the corresponding metamethod
 with the value as argument,
 and uses the result of the call as its result.
@@ -6928,7 +7068,7 @@ and uses the result of the call as its result.
 
 
 
luaL_traceback

-[-0, +1, e]
+[-0, +1, m]
 
void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
                      int level);

 
@@ -6975,7 +7115,7 @@ If ref is LUA_NOREF or 
luaL_where

-[-0, +1, e]
+[-0, +1, m]
 
void luaL_where (lua_State *L, int lvl);

 
 

@@ -7207,7 +7347,7 @@ nor vice versa.
 

 If object does not have a metatable, returns nil.
 Otherwise,
-if the object's metatable has a "__metatable" field,
+if the object's metatable has a __metatable field,
 returns the associated value.
 Otherwise, returns the metatable of the given object.
 
@@ -7333,7 +7473,7 @@ you can use next(t) to check whether a table is empty.
 

 The order in which the indices are enumerated is not specified,
 even for numeric indices.
-(To traverse a table in numeric order,
+(To traverse a table in numerical order,
 use a numerical for.)
 
 
@@ -7411,7 +7551,7 @@ use string.format and rawequal (v1, v2)
 Checks whether v1 is equal to v2,
-without invoking any metamethod.
+without invoking the __eq metamethod.
 Returns a boolean.
 
 
@@ -7420,7 +7560,7 @@ Returns a boolean.
 

 
rawget (table, index)

 Gets the real value of table[index],
-without invoking any metamethod.
+without invoking the __index metamethod.
 table must be a table;
 index may be any value.
 
@@ -7431,7 +7571,7 @@ without invoking any metamethod.
 
rawlen (v)

 Returns the length of the object v,
 which must be a table or a string,
-without invoking any metamethod.
+without invoking the __len metamethod.
 Returns an integer.
 
 
@@ -7440,7 +7580,7 @@ Returns an integer.
 

 
rawset (table, index, value)

 Sets the real value of table[index] to value,
-without invoking any metamethod.
+without invoking the __newindex metamethod.
 table must be a table,
 index any value different from nil and NaN,
 and value any Lua value.
@@ -7472,10 +7612,11 @@ and select returns the total number of extra arguments it received.
 
 

 Sets the metatable for the given table.
-(You cannot change the metatable of other types from Lua, only from C.)
+(To change the metatable of other types from Lua code,
+you must use the debug library (§6.10).)
 If metatable is nil,
 removes the metatable of the given table.
-If the original metatable has a "__metatable" field,
+If the original metatable has a __metatable field,
 raises an error.
 
 
@@ -7522,14 +7663,12 @@ the function returns nil.
 
tostring (v)

 Receives a value of any type and
 converts it to a string in a human-readable format.
-Floats always produce strings with some
-floating-point indication (either a decimal dot or an exponent).
 (For complete control of how numbers are converted,
 use string.format.)
 
 
 

-If the metatable of v has a "__tostring" field,
+If the metatable of v has a __tostring field,
 then tostring calls the corresponding value
 with v as argument,
 and uses the result of the call as its result.
@@ -7555,8 +7694,11 @@ and "userdata".
 
 

 
_VERSION

+
+
+

 A global variable (not a function) that
-holds a string containing the current interpreter version.
+holds a string containing the running Lua version.
 The current value of this variable is "Lua 5.3".
 
 
@@ -7579,8 +7721,8 @@ except that it sets a new message handler msgh.
 
6.2 – Coroutine Manipulation

 
 

-The operations related to coroutines comprise a sub-library of
-the basic library and come inside the table coroutine.
+This library comprises the operations to manipulate coroutines,
+which come inside the table coroutine.
 See §2.6 for a general description of coroutines.
 
 
@@ -7590,7 +7732,7 @@ See §2.6 for a general description of coroutines.
 
 

 Creates a new coroutine, with body f.
-f must be a Lua function.
+f must be a function.
 Returns this new coroutine,
 an object with type "thread".
 
@@ -7607,7 +7749,7 @@ Returns true when the running coroutine can yield.
 
 

 A running coroutine is yieldable if it is not the main thread and
-it is not inside a non-yieldable C function.
+it is not inside a non-yieldable C function.
 
 
 
@@ -7674,7 +7816,7 @@ or if it has stopped with an error.
 
 

 Creates a new coroutine, with body f.
-f must be a Lua function.
+f must be a function.
 Returns a function that resumes the coroutine each time it is called.
 Any arguments passed to the function behave as the
 extra arguments to resume.
@@ -7809,8 +7951,8 @@ The path used by require to search for a
 

 Lua initializes the C path package.cpath in the same way
 it initializes the Lua path package.path,
-using the environment variable LUA_CPATH_5_3
-or the environment variable LUA_CPATH
+using the environment variable LUA_CPATH_5_3,
+or the environment variable LUA_CPATH,
 or a default path defined in luaconf.h.
 
 
@@ -8073,7 +8215,7 @@ The string library assumes one-byte character encodings.
 
 

 
string.byte (s [, i [, j]])

-Returns the internal numerical codes of the characters s[i],
+Returns the internal numeric codes of the characters s[i],
 s[i+1], ..., s[j].
 The default value for i is 1;
 the default value for j is i.
@@ -8082,7 +8224,7 @@ following the same rules of function string.sub<
 
 
 

-Numerical codes are not necessarily portable across platforms.
+Numeric codes are not necessarily portable across platforms.
 
 
 
@@ -8091,12 +8233,12 @@ Numerical codes are not necessarily portable across platforms.
 
string.char (···)

 Receives zero or more integers.
 Returns a string with length equal to the number of arguments,
-in which each character has the internal numerical code equal
+in which each character has the internal numeric code equal
 to its corresponding argument.
 
 
 

-Numerical codes are not necessarily portable across platforms.
+Numeric codes are not necessarily portable across platforms.
 
 
 
@@ -8112,9 +8254,9 @@ of the given function,
 so that a later load on this string returns
 a copy of the function (but with new upvalues).
 If strip is a true value,
-the binary representation is created without debug information
-about the function
-(local variable names, lines, etc.).
+the binary representation may not include all debug information
+about the function,
+to save space.
 
 
 

@@ -8138,7 +8280,7 @@ Looks for the first match of
 If it finds a match, then find returns the indices of s
 where this occurrence starts and ends;
 otherwise, it returns nil.
-A third, optional numerical argument init specifies
+A third, optional numeric argument init specifies
 where to start the search;
 its default value is 1 and can be negative.
 A value of true as a fourth, optional argument plain
@@ -8169,6 +8311,9 @@ The only differences are that the options/modifiers
 *, h, L, l, n,
 and p are not supported
 and that there is an extra option, q.
+
+
+

 The q option formats a string between double quotes,
 using escape sequences when necessary to ensure that
 it can safely be read back by the Lua interpreter.
@@ -8186,16 +8331,22 @@ may produce the string:
 
 

 Options
-A and a (when available),
-E, e, f,
+A, a, E, e, f,
 G, and g all expect a number as argument.
 Options c, d,
 i, o, u, X, and x
 expect an integer.
-Option q expects a string;
-option s expects a string without embedded zeros.
-If the argument to option s is not a string,
+When Lua is compiled with a C89 compiler,
+options A and a (hexadecimal floats)
+do not support any modifier (flags, width, length).
+
+
+

+Option s expects a string;
+if its argument is not a string,
 it is converted to one following the same rules of tostring.
+If the option has any modifier (flags, width, length),
+the string argument should not contain embedded zeros.
 
 
 
@@ -8344,7 +8495,7 @@ the captures from the pattern;
 otherwise it returns nil.
 If pattern specifies no captures,
 then the whole match is returned.
-A third, optional numerical argument init specifies
+A third, optional numeric argument init specifies
 where to start the search;
 its default value is 1 and can be negative.
 
@@ -8358,7 +8509,7 @@ its default value is 1 and can be negative.
 

 Returns a binary string containing the values v1, v2, etc.
 packed (that is, serialized in binary form)
-according to the format string fmt (see §6.4.2). 
+according to the format string fmt (see §6.4.2).
 
 
 
@@ -8385,6 +8536,11 @@ The default value for sep is the empty string
 Returns the empty string if n is not positive.
 
 
+

+(Note that it is very easy to exhaust the memory of your machine
+with a single call to this function.)
+
+
 
 
 

@@ -8404,7 +8560,8 @@ If j is absent, then it is assumed to be equal to -1
 In particular,
 the call string.sub(s,1,j) returns a prefix of s
 with length j,
-and string.sub(s, -i) returns a suffix of s
+and string.sub(s, -i) (for a positive i)
+returns a suffix of s
 with length i.
 
 
@@ -8499,7 +8656,7 @@ represents the character x itself.
 represents the character x.
 This is the standard way to escape the magic characters.
 Any non-alphanumeric character
-(including all punctuations, even the non-magical)
+(including all punctuation characters, even the non-magical)
 can be preceded by a '%'
 when used to represent itself in a pattern.
 
@@ -8520,6 +8677,14 @@ and [0-7%l%-] represents the octal digits plus
 the lowercase letters plus the '-' character.
 
 
+

+You can put a closing square bracket in a set
+by positioning it as the first character in the set.
+You can put an hyphen in a set
+by positioning it as the first or the last character in the set.
+(You can also use an escape for both cases.)
+
+
 

 The interaction between ranges and classes is not defined.
 Therefore, patterns like [%a-z] or [a-%%]
@@ -8813,7 +8978,7 @@ Returns the number of UTF-8 characters in string s
 that start between positions i and j (both inclusive).
 The default for i is 1 and for j is -1.
 If it finds any invalid byte sequence,
-returns a false value plus the position of the first invalid byte. 
+returns a false value plus the position of the first invalid byte.
 
 
 
@@ -8857,8 +9022,7 @@ It provides all its functions inside the table table
 Remember that, whenever an operation needs the length of a table,
-the table must be a proper sequence
-or have a __len metamethod (see §3.4.7).
+all caveats about the length operator apply (see §3.4.7).
 All functions ignore non-numeric keys
 in the tables given as arguments.
 
@@ -8898,13 +9062,17 @@ of list t.
 
 
 

-Moves elements from table a1 to table a2.
-This function performs the equivalent to the following
+Moves elements from table a1 to table a2,
+performing the equivalent to the following
 multiple assignment:
 a2[t],··· = a1[f],···,a1[e].
 The default for a2 is a1.
 The destination range can overlap with the source range.
-Index f must be positive.
+The number of elements to be moved must fit in a Lua integer.
+
+
+

+Returns the destination table a2.
 
 
 
@@ -8956,14 +9124,22 @@ If comp is given,
 then it must be a function that receives two list elements
 and returns true when the first element must come
 before the second in the final order
-(so that not comp(list[i+1],list[i]) will be true after the sort).
+(so that, after the sort,
+i < j implies not comp(list[j],list[i])).
 If comp is not given,
 then the standard Lua operator < is used instead.
 
 
 

-The sort algorithm is not stable;
-that is, elements considered equal by the given order
+Note that the comp function must define
+a strict partial order over the elements in the list;
+that is, it must be asymmetric and transitive.
+Otherwise, no valid sort may be possible.
+
+
+

+The sort algorithm is not stable:
+elements considered equal by the given order
 may have their relative positions changed by the sort.
 
 
@@ -9120,7 +9296,7 @@ that rounds the quotient towards zero. (integer/float)
 
 

 The float value HUGE_VAL,
-a value larger than any other numerical value.
+a value larger than any other numeric value.
 
 
 
@@ -9215,14 +9391,13 @@ in the range  [0,1).
 When called with two integers m and n,
 math.random returns a pseudo-random integer
 with uniform distribution in the range [m, n].
-(The value m-n cannot be negative and must fit in a Lua integer.)
+(The value n-m cannot be negative and must fit in a Lua integer.)
 The call math.random(n) is equivalent to math.random(1,n).
 
 
 

 This function is an interface to the underling
 pseudo-random generator function provided by C.
-No guarantees can be given for its statistical properties.
 
 
 
@@ -9300,7 +9475,7 @@ or nil if x is not a number.
 
 

 Returns a boolean,
-true if integer m is below integer n when
+true if and only if integer m is below integer n when
 they are compared as unsigned integers.
 
 
@@ -9390,7 +9565,7 @@ instead of returning an error code.
 
 
 

-
io.lines ([filename ···])

+
io.lines ([filename, ···])

 
 
 

@@ -9422,8 +9597,8 @@ instead of returning an error code.
 

 This function opens a file,
 in the mode specified in the string mode.
-It returns a new file handle,
-or, in case of errors, nil plus an error message.
+In case of success,
+it returns a new file handle.
 
 
 

@@ -9488,7 +9663,8 @@ Equivalent to io.input():read(···).
 
 
 

-Returns a handle for a temporary file.
+In case of success,
+returns a handle for a temporary file.
 This file is opened in update mode
 and it is automatically removed when the program ends.
 
@@ -9602,16 +9778,12 @@ reads a numeral and returns it as a float or an integer,
 following the lexical conventions of Lua.
 (The numeral may have leading spaces and a sign.)
 This format always reads the longest input sequence that
-is a valid prefix for a number;
-if that prefix does not form a valid number
+is a valid prefix for a numeral;
+if that prefix does not form a valid numeral
 (e.g., an empty string, "0x", or "3.4e-"),
 it is discarded and the function returns nil.
 
 
-
  • "i": 
-reads an integral number and returns it as an integer.
-
    • 
-
 
  • "a": 
 reads the whole file, starting at the current position.
 On end of file, it returns the empty string.
@@ -9768,10 +9940,10 @@ then the date is formatted in Coordinated Universal Time.
 After this optional character,
 if format is the string "*t",
 then date returns a table with the following fields:
-year (four digits), month (1–12), day (1–31),
+year, month (1–12), day (1–31),
 hour (0–23), min (0–59), sec (0–61),
-wday (weekday, Sunday is 1),
-yday (day of the year),
+wday (weekday, 1–7, Sunday is 1),
+yday (day of the year, 1–366),
 and isdst (daylight saving flag, a boolean).
 This last field may be absent
 if the information is not available.
@@ -9786,8 +9958,8 @@ formatted according to the same rules as the ISO C function strftime<
 
    
 When called without arguments,
 date returns a reasonable date and time representation that depends on
-the host system and on the current locale
-(that is, os.date() is equivalent to os.date("%c")).
+the host system and on the current locale.
+(More specifically, os.date() is equivalent to os.date("%c").)
 
 
 
    
@@ -9889,6 +10061,7 @@ Deletes the file (or empty directory, on POSIX systems)
 with the given name.
 If this function fails, it returns nil,
 plus a string describing the error and the error code.
+Otherwise, it returns true.
 
 
 
@@ -9898,9 +10071,10 @@ plus a string describing the error and the error code.
 
 
 
    
-Renames file or directory named oldname to newname.
+Renames the file or directory named oldname to newname.
 If this function fails, it returns nil,
 plus a string describing the error and the error code.
+Otherwise, it returns true.
 
 
 
@@ -9946,16 +10120,25 @@ because of its reliance on C function setlocale.
 
 
    
 Returns the current time when called without arguments,
-or a time representing the date and time specified by the given table.
+or a time representing the local date and time specified by the given table.
 This table must have fields year, month, and day,
 and may have fields
 hour (default is 12),
 min (default is 0),
 sec (default is 0),
 and isdst (default is nil).
+Other fields are ignored.
 For a description of these fields, see the os.date function.
 
 
+
    
+The values in these fields do not need to be inside their valid ranges.
+For instance, if sec is -10,
+it means -10 seconds from the time specified by the other fields;
+if hour is 1000,
+it means +1000 hours from the time specified by the other fields.
+
+
 
    
 The returned value is a number, whose meaning depends on your system.
 In POSIX, Windows, and some other systems,
@@ -10093,7 +10276,7 @@ valid lines.
 
 
    
 For instance, the expression debug.getinfo(1,"n").name returns
-a table with a name for the current function,
+a name for the current function,
 if a reasonable name can be found,
 and the expression debug.getinfo(print)
 returns a table with all available information
@@ -10184,7 +10367,7 @@ represent variables with no known names
 
 
    
 Returns the Lua value associated to u.
-If u is not a userdata,
+If u is not a full userdata,
 returns nil.
 
 
@@ -10383,7 +10566,7 @@ and as lua - otherwise.
 
 
 
    
-When called without option -E, 
+When called without option -E,
 the interpreter checks for an environment variable LUA_INIT_5_3
 (or LUA_INIT if the versioned name is not defined)
 before running any argument.
@@ -10464,10 +10647,18 @@ the interpreter waits for its completion
 by issuing a different prompt.
 
 
+
    
+If the global variable _PROMPT contains a string,
+then its value is used as the prompt.
+Similarly, if the global variable _PROMPT2 contains a string,
+its value is used as the secondary prompt
+(issued during incomplete statements).
+
+
 
    
 In case of unprotected errors in the script,
 the interpreter reports the error to the standard error stream.
-If the error object is not a string but 
+If the error object is not a string but
 has a metamethod __tostring,
 the interpreter calls this metamethod to produce the final message.
 Otherwise, the interpreter converts the error object to a string
@@ -10599,7 +10790,8 @@ The bit32 library has been deprecated.
 It is easy to require a compatible external library or,
 better yet, to replace its functions with appropriate bitwise operations.
 (Keep in mind that bit32 operates on 32-bit integers,
-while the bitwise operators in standard Lua operate on 64-bit integers.)
+while the bitwise operators in Lua 5.3 operate on Lua integers,
+which by default have 64 bits.)
 
    • 
 
 
  • 
@@ -10614,7 +10806,7 @@ its __ipairs metamethod has been deprecated.
 
 
  • 
 Option names in io.read do not have a starting '*' anymore.
-For compatibility, Lua will continue to ignore this character.
+For compatibility, Lua will continue to accept (and ignore) this character.
 
    • 
 
 
  • 
@@ -10641,6 +10833,12 @@ if it cannot find an open function according to the new style.
 but it did not document the change.)
 
    • 
 
+
  • 
+The call collectgarbage("count") now returns only one result.
+(You can compute that second result from the fractional part
+of the first result.)
+
    • 
+
 
 
 
@@ -10775,14 +10973,12 @@ and LiteralString, see §3.1.)
 
 
 
-
-
    
-
+
    
 Last update:
-Tue Jan  6 10:10:50 BRST 2015
-
+Mon Jan  9 13:30:53 BRST 2017
+
    
 
 
 
diff --git a/doc/readme.html b/doc/readme.html
index 016575570133..96a9386e2af0 100644
--- a/doc/readme.html
+++ b/doc/readme.html
@@ -7,9 +7,9 @@