From d7648e85b78d53a2248de909868192598ad0eb69 Mon Sep 17 00:00:00 2001 From: Lua Team Date: Thu, 31 Jul 2014 12:00:00 +0000 Subject: Lua 5.3.0-alpha --- doc/manual.html | 416 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 231 insertions(+), 185 deletions(-) (limited to 'doc/manual.html') diff --git a/doc/manual.html b/doc/manual.html index de2dc5f6..186597b5 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -18,13 +18,13 @@ Lua 5.3 Reference Manual

-All details may change in the final version. +Some details may change in the final version.

by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes

-Copyright © 2011–2014 Lua.org, PUC-Rio. +Copyright © 2014 Lua.org, PUC-Rio. Freely available under the terms of the Lua license. @@ -38,7 +38,7 @@ Freely available under the terms of the

- + @@ -125,7 +125,7 @@ it usually represents the absence of a useful value. Both nil and false make a condition false; any other value makes it true. Number represents both -integral numbers and real (floating-point) numbers. +integer numbers and real (floating-point) numbers. String represents immutable sequences of bytes. Lua is 8-bit clean: @@ -146,7 +146,7 @@ Standard Lua uses 64-bit integers and double-precision (64-bit) floats, but you can also compile Lua so that it uses 32-bit integers and/or single-precision (32-bit) floats. The option with 32 bits both for integers and floats -(what is called Small Lua) is particularly attractive +(called Small Lua) is particularly attractive for small machines. @@ -159,7 +159,7 @@ functions written in C

The type userdata is provided to allow arbitrary C data to be stored in Lua variables. -A userdata value is a pointer to a block of raw memory. +A userdata value represents a block of raw memory. There are two kinds of userdata: full userdata, where the block of memory is managed by Lua, and light userdata, where the block of memory is managed by the host. @@ -178,7 +178,7 @@ The type thread represents independent threads of execution and it is used to implement coroutines (see §2.6). Do not confuse Lua threads with operating-system threads. Lua supports coroutines on all systems, -even those that do not support threads. +even those that do not support threads natively.

@@ -324,7 +324,9 @@ is never updated by Lua.

Because Lua is an embedded extension language, all Lua actions start from C code in the host program -calling a function from the Lua library (see lua_pcall). +calling a function from the Lua library. +(when you use Lua standalone, +the lua application is the host program.) Whenever an error occurs during the compilation or execution of a Lua chunk, control returns to the host, @@ -1891,9 +1893,9 @@ that rounds the quotient towards minus infinite (floor). In case of overflows in integer arithmetic, all operations wrap around, according to the usual rules of two-complement arithmetic. -(In other words, they return the correct result modulo 264.) - - +(In other words, +they return the unique representable integer +that is equal modulo 264 to the mathematical result.) @@ -1921,7 +1923,7 @@ Both right and left shifts fill the vacant bits with zeros. Negative displacements shift to the other direction; displacements with absolute values equal to or higher than the number of bits in an integer -result in zero (all bits are shifted out). +result in zero (as all bits are shifted out). @@ -1952,16 +1954,17 @@ In a conversion from integer to float, if the integer value has an exact representation as a float, that is the result. Otherwise, -the conversion gets the nearest higher or lower representable value. +the conversion gets the nearest higher or +the nearest lower representable value. This kind of conversion never fails.

The conversion from float to integer -first takes the floor of the float number. -If that value can be represented as an integer -(that is, it is in the range of integer representation), -that is the result. +checks whether the float has an exact representation as an integer +(that is, the float has an integral value and +it is in the range of integer representation). +If it does, that representation is the result. Otherwise, the conversion fails. @@ -2005,7 +2008,7 @@ Otherwise, the values of the operands are compared. Strings are compared in the obvious way. Numbers follow the usual rule for binary operations: if both operands are integers, -the are compared as integers; +they are compared as integers; otherwise, they are converted to floats and compared as such. @@ -2028,7 +2031,7 @@ by using the "eq" metamethod (see §2.4).

-Equality comparisons never convert strings to numbers +Equality comparisons do not convert strings to numbers or vice versa. Thus, "0"==0 evaluates to false, and t[0] and t["0"] denote different @@ -2190,7 +2193,7 @@ with key exp1 and value exp2. A field of the form name = exp is equivalent to ["name"] = exp. Finally, fields of the form exp are equivalent to -[i] = exp, where i are consecutive numerical integers, +[i] = exp, where i are consecutive integers starting with 1. Fields in the other formats do not affect this counting. For example, @@ -2861,7 +2864,7 @@ the Lua code being ran by lua_pcall to yie First, we can rewrite our function like here: 

