From owner-dev-commits-src-all@freebsd.org Sat Dec 26 05:04:34 2020 Return-Path: Delivered-To: dev-commits-src-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 9A2754D6D2C for ; Sat, 26 Dec 2020 05:04:34 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4D2sDf3vygz4r5w; Sat, 26 Dec 2020 05:04:34 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 79084775D; Sat, 26 Dec 2020 05:04:34 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 0BQ54Yi8082664; Sat, 26 Dec 2020 05:04:34 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 0BQ54YSL082663; Sat, 26 Dec 2020 05:04:34 GMT (envelope-from git) Date: Sat, 26 Dec 2020 05:04:34 GMT Message-Id: <202012260504.0BQ54YSL082663@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org From: Kyle Evans Subject: git: 0ea45b9cd43c - Import lua 5.4.2 MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: kevans X-Git-Repository: src X-Git-Refname: refs/heads/vendor/lua X-Git-Reftype: branch X-Git-Commit: 0ea45b9cd43ce1247eb3eee9bfd5cee3d19068e7 Auto-Submitted: auto-generated X-BeenThere: dev-commits-src-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: "Commit messages for all branches of the src repository." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 26 Dec 2020 05:04:34 -0000 The branch vendor/lua has been updated by kevans: URL: https://cgit.FreeBSD.org/src/commit/?id=0ea45b9cd43ce1247eb3eee9bfd5cee3d19068e7 commit 0ea45b9cd43ce1247eb3eee9bfd5cee3d19068e7 Author: Kyle Evans AuthorDate: 2020-12-26 05:02:38 +0000 Commit: Kyle Evans CommitDate: 2020-12-26 05:02:38 +0000 Import lua 5.4.2 --- Makefile | 30 +- README | 2 +- doc/contents.html | 81 +- doc/lua.1 | 93 +- doc/manual.html | 3260 ++++++++++++++++++++++++++++++++++------------------- doc/readme.html | 115 +- src/Makefile | 83 +- src/lapi.c | 706 +++++++----- src/lapi.h | 27 +- src/lauxlib.c | 385 ++++--- src/lauxlib.h | 54 +- src/lbaselib.c | 139 ++- src/lbitlib.c | 233 ---- src/lcode.c | 1141 ++++++++++++++----- src/lcode.h | 34 +- src/lcorolib.c | 89 +- src/lctype.c | 43 +- src/lctype.h | 18 +- src/ldblib.c | 94 +- src/ldebug.c | 462 +++++--- src/ldebug.h | 21 +- src/ldo.c | 559 ++++----- src/ldo.h | 38 +- src/ldump.c | 197 ++-- src/lfunc.c | 223 +++- src/lfunc.h | 50 +- src/lgc.c | 1387 ++++++++++++++++------- src/lgc.h | 128 ++- src/linit.c | 7 +- src/liolib.c | 121 +- src/ljumptab.h | 112 ++ src/llex.c | 74 +- src/llex.h | 12 +- src/llimits.h | 132 ++- src/lmathlib.c | 433 ++++++- src/lmem.c | 178 ++- src/lmem.h | 72 +- src/loadlib.c | 261 ++--- src/lobject.c | 340 +++--- src/lobject.h | 737 ++++++++---- src/lopcodes.c | 190 ++-- src/lopcodes.h | 401 ++++--- src/lopnames.h | 103 ++ src/loslib.c | 85 +- src/lparser.c | 967 ++++++++++------ src/lparser.h | 80 +- src/lprefix.h | 4 +- src/lstate.c | 221 ++-- src/lstate.h | 202 +++- src/lstring.c | 135 ++- src/lstring.h | 22 +- src/lstrlib.c | 502 ++++++--- src/ltable.c | 692 ++++++++---- src/ltable.h | 22 +- src/ltablib.c | 52 +- src/ltm.c | 173 ++- src/ltm.h | 37 +- src/lua.c | 439 ++++---- src/lua.h | 60 +- src/luac.c | 470 ++++++-- src/luaconf.h | 253 ++--- src/lualib.h | 5 +- src/lundump.c | 266 +++-- src/lundump.h | 8 +- src/lutf8lib.c | 117 +- src/lvm.c | 1759 +++++++++++++++++++---------- src/lvm.h | 91 +- src/lzio.c | 2 +- src/lzio.h | 2 +- 69 files changed, 12722 insertions(+), 6809 deletions(-) diff --git a/Makefile b/Makefile index a2820e04fe24..36447a0f61c7 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,7 @@ # == CHANGE THE SETTINGS BELOW TO SUIT YOUR ENVIRONMENT ======================= # Your platform. See PLATS for possible values. -PLAT= none +PLAT= guess # Where to install. The installation starts in the src and doc directories, # so take care if INSTALL_TOP is not an absolute path. See the local target. @@ -36,7 +36,7 @@ RM= rm -f # == END OF USER SETTINGS -- NO NEED TO CHANGE ANYTHING BELOW THIS LINE ======= # Convenience platforms targets. -PLATS= aix bsd c89 freebsd generic linux macosx mingw posix solaris +PLATS= guess aix bsd c89 freebsd generic linux linux-readline macosx mingw posix solaris # What to install. TO_BIN= lua luac @@ -45,17 +45,14 @@ TO_LIB= liblua.a TO_MAN= lua.1 luac.1 # Lua version and release. -V= 5.3 -R= $V.6 +V= 5.4 +R= $V.2 # Targets start here. all: $(PLAT) -$(PLATS) clean: - cd src && $(MAKE) $@ - -test: dummy - src/lua -v +$(PLATS) help test clean: + @cd src && $(MAKE) $@ install: dummy cd src && $(MKDIR) $(INSTALL_BIN) $(INSTALL_INC) $(INSTALL_LIB) $(INSTALL_MAN) $(INSTALL_LMOD) $(INSTALL_CMOD) @@ -73,15 +70,10 @@ uninstall: local: $(MAKE) install INSTALL_TOP=../install -none: - @echo "Please do 'make PLATFORM' where PLATFORM is one of these:" - @echo " $(PLATS)" - @echo "See doc/readme.html for complete instructions." - -# make may get confused with test/ and install/ +# make may get confused with install/ if it does not support .PHONY. dummy: -# echo config parameters +# Echo config parameters. echo: @cd src && $(MAKE) -s echo @echo "PLAT= $(PLAT)" @@ -101,14 +93,14 @@ echo: @echo "INSTALL_EXEC= $(INSTALL_EXEC)" @echo "INSTALL_DATA= $(INSTALL_DATA)" -# echo pkg-config data +# Echo pkg-config data. pc: @echo "version=$R" @echo "prefix=$(INSTALL_TOP)" @echo "libdir=$(INSTALL_LIB)" @echo "includedir=$(INSTALL_INC)" -# list targets that do not create files (but not all makes understand .PHONY) -.PHONY: all $(PLATS) clean test install local none dummy echo pecho lecho +# Targets that do not create files (not all makes understand .PHONY). +.PHONY: all $(PLATS) help test clean install uninstall local dummy echo pc # (end of Makefile) diff --git a/README b/README index f8bdb6f41d00..bc8a9d737d26 100644 --- a/README +++ b/README @@ -1,5 +1,5 @@ -This is Lua 5.3.6, released on 14 Sep 2020. +This is Lua 5.4.2, released on 13 Nov 2020. 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 3a357b1ed653..8ea0616b25ce 100644 --- a/doc/contents.html +++ b/doc/contents.html @@ -1,7 +1,7 @@ -Lua 5.3 Reference Manual - contents +Lua 5.4 Reference Manual - contents @@ -11,7 +11,7 @@

