From b96b0b5abbf40cbdbed7952bf35a5a27ddf75928 Mon Sep 17 00:00:00 2001 From: Roberto Ierusalimschy Date: Fri, 16 Aug 2019 14:58:02 -0300 Subject: Added macro 'luaL_pushfail' The macro 'luaL_pushfail' documents all places in the standard libraries that return nil to signal some kind of failure. It is defined as 'lua_pushnil'. The manual also got a notation (@fail) to document those returns. The tests were changed to be agnostic regarding whether 'fail' is 'nil' or 'false'. --- manual/2html | 1 + manual/manual.of | 87 +++++++++++++++++++++++++++++++++----------------------- 2 files changed, 52 insertions(+), 36 deletions(-) (limited to 'manual') diff --git a/manual/2html b/manual/2html index 605c6e59..a300f8d4 100755 --- a/manual/2html +++ b/manual/2html @@ -324,6 +324,7 @@ N = function (s) return (string.gsub(s, " ", " ")) end, NE = id, -- tag"foreignphrase", num = id, ["nil"] = fixed(Tag.b"nil"), +fail = fixed(Tag.b"fail"), Open = fixed"{", part = section("h1", true), Pat = compose(verbfixed, prepos("'", "'")), diff --git a/manual/manual.of b/manual/manual.of index bb6ae884..53073a54 100644 --- a/manual/manual.of +++ b/manual/manual.of @@ -4058,12 +4058,15 @@ Returns 0 if the userdata does not have that value. } -@APIEntry{void lua_setmetatable (lua_State *L, int index);| +@APIEntry{int lua_setmetatable (lua_State *L, int index);| @apii{1,0,-} Pops a table from the stack and sets it as the new metatable for the value at the given index. +(For historical reasons, this function returns an @id{int}, +which now is always 1.) + } @APIEntry{void lua_settable (lua_State *L, int index);| @@ -5782,7 +5785,7 @@ that will be called to close the stream when the handle is closed or collected; 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. +or a false value plus an error message, in case of error. Once Lua calls this field, it changes the field value to @id{NULL} to signal that the handle is closed. @@ -5904,6 +5907,14 @@ to its expected parameters. For instance, a function documented as @T{foo(arg)} should not be called without an argument. +The notation @fail means a return value representing +some kind of failure or the absence of a better value to return. +Currently, @fail is equal to @nil, +but that may change in future versions. +The recommendation is to test the success of these functions +with @T{(not status)}, instead of @T{(status == nil)}. + + Currently, Lua has the following standard libraries: @itemize{ @@ -6108,8 +6119,8 @@ with previous results. A return of an empty string, @nil, or no value signals the end of the chunk. If there are no syntactic errors, -returns the compiled chunk as a function; -otherwise, returns @nil plus the error message. +@id{load} returns the compiled chunk as a function; +otherwise, it returns @fail plus the error message. When you load a main chunk, the resulting function will always have exactly one upvalue, @@ -6301,7 +6312,7 @@ When called with no @id{base}, If the argument is already a number or a string convertible to a number, then @id{tonumber} returns this number; -otherwise, it returns @nil. +otherwise, it returns @fail. The conversion of strings can result in integers or floats, according to the lexical conventions of Lua @see{lexical}. @@ -6315,7 +6326,7 @@ In bases @N{above 10}, the letter @Char{A} (in either upper or lower case) @N{represents 10}, @Char{B} @N{represents 11}, and so forth, with @Char{Z} representing 35. If the string @id{e} is not a valid numeral in the given base, -the function returns @nil. +the function returns @fail. } @@ -6762,7 +6773,7 @@ will try to open the files Returns the resulting name of the first file that it can open in read mode (after closing the file), -or @nil plus an error message if none succeeds. +or @fail plus an error message if none succeeds. (This error message lists all file names it tried to open.) } @@ -6841,7 +6852,7 @@ Looks for the first match of @id{pattern} @see{pm} in the string @id{s}. If it finds a match, then @id{find} returns the indices @N{of @T{s}} where this occurrence starts and ends; -otherwise, it returns @nil. +otherwise, it returns @fail. A third, optional numeric argument @id{init} specifies where to start the search; its default value @N{is 1} and can be negative. @@ -7034,7 +7045,7 @@ Looks for the first @emph{match} of the @id{pattern} @see{pm} in the string @id{s}. If it finds one, then @id{match} returns the captures from the pattern; -otherwise it returns @nil. +otherwise it returns @fail. If @id{pattern} specifies no captures, then the whole match is returned. A third, optional numeric argument @id{init} specifies @@ -7499,7 +7510,7 @@ Returns the number of UTF-8 characters in string @id{s} that start between positions @id{i} and @id{j} (both inclusive). The default for @id{i} is @num{1} and for @id{j} is @num{-1}. If it finds any invalid byte sequence, -returns a false value plus the position of the first invalid byte. +returns @fail plus the position of the first invalid byte. } @@ -7515,7 +7526,7 @@ so that @T{utf8.offset(s, -n)} gets the offset of the @id{n}-th character from the end of the string. If the specified character is neither in the subject nor right after its end, -the function returns @nil. +the function returns @fail. As a special case, when @id{n} is 0 the function returns the start of the encoding @@ -7850,7 +7861,7 @@ Returns the tangent of @id{x} (assumed to be in radians). If the value @id{x} is convertible to an integer, returns that integer. -Otherwise, returns @nil. +Otherwise, returns @fail. } @@ -7858,7 +7869,7 @@ Otherwise, returns @nil. Returns @St{integer} if @id{x} is an integer, @St{float} if it is a float, -or @nil if @id{x} is not a number. +or @fail if @id{x} is not a number. } @@ -7897,10 +7908,10 @@ three predefined file handles with their usual meanings from C: The I/O library never closes these files. Unless otherwise stated, -all I/O functions return @nil on failure, +all I/O functions return @fail on failure, plus an error message as a second result and a system-dependent error code as a third result, -and some value different from @nil on success. +and some non-false value on success. On non-POSIX systems, the computation of the error message and error code in case of errors @@ -8021,7 +8032,7 @@ and it is automatically removed when the program ends. Checks whether @id{obj} is a valid file handle. Returns the string @T{"file"} if @id{obj} is an open file handle, @T{"closed file"} if @id{obj} is a closed file handle, -or @nil if @id{obj} is not a file handle. +or @fail if @id{obj} is not a file handle. } @@ -8075,7 +8086,7 @@ Reads the file @id{file}, according to the given formats, which specify what to read. For each format, the function returns a string or a number with the characters read, -or @nil if it cannot read data with the specified format. +or @fail if it cannot read data with the specified format. (In this latter case, the function does not read subsequent formats.) When called without arguments, @@ -8094,31 +8105,32 @@ is a valid prefix for a numeral; if that prefix does not form a valid numeral (e.g., an empty string, @St{0x}, or @St{3.4e-}) or it is too long (more than 200 characters), -it is discarded and the format returns @nil. +it is discarded and the format returns @fail. } @item{@St{a}| reads the whole file, starting at the current position. -On end of file, it returns the empty string. +On end of file, it returns the empty string; +this format never fails. } @item{@St{l}| reads the next line skipping the end of line, -returning @nil on end of file. +returning @fail on end of file. This is the default format. } @item{@St{L}| reads the next line keeping the end-of-line character (if present), -returning @nil on end of file. +returning @fail on end of file. } @item{@emph{number}| reads a string with up to this number of bytes, -returning @nil on end of file. +returning @fail on end of file. If @id{number} is zero, it reads nothing and returns an empty string, -or @nil on end of file. +or @fail on end of file. } } @@ -8139,7 +8151,7 @@ specified by the string @id{whence}, as follows: } In case of success, @id{seek} returns the final file position, measured in bytes from the beginning of the file. -If @id{seek} fails, it returns @nil, +If @id{seek} fails, it returns @fail, plus a string describing the error. The default value for @id{whence} is @T{"cur"}, @@ -8179,7 +8191,6 @@ Writes the value of each of its arguments to @id{file}. The arguments must be strings or numbers. In case of success, this function returns @id{file}. -Otherwise it returns @nil plus a string describing the error. } @@ -8251,7 +8262,7 @@ This function is equivalent to the @ANSI{system}. It passes @id{command} to be executed by an operating system shell. Its first result is @true if the command terminated successfully, -or @nil otherwise. +or @fail otherwise. After this first result the function returns a string plus a number, as follows: @@ -8293,7 +8304,7 @@ closes the Lua state before exiting. @LibEntry{os.getenv (varname)| Returns the value of the process environment variable @id{varname}, -or @nil if the variable is not defined. +or @fail if the variable is not defined. } @@ -8301,7 +8312,7 @@ or @nil if the variable is not defined. Deletes the file (or empty directory, on @x{POSIX} systems) with the given name. -If this function fails, it returns @nil, +If this function fails, it returns @fail plus a string describing the error and the error code. Otherwise, it returns true. @@ -8310,7 +8321,7 @@ Otherwise, it returns true. @LibEntry{os.rename (oldname, newname)| Renames the file or directory named @id{oldname} to @id{newname}. -If this function fails, it returns @nil, +If this function fails, it returns @fail, plus a string describing the error and the error code. Otherwise, it returns true. @@ -8325,7 +8336,7 @@ Sets the current locale of the program. @T{"monetary"}, @T{"numeric"}, or @T{"time"}; the default category is @T{"all"}. The function returns the name of the new locale, -or @nil if the request cannot be honored. +or @fail if the request cannot be honored. If @id{locale} is the empty string, the current locale is set to an implementation-defined native locale. @@ -8444,6 +8455,8 @@ the current hook function, the current hook mask, and the current hook count, as set by the @Lid{debug.sethook} function. +Returns @fail if there is no active hook. + } @LibEntry{debug.getinfo ([thread,] f [, what])| @@ -8458,7 +8471,7 @@ of the given thread: (except for tail calls, which do not count on the stack); and so on. If @id{f} is a number greater than the number of active functions, -then @id{getinfo} returns @nil. +then @id{getinfo} returns @fail. The returned table can contain all the fields returned by @Lid{lua_getinfo}, with the string @id{what} describing which fields to fill in. @@ -8496,7 +8509,8 @@ Compile-time constants may not appear in this listing, if they were optimized away by the compiler. Negative indices refer to vararg arguments; @num{-1} is the first vararg argument. -The function returns @nil if there is no variable with the given index, +The function returns @fail +if there is no variable with the given index, and raises an error when called with a level out of range. (You can call @Lid{debug.getinfo} to check whether the level is valid.) @@ -8527,7 +8541,8 @@ Returns the registry table @see{registry}. This function returns the name and the value of the upvalue with index @id{up} of the function @id{f}. -The function returns @nil if there is no upvalue with the given index. +The function returns @fail +if there is no upvalue with the given index. (For Lua functions, upvalues are the external local variables that the function uses, @@ -8615,7 +8630,7 @@ and @N{level 1} is the hook function.) This function assigns the value @id{value} to the local variable with index @id{local} of the function at level @id{level} of the stack. -The function returns @nil if there is no local +The function returns @fail if there is no local variable with the given index, and raises an error when called with a @id{level} out of range. (You can call @id{getinfo} to check whether the level is valid.) @@ -8638,7 +8653,7 @@ Returns @id{value}. This function assigns the value @id{value} to the upvalue with index @id{up} of the function @id{f}. -The function returns @nil if there is no upvalue +The function returns @fail if there is no upvalue with the given index. Otherwise, it returns the name of the upvalue. @@ -8653,7 +8668,7 @@ the @id{n}-th user value associated to the given @id{udata}. @id{udata} must be a full userdata. Returns @id{udata}, -or @nil if the userdata does not have that value. +or @fail if the userdata does not have that value. } -- cgit v1.2.3-55-g6feb