rusefi
/
lua
mirror of https://github.com/rusefi/lua.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Several enhancements in the manual

This commit is contained in:
Roberto Ierusalimschy 2019-10-23 10:41:47 -03:00
parent 6e285e5392
commit 4c32d9300c
1 changed files with 54 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
manual/manual.of
View File

@ -82,7 +82,8 @@ whose main property is to be different from any other value;
it often represents the absence of a useful value. it often represents the absence of a useful value.
The type @emph{boolean} has two values, @false and @true. The type @emph{boolean} has two values, @false and @true.
Both @nil and @false make a condition false; Both @nil and @false make a condition false;
any other value makes it true. they are collectively called @def{false values}.
Any other value makes a condition true.
The type @emph{number} represents both The type @emph{number} represents both
integer numbers and real (floating-point) numbers, integer numbers and real (floating-point) numbers,
@ -278,9 +279,9 @@ so, an error inside the message handler
will call the message handler again. will call the message handler again.
If this loop goes on for too long, If this loop goes on for too long,
Lua breaks it and returns an appropriate message. Lua breaks it and returns an appropriate message.
(The message handler is called only for regular runtime errors. The message handler is called only for regular runtime errors.
It is not called for memory-allocation errors It is not called for memory-allocation errors
nor for errors while running finalizers.) nor for errors while running finalizers or other message handlers.
Lua also offers a system of @emph{warnings} @seeF{warn}. Lua also offers a system of @emph{warnings} @seeF{warn}.
Unlike errors, warnings do not interfere Unlike errors, warnings do not interfere
@ -467,7 +468,7 @@ Behavior similar to the less than operation.
The indexing access operation @T{table[key]}. The indexing access operation @T{table[key]}.
This event happens when @id{table} is not a table or This event happens when @id{table} is not a table or
when @id{key} is not present in @id{table}. when @id{key} is not present in @id{table}.
The metamethod is looked up in @id{table}. The metamethod is looked up in the metatable of @id{table}.
Despite the name, Despite the name,
the metamethod for this event can be either a function or a table. the metamethod for this event can be either a function or a table.
@ -528,7 +529,7 @@ the interpreter also respects the following keys in metatables:
and @idx{__name}. and @idx{__name}.
(The entry @idx{__name}, (The entry @idx{__name},
when it contains a string, when it contains a string,
is used by some error-reporting functions to build error messages.) may be used by @Lid{tostring} and in error messages.)
For the unary operators (negation, length, and bitwise NOT), For the unary operators (negation, length, and bitwise NOT),
the metamethod is computed and called with a dummy second operand, the metamethod is computed and called with a dummy second operand,
@ -638,7 +639,7 @@ In generational mode,
the collector does frequent @emph{minor} collections, the collector does frequent @emph{minor} collections,
which traverses only objects recently created. which traverses only objects recently created.
If after a minor collection the use of memory is still above a limit, If after a minor collection the use of memory is still above a limit,
the collector does a @emph{major} collection, the collector does a stop-the-world @emph{major} collection,
which traverses all objects. which traverses all objects.
The generational mode uses two parameters: The generational mode uses two parameters:
the @def{minor multiplier} and the @def{the major multiplier}. the @def{minor multiplier} and the @def{the major multiplier}.
@ -943,7 +944,7 @@ Lua is a @x{free-form} language.
It ignores spaces and comments between lexical elements (@x{tokens}), It ignores spaces and comments between lexical elements (@x{tokens}),
except as delimiters between two tokens. except as delimiters between two tokens.
In source code, In source code,
Lua recognizes as spaces the standard ASCII white-space Lua recognizes as spaces the standard ASCII whitespace
characters space, form feed, newline, characters space, form feed, newline,
carriage return, horizontal tab, and vertical tab. carriage return, horizontal tab, and vertical tab.
@ -998,7 +999,7 @@ and @Char{\'} (apostrophe [single quote]).
A backslash followed by a line break A backslash followed by a line break
results in a newline in the string. results in a newline in the string.
The escape sequence @Char{\z} skips the following span The escape sequence @Char{\z} skips the following span
of white-space characters, of whitespace characters,
including line breaks; including line breaks;
it is particularly useful to break and indent a long literal string it is particularly useful to break and indent a long literal string
into multiple lines without adding the newlines and spaces into multiple lines without adding the newlines and spaces
@ -1769,7 +1770,7 @@ Otherwise, the conversion fails.
Several places in Lua coerce strings to numbers when necessary. Several places in Lua coerce strings to numbers when necessary.
A string is converted to an integer or a float A string is converted to an integer or a float
following its syntax and the rules of the Lua lexer. following its syntax and the rules of the Lua lexer.
(The string may have also leading and trailing spaces and a sign.) (The string may have also leading and trailing whitespaces and a sign.)
All conversions from strings to numbers All conversions from strings to numbers
accept both a dot and the current locale mark accept both a dot and the current locale mark
as the radix character. as the radix character.
@ -2182,7 +2183,7 @@ function r() return 1,2,3 end
Then, we have the following mapping from arguments to parameters and Then, we have the following mapping from arguments to parameters and
to the vararg expression: to the vararg expression:
@verbatim{ @verbatim{
CALL PARAMETERS CALL PARAMETERS
f(3) a=3, b=nil f(3) a=3, b=nil
f(3, 4) a=3, b=4 f(3, 4) a=3, b=4
@ -2802,9 +2803,13 @@ Sets a new panic function and returns the old one @see{C-error}.
@apii{nargs+1,nresults,e} @apii{nargs+1,nresults,e}
Calls a function. Calls a function.
Like regular Lua calls,
@id{lua_call} respects the @idx{__call} metamethod.
So, here the word @Q{function}
means any callable value.
To do a call you must use the following protocol: To do a call you must use the following protocol:
first, the value to be called is pushed onto the stack; first, the function to be called is pushed onto the stack;
then, the arguments to the call are pushed then, the arguments to the call are pushed
in direct order; in direct order;
that is, the first argument is pushed first. that is, the first argument is pushed first.
@ -2812,7 +2817,7 @@ Finally you call @Lid{lua_call};
@id{nargs} is the number of arguments that you pushed onto the stack. @id{nargs} is the number of arguments that you pushed onto the stack.
When the function returns, When the function returns,
all arguments and the function value are popped all arguments and the function value are popped
and the function results are pushed onto the stack. and the call results are pushed onto the stack.
The number of results is adjusted to @id{nresults}, The number of results is adjusted to @id{nresults},
unless @id{nresults} is @defid{LUA_MULTRET}. unless @id{nresults} is @defid{LUA_MULTRET}.
In this case, all results from the function are pushed; In this case, all results from the function are pushed;
@ -2824,8 +2829,6 @@ so that after the call the last result is on the top of the stack.
Any error while calling and running the function is propagated upwards Any error while calling and running the function is propagated upwards
(with a @id{longjmp}). (with a @id{longjmp}).
Like regular Lua calls,
this function respects the @idx{__call} metamethod.
The following example shows how the host program can do the The following example shows how the host program can do the
equivalent to this Lua code: equivalent to this Lua code:
@ -3971,7 +3974,8 @@ leaves the error object on the top of the stack,
Starts and resumes a coroutine in the given thread @id{L}. Starts and resumes a coroutine in the given thread @id{L}.
To start a coroutine, To start a coroutine,
you push onto the thread stack the main function plus any arguments; you push the main function plus any arguments
onto the empty stack of the thread.
then you call @Lid{lua_resume}, then you call @Lid{lua_resume},
with @id{nargs} being the number of arguments. with @id{nargs} being the number of arguments.
This call returns when the coroutine suspends or finishes its execution. This call returns when the coroutine suspends or finishes its execution.
@ -3988,8 +3992,9 @@ or an error code in case of errors @seeC{lua_pcall}.
In case of errors, In case of errors,
the error object is on the top of the stack. the error object is on the top of the stack.
To resume a coroutine, you clear its stack, To resume a coroutine,
push only the values to be passed as results from @id{yield}, you remove the @id{*nresults} yielded values from its stack,
push the values to be passed as results from @id{yield},
and then call @Lid{lua_resume}. and then call @Lid{lua_resume}.
The parameter @id{from} represents the coroutine that is resuming @id{L}. The parameter @id{from} represents the coroutine that is resuming @id{L}.
@ -4152,7 +4157,7 @@ and returns the total size of the string,
that is, its length plus one. that is, its length plus one.
The conversion can result in an integer or a float, The conversion can result in an integer or a float,
according to the lexical conventions of Lua @see{lexical}. according to the lexical conventions of Lua @see{lexical}.
The string may have leading and trailing spaces and a sign. The string may have leading and trailing whitespaces and a sign.
If the string is not a valid numeral, If the string is not a valid numeral,
returns 0 and pushes nothing. returns 0 and pushes nothing.
(Note that the result can be used as a boolean, (Note that the result can be used as a boolean,
@ -5791,7 +5796,7 @@ The field @id{closef} points to a Lua function
that will be called to close the stream that will be called to close the stream
when the handle is closed or collected; when the handle is closed or collected;
this function receives the file handle as its sole argument and this function receives the file handle as its sole argument and
must return either @true, in case of success, must return either a true value, in case of success,
or a false value 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, Once Lua calls this field,
it changes the field value to @id{NULL} it changes the field value to @id{NULL}
@ -5914,12 +5919,12 @@ to its expected parameters.
For instance, a function documented as @T{foo(arg)} For instance, a function documented as @T{foo(arg)}
should not be called without an argument. should not be called without an argument.
The notation @fail means a return value representing The notation @fail means a false value representing
some kind of failure or the absence of a better value to return. some kind of failure.
Currently, @fail is equal to @nil, (Currently, @fail is equal to @nil,
but that may change in future versions. but that may change in future versions.
The recommendation is to always test the success of these functions The recommendation is to always test the success of these functions
with @T{(not status)}, instead of @T{(status == nil)}. with @T{(not status)}, instead of @T{(status == nil)}.)
Currently, Lua has the following standard libraries: Currently, Lua has the following standard libraries:
@ -6338,19 +6343,25 @@ the function returns @fail.
} }
@LibEntry{tostring (v)| @LibEntry{tostring (v)|
Receives a value of any type and Receives a value of any type and
converts it to a string in a human-readable format. converts it to a string in a human-readable format.
(For complete control of how numbers are converted,
use @Lid{string.format}.)
If the metatable of @id{v} has a @idx{__tostring} field, If the metatable of @id{v} has a @idx{__tostring} field,
then @id{tostring} calls the corresponding value then @id{tostring} calls the corresponding value
with @id{v} as argument, with @id{v} as argument,
and uses the result of the call as its result. and uses the result of the call as its result.
Otherwise, if the metatable of @id{v} has a @idx{__name} field
with a string value,
@id{tostring} may use that string in its final result.
For complete control of how numbers are converted,
use @Lid{string.format}.
} }
@LibEntry{type (v)| @LibEntry{type (v)|
Returns the type of its only argument, coded as a string. Returns the type of its only argument, coded as a string.
The possible results of this function are The possible results of this function are
@St{nil} (a string, not the value @nil), @St{nil} (a string, not the value @nil),
@ -6599,7 +6610,8 @@ Default is @Char{-}.}
@LibEntry{package.cpath| @LibEntry{package.cpath|
The path used by @Lid{require} to search for a @N{C loader}. A string with the path used by @Lid{require}
to search for a @N{C loader}.
Lua initializes the @N{C path} @Lid{package.cpath} in the same way Lua initializes the @N{C path} @Lid{package.cpath} in the same way
it initializes the Lua path @Lid{package.path}, it initializes the Lua path @Lid{package.path},
@ -6656,7 +6668,8 @@ plus other Unix systems that support the @id{dlfcn} standard).
@LibEntry{package.path| @LibEntry{package.path|
The path used by @Lid{require} to search for a Lua loader. A string with the path used by @Lid{require}
to search for a Lua loader.
At start-up, Lua initializes this variable with At start-up, Lua initializes this variable with
the value of the environment variable @defid{LUA_PATH_5_4} or the value of the environment variable @defid{LUA_PATH_5_4} or
@ -7397,7 +7410,7 @@ coded as an unsigned integer with @id{n} bytes
@item{@T{X@rep{op}}|an empty item that aligns @item{@T{X@rep{op}}|an empty item that aligns
according to option @id{op} according to option @id{op}
(which is otherwise ignored)} (which is otherwise ignored)}
@item{@Char{ }|(empty space) ignored} @item{@Char{ }|(space) ignored}
} }
(A @St{[@rep{n}]} means an optional integral numeral.) (A @St{[@rep{n}]} means an optional integral numeral.)
Except for padding, spaces, and configurations Except for padding, spaces, and configurations
@ -8106,7 +8119,7 @@ The available formats are
@item{@St{n}| @item{@St{n}|
reads a numeral and returns it as a float or an integer, reads a numeral and returns it as a float or an integer,
following the lexical conventions of Lua. following the lexical conventions of Lua.
(The numeral may have leading spaces and a sign.) (The numeral may have leading whitespaces and a sign.)
This format always reads the longest input sequence that This format always reads the longest input sequence that
is a valid prefix for a numeral; is a valid prefix for a numeral;
if that prefix does not form a valid numeral if that prefix does not form a valid numeral
@ -8594,7 +8607,7 @@ This function has the following restrictions:
@item{@id{limit} cannot be less than the amount of C stack in use.} @item{@id{limit} cannot be less than the amount of C stack in use.}
} }
If a call does not respect some restriction, If a call does not respect some restriction,
it returns a falsy value. it returns a false value.
Otherwise, Otherwise,
the call returns the old limit. the call returns the old limit.
@ -8736,15 +8749,15 @@ lua [options] [script [args]]
} }
The options are: The options are:
@description{ @description{
@item{@T{-e @rep{stat}}| executes string @rep{stat};} @item{@T{-e @rep{stat}}| execute string @rep{stat};}
@item{@T{-l @rep{mod}}| @Q{requires} @rep{mod} and assigns the @item{@T{-i}| enter interactive mode after running @rep{script};}
@item{@T{-l @rep{mod}}| @Q{require} @rep{mod} and assign the
result to global @rep{mod};} result to global @rep{mod};}
@item{@T{-i}| enters interactive mode after running @rep{script};} @item{@T{-v}| print version information;}
@item{@T{-v}| prints version information;} @item{@T{-E}| ignore environment variables;}
@item{@T{-E}| ignores environment variables;}
@item{@T{-W}| turn warnings on;} @item{@T{-W}| turn warnings on;}
@item{@T{--}| stops handling options;} @item{@T{--}| stop handling options;}
@item{@T{-}| executes @id{stdin} as a file and stops handling options.} @item{@T{-}| execute @id{stdin} as a file and stop handling options.}
} }
After handling its options, @id{lua} runs the given @emph{script}. After handling its options, @id{lua} runs the given @emph{script}.
When called without arguments, When called without arguments,
@ -8761,12 +8774,10 @@ then @id{lua} executes the file.
Otherwise, @id{lua} executes the string itself. Otherwise, @id{lua} executes the string itself.
When called with the option @T{-E}, When called with the option @T{-E},
besides ignoring @id{LUA_INIT}, Lua does not consult any environment variables.
Lua also ignores In particular,
the values of @id{LUA_PATH} and @id{LUA_CPATH}, the values of @Lid{package.path} and @Lid{package.cpath}
setting the values of are set with the default paths defined in @id{luaconf.h}.
@Lid{package.path} and @Lid{package.cpath}
with the default paths defined in @id{luaconf.h}.
The options @T{-e}, @T{-l}, and @T{-W} are handled in The options @T{-e}, @T{-l}, and @T{-W} are handled in
the order they appear. the order they appear.