-     int k (lua_State *L, int status, int ctx) {
+     int k (lua_State *L, int status, lua_Ctx ctx) {
        ...  /* code 2 */
      }
      
@@ -2905,6 +2908,12 @@ the status is always LUA_YIELD when Lu
 (For these two functions,
 Lua will not call the continuation in case of errors,
 because they do not handle errors.)
+Similarly, when using lua_callk,
+you should call the continuation function
+with LUA_OK as the status.
+(For lua_yieldk, there is not much point in calling
+directly the continuation function,
+because lua_yieldk usually does not return.)
 
 
 

@@ -3159,7 +3168,7 @@ This is considered good programming practice.
 
 
lua_callk

 [-(nargs + 1), +nresults, e]
-
void lua_callk (lua_State *L, int nargs, int nresults, int ctx,
+
void lua_callk (lua_State *L, int nargs, int nresults, lua_Ctx ctx,
                 lua_KFunction k);

 
 

@@ -3307,7 +3316,7 @@ Concatenation is performed following the usual semantics of Lua
 
void lua_copy (lua_State *L, int fromidx, int toidx);

 
 

-Moves the element at index fromidx
+Copies the element at index fromidx
 into the valid index toidx
 without shifting any element
 (therefore replacing the value at that position).
@@ -3335,6 +3344,21 @@ Otherwise you can use the function lua_newtable
lua_Ctx

+
typedef ... lua_Ctx;

+
+

+The type for continuation-function contexts.
+It must be a numerical type.
+This type is defined as intptr_t
+when intptr_t is available,
+so that it can store pointers too.
+Otherwise, it is defined as ptrdiff_t.
+
+
+
+
+
 
lua_dump

 [-0, +0, e]
 
int lua_dump (lua_State *L,
@@ -3485,6 +3509,31 @@ Returns the type of the pushed value.
 
 
 
+
lua_getextraspace

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

+
+

+Returns a pointer to a raw memory area associated with the
+given Lua state.
+The application can use this area for any purpose;
+Lua does not use it for anything.
+
+
+

+Each new thread has this area initialized with a copy
+of the area of the main thread.
+
+
+

+By default, this area has the size of a pointer to void,
+but you can recompile Lua with a different size for this area.
+(See LUA_EXTRASPACE in luaconf.h.)
+
+
+
+
+
 
lua_getglobal

 [-0, +1, e]
 
int lua_getglobal (lua_State *L, const char *name);

@@ -3502,8 +3551,9 @@ Returns the type of that value.
 
int lua_getmetatable (lua_State *L, int index);

 
 

-Pushes onto the stack the metatable of the value at the given index.
-If the value does not have a metatable,
+If the value at the given index has a metatable,
+the function pushes that metatable onto the stack and returns 1.
+Otherwise,
 the function returns 0 and pushes nothing on the stack.
 
 
@@ -3588,9 +3638,9 @@ The type of integers in Lua.
 

 By default this type is long long
 (usually a 64-bit two-complement integer),
-but that can be changed in luaconf.h
-to long or int
-(usually a 32-bit two-complement integer).
+but that can be changed to long or int,
+usually a 32-bit two-complement integer.
+(See LUA_INT in luaconf.h.)
 
 
 

@@ -3775,7 +3825,7 @@ and 0 otherwise.
 
 
 
lua_KFunction

-
typedef int (*lua_KFunction) (lua_State *L, int status, int ctx);

+
typedef int (*lua_KFunction) (lua_State *L, int status, lua_Ctx ctx);

 
 

 Type for continuation functions (see §4.7).
@@ -3988,7 +4038,8 @@ The type of floats in Lua.
 
 

 By default this type is double,
-but that can be changed in luaconf.h to a single float.
+but that can be changed to a single float.
+(See LUA_REAL in luaconf.h.)
 
 
 
@@ -4096,7 +4147,7 @@ error while running a __gc metamethod.
                 int nargs,
                 int nresults,
                 int errfunc,
-                int ctx,
+                lua_Ctx ctx,
                 lua_KFunction k);

 
 

@@ -4366,17 +4417,6 @@ Returns 1 if this thread is the main thread of its state.
 
 
 
-
lua_pushunsigned

-[-0, +1, –]
-
void lua_pushunsigned (lua_State *L, lua_Unsigned n);

-
-

-Pushes an integer with value n onto the stack.
-
-
-
-
-
 
lua_pushvalue

 [-0, +1, –]
 
void lua_pushvalue (lua_State *L, int index);

@@ -4916,9 +4956,12 @@ to a string inside the Lua state.
 This string always has a zero ('\0')
 after its last character (as in C),
 but can contain other zeros in its body.
+
+
+

 Because Lua has garbage collection,
 there is no guarantee that the pointer returned by lua_tolstring
-will be valid after the corresponding value is removed from the stack.
+will be valid after the corresponding Lua value is removed from the stack.
 
 
 
@@ -5001,48 +5044,6 @@ otherwise, the function returns NULL.
 
 
 
-
lua_tounsigned

-[-0, +0, –]
-
lua_Unsigned lua_tounsigned (lua_State *L, int index);

-
-

-Equivalent to lua_tounsignedx with isnum equal to NULL.
-
-
-
-
-
-
lua_tounsignedx

-[-0, +0, –]
-
lua_Unsigned lua_tounsignedx (lua_State *L, int index, int *isnum);

-
-

-Converts the Lua value at the given index
-to the unsigned integral type lua_Unsigned.
-The Lua value must be an integer,
-or a float,
-or a string convertible to a number
-(see §3.4.3);
-otherwise, lua_tounsignedx returns 0.
-
-
-

-If the number is not an integer,
-it is rounded towards minus infinite (floor).
-If the result is outside the range of representable values,
-it is normalized to the module of its division by
-one more than the maximum representable value.
-
-
-

-If isnum is not NULL,
-its referent is assigned a boolean value that
-indicates whether the operation succeeded.
-
-
-
-
-
 
lua_touserdata

 [-0, +0, –]
 
void *lua_touserdata (lua_State *L, int index);

@@ -5101,11 +5102,6 @@ which must be one the values returned by lua_typelua_Integer.
 
 
-

-Lua also defines the constant LUA_MAXUNSIGNED,
-with the maximum value that fits in this type.
-
-
 
 
 
@@ -5178,14 +5174,14 @@ and pushes them onto the stack to.
 
 
 
lua_yield

-[-?, +?, –]
+[-?, +?, e]
 
int lua_yield (lua_State *L, int nresults);

 
 

 This function is equivalent to lua_yieldk,
 but it has no continuation (see §4.7).
 Therefore, when the thread resumes,
-it returns to the function that called
+it continues the function that called
 the function calling lua_yield.
 
 
@@ -5193,21 +5189,15 @@ the function calling lua_yield.
 
 
 
lua_yieldk

-[-?, +?, –]
-
int lua_yieldk (lua_State *L, int nresults, int ctx, lua_KFunction k);

+[-?, +?, e]
+
int lua_yieldk (lua_State *L, int nresults, lua_Ctx ctx, lua_KFunction k);

 
 

-Yields a coroutine.
+Yields a coroutine (thread).
 
 
 

-This function should only be called as the
-return expression of a C function, as follows:
-
-
-     return lua_yieldk (L, n, ctx, k);
-

-When a C function calls lua_yieldk in that way,
+When a C function calls lua_yieldk,
 the running coroutine suspends its execution,
 and the call to lua_resume that started this coroutine returns.
 The parameter nresults is the number of values from the stack
@@ -5227,6 +5217,29 @@ the continuation function receives the value ctx
 that was passed to lua_yieldk.
 
 
+

+Usually, this function does not return;
+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).
+In that case, lua_yieldk should be called with no continuation
+(probably in the form of lua_yield),
+and the hook should return immediately after the call.
+Lua will yield and,
+when the coroutine resumes again,
+it will continue the normal execution
+of the (Lua) function that triggered the hook.
+
+
+

+This function can raise an error if it is called from a thread
+with a pending C call with no continuation function,
+or it is called from a thread that is not running inside a resume
+(e.g., the main thread).
+
+
 
 
 
@@ -6196,18 +6209,6 @@ returns the userdata address (see lua_touserdata
 
 
 
-
luaL_checkunsigned

-[-0, +0, v]
-
lua_Unsigned luaL_checkunsigned (lua_State *L, int arg);

-
-

-Checks whether the function argument arg is a number
-and returns this number converted to a lua_Unsigned.
-
-
-
-
-
 
luaL_checkversion

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

@@ -6682,23 +6683,6 @@ Otherwise, raises an error.
 
 
 
-
luaL_optunsigned

-[-0, +0, v]
-
lua_Unsigned luaL_optunsigned (lua_State *L,
-                               int arg,
-                               lua_Unsigned u);

-
-

-If the function argument arg is a number,
-returns this number converted to a lua_Unsigned.
-If this argument is absent or is nil,
-returns u.
-Otherwise, raises an error.
-
-
-
-
-
 
luaL_prepbuffer

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

@@ -6803,18 +6787,19 @@ in which both name and func are NULL.
                     lua_CFunction openf, int glb);

 
 

-Calls function openf with string modname as an argument
+If modname is not already present in package.loaded,
+calls function openf with string modname as an argument
 and sets the call result in package.loaded[modname],
 as if that function has been called through require.
 
 
 

 If glb is true,
-also stores the result into global modname.
+also stores the module into global modname.
 
 
 

-Leaves a copy of that result on the stack.
+Leaves a copy of the module on the stack.
 
 
 
@@ -7218,21 +7203,19 @@ Otherwise, returns the metatable of the given object.
 
 
 

-If t has a metamethod __ipairs,
-calls it with t as argument and returns the first three
-results from the call.
-
-
-

-Otherwise,
-returns three values: an iterator function, the table t, and 0,
+Returns three values (an iterator function, the table t, and 0)
 so that the construction
 
 
      for i,v in ipairs(t) do body end
 

-will iterate over the pairs (1,t[1]), (2,t[2]), ...,
-up to the first integer key absent from the table.
+will iterate over the pairs
+(1,t[1]), (2,t[2]), ..., (#t,t[#t]).
+
+
+

+The table should be a proper sequence
+or have a __len metamethod (see §3.4.7).
 
 
 
@@ -7973,9 +7956,9 @@ The name of this C function is the string "luaopen_"
 concatenated with a copy of the module name where each dot
 is replaced by an underscore.
 Moreover, if the module name has a hyphen,
-its prefix up to (and including) the first hyphen is removed.
-For instance, if the module name is a.v1-b.c,
-the function name will be luaopen_b_c.
+its sufix after (and including) the first hyphen is removed.
+For instance, if the module name is a.b.c-v2.1,
+the function name will be luaopen_a_b_c.
 
 
 

@@ -8138,6 +8121,8 @@ This function may not work correctly in architectures
 with mixed endian.
 
 
+
+
 

 
string.dumpint (n [, size [, endianness]])

 Returns a string with the two-complement representation of integer n,
@@ -8165,7 +8150,7 @@ that do not use a two-complement representation for integers.
 
 

 Looks for the first match of
-pattern in the string s.
+pattern (see §6.4.1) in the string s.
 If it finds a match, then find returns the indices of s
 where this occurrence starts and ends;
 otherwise, it returns nil.
@@ -8235,7 +8220,8 @@ it is converted to one following the same rules of 
string.gmatch (s, pattern)

 Returns an iterator function that,
 each time it is called,
-returns the next captures from pattern over the string s.
+returns the next captures from pattern (see §6.4.1)
+over the string s.
 If pattern specifies no captures,
 then the whole match is produced in each call.
 
@@ -8273,7 +8259,7 @@ work as an anchor, as this would prevent the iteration.
 
string.gsub (s, pattern, repl [, n])

 Returns a copy of s
 in which all (or the first n, if given)
-occurrences of the pattern have been
+occurrences of the pattern (see §6.4.1) have been
 replaced by a replacement string specified by repl,
 which can be a string, a table, or a function.
 gsub also returns, as its second value,
@@ -8368,7 +8354,7 @@ The definition of what an uppercase letter is depends on the current locale.
 

 
string.match (s, pattern [, init])

 Looks for the first match of
-pattern in the string s.
+pattern (see §6.4.1) in the string s.
 If it finds one, then match returns
 the captures from the pattern;
 otherwise it returns nil.
@@ -8456,8 +8442,21 @@ The definition of what a lowercase letter is depends on the current locale.
 
 
 
+
+
 
6.4.1 – Patterns

 
+

+Patterns in Lua are described by regular strings,
+which are interpreted as patterns by the pattern-matching functions
+string.find,
+string.gmatch,
+string.gsub,
+and string.match.
+This section describes the syntax and the meaning
+(that is, what they match) of these strings.
+
+
 
 
Character Class:

 A character class is used to represent a set of characters.
@@ -8649,8 +8648,6 @@ string "flaaap", there will be two captures: 3 and 5.
 
 
 
-
-
 
6.5 – UTF-8 Support

 
 

@@ -8774,11 +8771,6 @@ All functions ignore non-numeric keys
 in tables given as arguments.
 
 
-

-For performance reasons,
-all table accesses (get/set) performed by these functions are raw.
-
-
 

 
table.concat (list [, sep [, i [, j]]])

 
@@ -8794,6 +8786,22 @@ If i is greater than j, returns the empty string.
 
 
 
+

+
table.copy (a1, f, e, [a2,] t)

+
+
+

+Copies elements from table a1 to table a2.
+This function performs 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.
+
+
+
+
 

 
table.insert (list, [pos,] value)

 
@@ -9014,18 +9022,6 @@ a value larger than any other numerical value.
 
 
 
-

-
math.ifloor (x)

-
-
-

-Returns the largest integer smaller than or equal to x.
-If the value does not fit in an integer,
-returns nil.
-
-
-
-
 

 
math.log (x [, base])

 
@@ -9171,6 +9167,18 @@ Returns the tangent of x (assumed to be in radians).
 
 
 
+

+
math.tointeger (x)

+
+
+

+If the value x is convertible to an integer,
+returns that integer.
+Otherwise, returns nil.
+
+
+
+
 

 
math.type (x)

 
@@ -9183,6 +9191,18 @@ or nil if x is not a number.
 
 
 
+

+
math.ult (m, n)

+
+
+

+Returns a boolean,
+true if integer m is below integer n when
+they are compared as unsigned integers.
+
+
+
+
 
 
 
@@ -10272,8 +10292,7 @@ The options are:
 
  • --:  stops handling options;
    • 
 
  • -:  executes stdin as a file and stops handling options.
    • 
 
    
-After handling its options, lua runs the given script,
-passing to it the given args as string arguments.
+After handling its options, lua runs the given script.
 When called without arguments,
 lua behaves as lua -v -i
 when the standard input (stdin) is a terminal,
@@ -10283,7 +10302,7 @@ and as lua - otherwise.
 
    
 When called without option -E, 
 the interpreter checks for an environment variable LUA_INIT_5_3
-(or LUA_INIT if it is not defined)
+(or LUA_INIT if the versioned name is not defined)
 before running any argument.
 If the variable content has the format @filename,
 then lua executes the file.
@@ -10343,6 +10362,11 @@ For instance, the call
      $ lua -e "print(arg[1])"

    will print "-e". +If there is a script, +the script is called with parameters +arg[1], ···, arg[#arg]. +(Like all chunks in Lua, +the script is compiled as a vararg function.)

    @@ -10417,7 +10441,7 @@ do not imply source-code changes in a program, such as the numeric values for constants or the implementation of functions as macros. Therefore, -you should never assume that binaries are compatible between +you should not assume that binaries are compatible between different Lua versions. Always recompile clients of the Lua API when using a new version. @@ -10426,7 +10450,7 @@ using a new version.

    Similarly, Lua versions can always change the internal representation of precompiled chunks; -precompiled chunks are never compatible between different Lua versions. +precompiled chunks are not compatible between different Lua versions.

    @@ -10458,12 +10482,6 @@ it is not a general guideline for good programming. For good programming, use floats where you need floats and integers where you need integers.) - - -

    -Although not formally an incompatibility, -the proper differentiation between floats and integers -have an impact on performance.

  • @@ -10502,6 +10520,16 @@ better yet, to replace its functions with appropriate bitwise operations. while the bitwise operators in Standard Lua operate on 64-bit integers.)
    • +
  • +The Table library now respects metamethods +for setting and getting elements. +
    • + +
  • +The ipairs iterator now respects metamethods and +its id{__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. @@ -10513,12 +10541,23 @@ The following functions were deprecated in the mathematical library: frexp, and ldexp. You can replace math.pow(x,y) with x^y; you can replace math.atan2 with math.atan, -which now accepts two parameters; +which now accepts one or two parameters; you can replace math.ldexp(x,exp) with x * 2.0^exp. For the other operations, the best choice is to use an external library.
    • +
  • +The searcher for C loaders used by require +changed the way it handles versioned names. +Now, the version should come after the module name +(as is usual in most other tools). +For compatibility, that searcher still tries the old format +if if cannot find an open function according to the new style. +(Lua 5.2 already worked that way, +but it did not document the change.) +
    • + @@ -10541,6 +10580,13 @@ Function lua_dump has an extra parameter, < Use 0 as the value of this parameter to get the old behavior. +
  • +Functions to inject/project unsigned integers +(lua_pushunsigned, lua_tounsigned, etc.) +were deprecated. +Use their signed equivalents with a type cast. +
    • + @@ -10550,7 +10596,7 @@ Use 0 as the value of this parameter to get the old behavior.

    Here is the complete syntax of Lua in extended BNF. -(It does not describe operator precedences.) +(For operator precedences, see §3.4.8.) @@ -10635,10 +10681,10 @@ Here is the complete syntax of Lua in extended BNF.

    Last update: -Thu Jun 19 17:13:19 BRT 2014 +Thu Jul 31 14:02:14 BRT 2014 -- cgit v1.2.1