Lua -Lua 5.3 Reference Manual +Lua 5.4 Reference Manual

@@ -32,7 +32,7 @@ For a complete introduction to Lua programming, see the book

-Copyright © 2015–2020 Lua.org, PUC-Rio. +Copyright © 2020 Lua.org, PUC-Rio. Freely available under the terms of the Lua license. @@ -49,8 +49,10 @@ Freely available under the terms of the

  • 2.4 – Metatables and Metamethods
  • 2.5 – Garbage Collection
  • 2.6 – Coroutines @@ -68,6 +70,7 @@ Freely available under the terms of the
  • 3.3.5 – For Statement
  • 3.3.6 – Function Calls as Statements
  • 3.3.7 – Local Declarations +
  • 3.3.8 – To-be-closed Variables
  • 3.4 – Expressions

    -

  • 6 – Standard Libraries +
  • 6 – The Standard Libraries
    • 6.1 – Basic Functions
    • 6.2 – Coroutine Manipulation @@ -126,9 +135,9 @@ Freely available under the terms of the

    • 8 – Incompatibilities with the Previous Version

    • 9 – The Complete Syntax of Lua @@ -165,10 +174,12 @@ Freely available under the terms of the tonumber
      tostring
      type
      +warn
      xpcall

      coroutine
      +coroutine.close
      coroutine.create
      coroutine.isyieldable
      coroutine.resume
      @@ -326,10 +337,11 @@ Freely available under the terms of the __bor
      __bxor
      __call
      +__close
      __concat
      __div
      __eq
      -__gc
      +__gc
      __idiv
      __index
      __le
      @@ -337,7 +349,7 @@ Freely available under the terms of the __lt
      __metatable
      __mod
      -__mode
      +__mode
      __mul
      __name
      __newindex
      @@ -352,11 +364,11 @@ Freely available under the terms of the

      environment
      variables

      LUA_CPATH
      -LUA_CPATH_5_3
      +LUA_CPATH_5_4
      LUA_INIT
      -LUA_INIT_5_3
      +LUA_INIT_5_4
      LUA_PATH
      -LUA_PATH_5_3
      +LUA_PATH_5_4
      @@ -373,6 +385,7 @@ Freely available under the terms of the lua_Reader
      lua_State
      lua_Unsigned
      +lua_WarnFunction
      lua_Writer

      @@ -399,13 +412,13 @@ Freely available under the terms of the lua_gethookmask
      lua_geti
      lua_getinfo
      +lua_getiuservalue
      lua_getlocal
      lua_getmetatable
      lua_getstack
      lua_gettable
      lua_gettop
      lua_getupvalue
      -lua_getuservalue
      lua_insert
      lua_isboolean
      lua_iscfunction
      @@ -426,7 +439,7 @@ Freely available under the terms of the lua_newstate
      lua_newtable
      lua_newthread
      -lua_newuserdata
      +lua_newuserdatauv
      lua_next
      lua_numbertointeger
      lua_pcall
      @@ -458,6 +471,7 @@ Freely available under the terms of the lua_register
      lua_remove
      lua_replace
      +lua_resetthread
      lua_resume
      lua_rotate
      lua_setallocf
      @@ -465,16 +479,18 @@ Freely available under the terms of the lua_setglobal
      lua_sethook
      lua_seti
      +lua_setiuservalue
      lua_setlocal
      lua_setmetatable
      lua_settable
      lua_settop
      lua_setupvalue
      -lua_setuservalue
      +lua_setwarnf
      lua_status
      lua_stringtonumber
      lua_toboolean
      lua_tocfunction
      +lua_toclose
      lua_tointeger
      lua_tointegerx
      lua_tolstring
      @@ -490,6 +506,7 @@ Freely available under the terms of the lua_upvalueindex
      lua_upvaluejoin
      lua_version
      +lua_warning
      lua_xmove
      lua_yield
      lua_yieldk
      @@ -504,14 +521,19 @@ Freely available under the terms of the

      luaL_addchar
      +luaL_addgsub
      luaL_addlstring
      luaL_addsize
      luaL_addstring
      luaL_addvalue
      luaL_argcheck
      luaL_argerror
      +luaL_argexpected
      +luaL_buffaddr
      luaL_buffinit
      luaL_buffinitsize
      +luaL_bufflen
      +luaL_buffsub
      luaL_callmeta
      luaL_checkany
      luaL_checkinteger
      @@ -550,6 +572,7 @@ Freely available under the terms of the luaL_optstring
      luaL_prepbuffer
      luaL_prepbuffsize
      +luaL_pushfail
      luaL_pushresult
      luaL_pushresultsize
      luaL_ref
      @@ -559,6 +582,7 @@ Freely available under the terms of the luaL_testudata
      luaL_tolstring
      luaL_traceback
      +luaL_typeerror
      luaL_typename
      luaL_unref
      luaL_where
      @@ -580,7 +604,6 @@ Freely available under the terms of the

      LUA_ERRERR
      LUA_ERRFILE
      -LUA_ERRGCMM
      LUA_ERRMEM
      LUA_ERRRUN
      LUA_ERRSYNTAX
      @@ -589,6 +612,7 @@ Freely available under the terms of the LUA_HOOKLINE
      LUA_HOOKRET
      LUA_HOOKTAILCALL
      +LUAL_BUFFERSIZE
      LUA_MASKCALL
      LUA_MASKCOUNT
      LUA_MASKLINE
      @@ -632,7 +656,6 @@ Freely available under the terms of the LUA_TUSERDATA
      LUA_USE_APICHECK
      LUA_YIELD
      -LUAL_BUFFERSIZE
      @@ -640,10 +663,10 @@ Freely available under the terms of the

      Last update: -Tue Aug 25 13:45:14 UTC 2020 +Tue Nov 10 20:58:52 UTC 2020

      diff --git a/doc/lua.1 b/doc/lua.1 index d728d0b80c17..a46a1a67dd04 100644 --- a/doc/lua.1 +++ b/doc/lua.1 @@ -1,5 +1,5 @@ -.\" $Id: lua.man,v 1.14 2016/10/17 15:43:50 lhf Exp $ -.TH LUA 1 "$Date: 2016/10/17 15:43:50 $" +.\" $Id: lua.man,v 1.14 2020/05/21 19:31:21 lhf Exp $ +.TH LUA 1 "$Date: 2020/05/21 19:31:21 $" .SH NAME lua \- Lua interpreter .SH SYNOPSIS @@ -25,52 +25,57 @@ the Lua compiler.) .B lua can be used as a batch interpreter and also interactively. .LP -The given -.I options -are handled in order and then +After handling the +.IR options , the Lua program in file .I script is loaded and executed. -The given +The .I args are available to .I script as strings in a global table named -.BR arg . -If no options or arguments are given, -then -.B "\-v \-i" -is assumed when the standard input is a terminal; -otherwise, -.B "\-" -is assumed. +.B arg +and also as arguments to its main function. +When called without arguments, +.B lua +behaves as +.B "lua \-v \-i" +if the standard input is a terminal, +and as +.B "lua \-" +otherwise. .LP In interactive mode, .B lua prompts the user, reads lines from the standard input, and executes them as they are read. -If the line contains an expression or list of expressions, -then the line is evaluated and the results are printed. +If the line contains an expression, +then the line is evaluated and the result is printed. If a line does not contain a complete statement, then a secondary prompt is displayed and lines are read until a complete statement is formed or a syntax error is found. .LP -At the very start, -before even handling the command line, +Before handling command line options and scripts, .B lua checks the contents of the environment variables -.B LUA_INIT_5_3 -or +.B LUA_INIT_5_4 +and .BR LUA_INIT , in that order. -If the contents is of the form +If the contents are of the form .RI '@ filename ', then .I filename is executed. -Otherwise, the string is assumed to be a Lua statement and is executed. +Otherwise, the contents are assumed to be a Lua statement and is executed. +When +.B LUA_INIT_5_4 +is defined, +.B LUA_INIT +is ignored. .SH OPTIONS .TP .BI \-e " stat" @@ -82,10 +87,10 @@ enter interactive mode after executing .IR script . .TP .BI \-l " name" -execute the equivalent of -.IB name =require(' name ') -before executing -.IR script . +require library +.I name +into global +.IR name . .TP .B \-v show version information. @@ -93,18 +98,50 @@ show version information. .B \-E ignore environment variables. .TP +.B \-W +turn warnings on. +.TP .B \-\- stop handling options. .TP .B \- stop handling options and execute the standard input as a file. +.SH ENVIRONMENT VARIABLES +The following environment variables affect the execution of +.BR lua . +When defined, +the version-specific variants take priority +and the version-neutral variants are ignored. +.TP +.B LUA_INIT, LUA_INIT_5_4 +Code to be executed before command line options and scripts. +.TP +.B LUA_PATH, LUA_PATH_5_4 +Initial value of package.cpath, +the path used by require to search for Lua loaders. +.TP +.B LUA_CPATH, LUA_CPATH_5_4 +Initial value of package.cpath, +the path used by require to search for C loaders. +.SH EXIT STATUS +If a script calls os.exit, +then +.B lua +exits with the given exit status. +Otherwise, +.B lua +exits +with EXIT_SUCCESS (0 on POSIX systems) if there were no errors +and +with EXIT_FAILURE (1 on POSIX systems) if there were errors. +Errors raised in interactive mode do not cause exits. +.SH DIAGNOSTICS +Error messages should be self explanatory. .SH "SEE ALSO" .BR luac (1) .br The documentation at lua.org, especially section 7 of the reference manual. -.SH DIAGNOSTICS -Error messages should be self explanatory. .SH AUTHORS R. Ierusalimschy, L. H. de Figueiredo, diff --git a/doc/manual.html b/doc/manual.html index 57c778744b7a..6de396c41d1c 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -1,7 +1,7 @@ -Lua 5.3 Reference Manual +Lua 5.4 Reference Manual @@ -11,7 +11,7 @@

      Lua -Lua 5.3 Reference Manual +Lua 5.4 Reference Manual

      @@ -19,7 +19,7 @@ by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes

      -Copyright © 2015–2020 Lua.org, PUC-Rio. +Copyright © 2020 Lua.org, PUC-Rio. Freely available under the terms of the Lua license. @@ -35,7 +35,7 @@ Freely available under the terms of the

      - + @@ -56,7 +56,7 @@ Lua is dynamically typed, runs by interpreting bytecode with a register-based virtual machine, and has automatic memory management with -incremental garbage collection, +a generational garbage collection, making it ideal for configuration, scripting, and rapid prototyping. @@ -106,15 +106,19 @@ see Roberto's book, Programming in Lua.

      2 – Basic Concepts

      + +

      This section describes the basic concepts of the language. + +

      2.1 – Values and Types

      -Lua is a dynamically typed language. +Lua is a dynamically typed language. This means that variables do not have types; only values do. There are no type definitions in the language. @@ -122,7 +126,7 @@ All values carry their own type.

      -All values in Lua are first-class values. +All values in Lua are first-class values. This means that all values can be stored in variables, passed as arguments to other functions, and returned as results. @@ -134,31 +138,17 @@ There are eight basic types in Lua: thread, and table. The type nil has one single value, nil, whose main property is to be different from any other value; -it usually represents the absence of a useful value. +it often represents the absence of a useful value. The type boolean has two values, false and true. Both nil and false make a condition false; -any other value makes it true. -The type number represents both -integer numbers and real (floating-point) numbers. -The type string represents immutable sequences of bytes. - -Lua is 8-bit clean: -strings can contain any 8-bit value, -including embedded zeros ('\0'). -Lua is also encoding-agnostic; -it makes no assumptions about the contents of a string. +they are collectively called false values. +Any other value makes a condition true.

      -The type number uses two internal representations, -or two subtypes, -one called integer and the other called float. -Lua has explicit rules about when each representation is used, -but it also converts between them automatically as needed (see §3.4.3). -Therefore, -the programmer may choose to mostly ignore the difference -between integers and floats -or to assume complete control over the representation of each number. +The type number represents both +integer numbers and real (floating-point) numbers, +using two subtypes: integer and float. 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. @@ -168,6 +158,36 @@ for small machines and embedded systems. (See macro LUA_32BITS in file luaconf.h.) +

      +Unless stated otherwise, +any overflow when manipulating integer values wrap around, +according to the usual rules of two-complement arithmetic. +(In other words, +the actual result is the unique representable integer +that is equal modulo 2n to the mathematical result, +where n is the number of bits of the integer type.) + + +

      +Lua has explicit rules about when each subtype is used, +but it also converts between them automatically as needed (see §3.4.3). +Therefore, +the programmer may choose to mostly ignore the difference +between integers and floats +or to assume complete control over the representation of each number. + + +

      +The type string represents immutable sequences of bytes. + +Lua is 8-bit clean: +strings can contain any 8-bit value, +including embedded zeros ('\0'). +Lua is also encoding-agnostic; +it makes no assumptions about the contents of a string. +The length of any string in Lua must fit in a Lua integer. + +

      Lua can call (and manipulate) functions written in Lua and functions written in C (see §3.4.10). @@ -190,7 +210,8 @@ the programmer can define operations for full userdata values (see §2.4). Userdata values cannot be created or modified in Lua, only through the C API. -This guarantees the integrity of data owned by the host program. +This guarantees the integrity of data owned by +the host program and C libraries.

      @@ -205,11 +226,12 @@ even those that do not support threads natively. The type table implements associative arrays, that is, arrays that can have as indices not only numbers, but any Lua value except nil and NaN. -(Not a Number is a special value used to represent -undefined or unrepresentable numerical results, such as 0/0.) +(Not a Number is a special floating-point value +used by the IEEE 754 standard to represent +undefined numerical results, such as 0/0.) Tables can be heterogeneous; that is, they can contain values of all types (except nil). -Any key with value nil is not considered part of the table. +Any key associated to the value nil is not considered part of the table. Conversely, any key that is not part of a table has an associated value nil. @@ -245,14 +267,10 @@ In particular, floats with integral values are equal to their respective integers (e.g., 1.0 == 1). To avoid ambiguities, -any float with integral value used as a key -is converted to its respective integer. +any float used as a key that is equal to an integer +is converted to that integer. For instance, if you write a[2.0] = true, -the actual key inserted into the table will be the -integer 2. -(On the other hand, -2 and "2" are different Lua values and therefore -denote different table entries.) +the actual key inserted into the table will be the integer 2.

      @@ -266,7 +284,7 @@ these operations do not imply any kind of copy.

      The library function type returns a string describing the type -of a given value (see §6.1). +of a given value (see type). @@ -275,7 +293,7 @@ of a given value (see §6.1).

      2.2 – Environments and the Global Environment

      -As will be discussed in §3.2 and §3.3.3, +As we will discuss further in §3.2 and §3.3.3, any reference to a free name (that is, a name not bound to any declaration) var is syntactically translated to _ENV.var. @@ -301,24 +319,25 @@ Any table used as the value of _ENV is called an environment Lua keeps a distinguished environment called the global environment. -This value is kept at a special index in the C registry (see §4.5). +This value is kept at a special index in the C registry (see §4.3). In Lua, the global variable _G is initialized with this same value. -(_G is never used internally.) +(_G is never used internally, +so changing its value will affect only your own code.)

      When Lua loads a chunk, -the default value for its _ENV upvalue +the default value for its _ENV variable is the global environment (see load). Therefore, by default, free names in Lua code refer to entries in the global environment -(and, therefore, they are also called global variables). +and, therefore, they are also called global variables. Moreover, all standard libraries are loaded in the global environment and some functions there operate on that environment. You can use load (or loadfile) to load a chunk with a different environment. (In C, you have to load the chunk and then change the value -of its first upvalue.) +of its first upvalue; see lua_setupvalue.) @@ -326,39 +345,57 @@ of its first upvalue.)

      2.3 – Error Handling

      +

      +Several operations in Lua can raise an error. +An error interrupts the normal flow of the program, +which can continue by catching the error. + + +

      +Lua code can explicitly raise an error by calling the +error function. +(This function never returns.) + + +

      +To catch errors in Lua, +you can do a protected call, +using pcall (or xpcall). +The function pcall calls a given function in protected mode. +Any error while running the function stops its execution, +and control returns immediately to pcall, +which returns a status code. + +

      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. +Lua code starts running by a call +from C code in the host program. (When you use Lua standalone, the lua application is the host program.) -Whenever an error occurs during +Usually, this call is protected; +so, when an otherwise unprotected error occurs during the compilation or execution of a Lua chunk, control returns to the host, -which can take appropriate measures -(such as printing an error message). - - -

      -Lua code can explicitly generate an error by calling the -error function. -If you need to catch errors in Lua, -you can use pcall or xpcall -to call a given function in protected mode. +which can take appropriate measures, +such as printing an error message.

      Whenever there is an error, -an error object (also called an error message) +an error object is propagated with information about the error. Lua itself only generates errors whose error object is a string, but programs may generate errors with any value as the error object. It is up to the Lua program or its host to handle such error objects. +For historical reasons, +an error object is often called an error message, +even though it does not have to be a string.

      -When you use xpcall or lua_pcall, +When you use xpcall (or lua_pcall, in C) you may give a message handler to be called in case of errors. This function is called with the original error object @@ -371,9 +408,17 @@ so, an error inside the message handler will call the message handler again. If this loop goes on for too long, 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 -nor for errors while running finalizers.) +nor for errors while running finalizers or other message handlers. + + +

      +Lua also offers a system of warnings (see warn). +Unlike errors, warnings do not interfere +in any way with program execution. +They typically only generate a message to the user, +although this behavior can be adapted from C (see lua_setwarnf). @@ -385,9 +430,9 @@ nor for errors while running finalizers.) Every value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value -under certain special operations. +under certain events. You can change several aspects of the behavior -of operations over a value by setting specific fields in its metatable. +of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, @@ -397,35 +442,32 @@ Lua calls this function to perform the addition.

      The key for each event in a metatable is a string with the event name prefixed by two underscores; -the corresponding values are called metamethods. -In the previous example, the key is "__add" +the corresponding value is called a metavalue. +For most events, the metavalue must be a function, +which is then called a metamethod. *** 31822 LINES SKIPPED ***