svn commit: r326344 - in vendor/lua/dist: . doc src
Warner Losh
imp at FreeBSD.org
Tue Nov 28 22:55:34 UTC 2017
Author: imp
Date: Tue Nov 28 22:55:31 2017
New Revision: 326344
URL: https://svnweb.freebsd.org/changeset/base/326344
Log:
Import Lua 3.5.4
Downloaded from https://www.lua.org/ftp/lua-5.3.4.tar.gz
Added:
vendor/lua/dist/doc/index.css (contents, props changed)
Modified:
vendor/lua/dist/Makefile
vendor/lua/dist/README
vendor/lua/dist/doc/contents.html
vendor/lua/dist/doc/logo.gif
vendor/lua/dist/doc/lua.1
vendor/lua/dist/doc/lua.css
vendor/lua/dist/doc/manual.css
vendor/lua/dist/doc/manual.html
vendor/lua/dist/doc/readme.html
vendor/lua/dist/src/Makefile
vendor/lua/dist/src/lapi.c
vendor/lua/dist/src/lapi.h
vendor/lua/dist/src/lauxlib.c
vendor/lua/dist/src/lauxlib.h
vendor/lua/dist/src/lbaselib.c
vendor/lua/dist/src/lbitlib.c
vendor/lua/dist/src/lcode.c
vendor/lua/dist/src/lcode.h
vendor/lua/dist/src/lcorolib.c
vendor/lua/dist/src/ldblib.c
vendor/lua/dist/src/ldebug.c
vendor/lua/dist/src/ldebug.h
vendor/lua/dist/src/ldo.c
vendor/lua/dist/src/ldo.h
vendor/lua/dist/src/ldump.c
vendor/lua/dist/src/lfunc.h
vendor/lua/dist/src/lgc.c
vendor/lua/dist/src/lgc.h
vendor/lua/dist/src/linit.c
vendor/lua/dist/src/liolib.c
vendor/lua/dist/src/llex.c
vendor/lua/dist/src/llex.h
vendor/lua/dist/src/llimits.h
vendor/lua/dist/src/lmathlib.c
vendor/lua/dist/src/lmem.c
vendor/lua/dist/src/loadlib.c
vendor/lua/dist/src/lobject.c
vendor/lua/dist/src/lobject.h
vendor/lua/dist/src/lopcodes.h
vendor/lua/dist/src/loslib.c
vendor/lua/dist/src/lparser.c
vendor/lua/dist/src/lparser.h
vendor/lua/dist/src/lstate.c
vendor/lua/dist/src/lstate.h
vendor/lua/dist/src/lstring.c
vendor/lua/dist/src/lstring.h
vendor/lua/dist/src/lstrlib.c
vendor/lua/dist/src/ltable.c
vendor/lua/dist/src/ltable.h
vendor/lua/dist/src/ltablib.c
vendor/lua/dist/src/ltm.c
vendor/lua/dist/src/ltm.h
vendor/lua/dist/src/lua.c
vendor/lua/dist/src/lua.h
vendor/lua/dist/src/luac.c
vendor/lua/dist/src/luaconf.h
vendor/lua/dist/src/lualib.h
vendor/lua/dist/src/lundump.c
vendor/lua/dist/src/lundump.h
vendor/lua/dist/src/lutf8lib.c
vendor/lua/dist/src/lvm.c
vendor/lua/dist/src/lvm.h
vendor/lua/dist/src/lzio.c
vendor/lua/dist/src/lzio.h
Modified: vendor/lua/dist/Makefile
==============================================================================
--- vendor/lua/dist/Makefile Tue Nov 28 20:44:10 2017 (r326343)
+++ vendor/lua/dist/Makefile Tue Nov 28 22:55:31 2017 (r326344)
@@ -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)
Modified: vendor/lua/dist/README
==============================================================================
--- vendor/lua/dist/README Tue Nov 28 20:44:10 2017 (r326343)
+++ vendor/lua/dist/README Tue Nov 28 22:55:31 2017 (r326344)
@@ -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.
Modified: vendor/lua/dist/doc/contents.html
==============================================================================
--- vendor/lua/dist/doc/contents.html Tue Nov 28 20:44:10 2017 (r326343)
+++ vendor/lua/dist/doc/contents.html Tue Nov 28 22:55:31 2017 (r326344)
@@ -3,43 +3,42 @@
<HEAD>
<TITLE>Lua 5.3 Reference Manual - contents</TITLE>
<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css">
+<LINK REL="stylesheet" TYPE="text/css" HREF="index.css">
<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
-<STYLE TYPE="text/css">
-ul {
- list-style-type: none ;
- list-style-position: outside ;
-}
-</STYLE>
</HEAD>
<BODY>
-<HR>
<H1>
-<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="" BORDER=0></A>
+<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A>
Lua 5.3 Reference Manual
</H1>
<P>
The reference manual is the official definition of the Lua language.
+<BR>
For a complete introduction to Lua programming, see the book
<A HREF="http://www.lua.org/pil/">Programming in Lua</A>.
-<P>
+<DIV CLASS="menubar">
<A HREF="manual.html">start</A>
·
<A HREF="#contents">contents</A>
·
<A HREF="#index">index</A>
-<HR>
+·
+<A HREF="http://www.lua.org/manual/">other versions</A>
+</DIV>
+
+<P>
<SMALL>
-Copyright © 2015 Lua.org, PUC-Rio.
+Copyright © 2015–2017 Lua.org, PUC-Rio.
Freely available under the terms of the
<A HREF="http://www.lua.org/license.html">Lua license</A>.
</SMALL>
<H2><A NAME="contents">Contents</A></H2>
-<UL style="padding: 0">
+<UL CLASS="contents menubar">
<LI><A HREF="manual.html">1 – Introduction</A>
<P>
<LI><A HREF="manual.html#2">2 – Basic Concepts</A>
@@ -136,15 +135,14 @@ Freely available under the terms of the
</UL>
<H2><A NAME="index">Index</A></H2>
-<TABLE WIDTH="100%">
-<TR VALIGN="top">
+<TABLE CLASS="menubar" WIDTH="100%">
+<TR>
<TD>
<H3><A NAME="functions">Lua functions</A></H3>
<P>
<A HREF="manual.html#6.1">basic</A><BR>
<A HREF="manual.html#pdf-_G">_G</A><BR>
<A HREF="manual.html#pdf-_VERSION">_VERSION</A><BR>
-
<A HREF="manual.html#pdf-assert">assert</A><BR>
<A HREF="manual.html#pdf-collectgarbage">collectgarbage</A><BR>
<A HREF="manual.html#pdf-dofile">dofile</A><BR>
@@ -321,6 +319,7 @@ Freely available under the terms of the
<A HREF="manual.html#pdf-utf8.offset">utf8.offset</A><BR>
<H3><A NAME="env">environment<BR>variables</A></H3>
+<P>
<A HREF="manual.html#pdf-LUA_CPATH">LUA_CPATH</A><BR>
<A HREF="manual.html#pdf-LUA_CPATH_5_3">LUA_CPATH_5_3</A><BR>
<A HREF="manual.html#pdf-LUA_INIT">LUA_INIT</A><BR>
@@ -513,6 +512,7 @@ Freely available under the terms of the
<A HREF="manual.html#luaL_newmetatable">luaL_newmetatable</A><BR>
<A HREF="manual.html#luaL_newstate">luaL_newstate</A><BR>
<A HREF="manual.html#luaL_openlibs">luaL_openlibs</A><BR>
+<A HREF="manual.html#luaL_opt">luaL_opt</A><BR>
<A HREF="manual.html#luaL_optinteger">luaL_optinteger</A><BR>
<A HREF="manual.html#luaL_optlstring">luaL_optlstring</A><BR>
<A HREF="manual.html#luaL_optnumber">luaL_optnumber</A><BR>
@@ -546,6 +546,7 @@ Freely available under the terms of the
<A HREF="manual.html#pdf-luaopen_utf8">luaopen_utf8</A><BR>
<H3><A NAME="constants">constants</A></H3>
+<P>
<A HREF="manual.html#pdf-LUA_ERRERR">LUA_ERRERR</A><BR>
<A HREF="manual.html#pdf-LUA_ERRFILE">LUA_ERRFILE</A><BR>
<A HREF="manual.html#pdf-LUA_ERRGCMM">LUA_ERRGCMM</A><BR>
@@ -606,13 +607,12 @@ Freely available under the terms of the
</TR>
</TABLE>
-<HR>
-<SMALL CLASS="footer">
+<P CLASS="footer">
Last update:
-Tue Dec 9 21:26:07 BRST 2014
-</SMALL>
+Thu Dec 22 18:29:39 BRST 2016
+</P>
<!--
-Last change: updated for Lua 5.3.0 (final)
+Last change: revised for Lua 5.3.4
-->
</BODY>
Added: vendor/lua/dist/doc/index.css
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ vendor/lua/dist/doc/index.css Tue Nov 28 22:55:31 2017 (r326344)
@@ -0,0 +1,21 @@
+ul {
+ list-style-type: none ;
+}
+
+ul.contents {
+ padding: 0 ;
+}
+
+table {
+ border: none ;
+ border-spacing: 0 ;
+ border-collapse: collapse ;
+}
+
+td {
+ vertical-align: top ;
+ padding: 0 ;
+ text-align: left ;
+ line-height: 1.25 ;
+ width: 15% ;
+}
Modified: vendor/lua/dist/doc/logo.gif
==============================================================================
Binary file (source and/or target). No diff available.
Modified: vendor/lua/dist/doc/lua.1
==============================================================================
--- vendor/lua/dist/doc/lua.1 Tue Nov 28 20:44:10 2017 (r326343)
+++ vendor/lua/dist/doc/lua.1 Tue Nov 28 22:55:31 2017 (r326344)
@@ -1,4 +1,5 @@
-.TH LUA 1 "$Date: 2014/12/10 15:55:45 $"
+.\" $Id: lua.man,v 1.14 2016/10/17 15:43:50 lhf Exp $
+.TH LUA 1 "$Date: 2016/10/17 15:43:50 $"
.SH NAME
lua \- Lua interpreter
.SH SYNOPSIS
Modified: vendor/lua/dist/doc/lua.css
==============================================================================
--- vendor/lua/dist/doc/lua.css Tue Nov 28 20:44:10 2017 (r326343)
+++ vendor/lua/dist/doc/lua.css Tue Nov 28 22:55:31 2017 (r326344)
@@ -3,89 +3,96 @@ html {
}
body {
- border: solid #a0a0a0 1px ;
- border-radius: 20px ;
- padding: 26px ;
- margin: 16px ;
- color: #000000 ;
background-color: #FFFFFF ;
+ color: #000000 ;
font-family: Helvetica, Arial, sans-serif ;
text-align: justify ;
+ line-height: 1.25 ;
+ margin: 16px auto ;
+ padding: 32px ;
+ border: solid #a0a0a0 1px ;
+ border-radius: 20px ;
+ max-width: 70em ;
+ width: 90% ;
}
h1, h2, h3, h4 {
+ color: #000080 ;
font-family: Verdana, Geneva, sans-serif ;
font-weight: normal ;
font-style: normal ;
+ text-align: left ;
}
-h2 {
- padding-top: 0.4em ;
- padding-bottom: 0.4em ;
- padding-left: 0.8em ;
- padding-right: 0.8em ;
- background-color: #D0D0FF ;
- border-radius: 8px ;
- border: solid #a0a0a0 1px ;
+h1 {
+ font-size: 28pt ;
}
-h3 {
- padding-left: 0.5em ;
- border-left: solid #D0D0FF 1em ;
+h1 img {
+ vertical-align: text-bottom ;
}
-table h3 {
- padding-left: 0px ;
- border-left: none ;
+h2:before {
+ content: "\2756" ;
+ padding-right: 0.5em ;
}
-a:link {
- color: #000080 ;
- background-color: inherit ;
+a {
text-decoration: none ;
}
-a:visited {
- background-color: inherit ;
- text-decoration: none ;
+a:link {
+ color: #000080 ;
}
a:link:hover, a:visited:hover {
- color: #000080 ;
background-color: #D0D0FF ;
- border-radius: 4px;
+ color: #000080 ;
+ border-radius: 4px ;
}
a:link:active, a:visited:active {
color: #FF0000 ;
}
-h1 a img {
- vertical-align: text-bottom ;
+div.menubar {
+ padding-bottom: 0.5em ;
}
-hr {
- border: 0 ;
- height: 1px ;
- color: #a0a0a0 ;
- background-color: #a0a0a0 ;
- display: none ;
+p.menubar {
+ margin-left: 2.5em ;
}
-table hr {
- display: block ;
+.menubar a:hover {
+ margin: -3px -3px -3px -3px ;
+ padding: 3px 3px 3px 3px ;
+ border-radius: 4px ;
}
:target {
- background-color: #F8F8F8 ;
+ background-color: #F0F0F0 ;
+ margin: -8px ;
padding: 8px ;
- border: solid #a0a0a0 2px ;
border-radius: 8px ;
+ outline: none ;
}
+hr {
+ display: none ;
+}
+
+table hr {
+ background-color: #a0a0a0 ;
+ color: #a0a0a0 ;
+ border: 0 ;
+ height: 1px ;
+ display: block ;
+}
+
.footer {
color: gray ;
font-size: x-small ;
+ text-transform: lowercase ;
}
input[type=text] {
@@ -102,4 +109,56 @@ pre.session {
background-color: #F8F8F8 ;
padding: 1em ;
border-radius: 8px ;
+}
+
+td.gutter {
+ width: 4% ;
+}
+
+table.columns {
+ border: none ;
+ border-spacing: 0 ;
+ border-collapse: collapse ;
+}
+
+table.columns td {
+ vertical-align: top ;
+ padding: 0 ;
+ padding-bottom: 1em ;
+ text-align: justify ;
+ line-height: 1.25 ;
+}
+
+p.logos a:link:hover, p.logos a:visited:hover {
+ background-color: inherit ;
+}
+
+table.book {
+ border: none ;
+ border-spacing: 0 ;
+ border-collapse: collapse ;
+}
+
+table.book td {
+ padding: 0 ;
+ vertical-align: top ;
+}
+
+table.book td.cover {
+ padding-right: 1em ;
+}
+
+table.book img {
+ border: solid #000080 1px ;
+}
+
+table.book span {
+ font-size: small ;
+ text-align: left ;
+ display: block ;
+ margin-top: 0.25em ;
+}
+
+img {
+ background-color: white ;
}
Modified: vendor/lua/dist/doc/manual.css
==============================================================================
--- vendor/lua/dist/doc/manual.css Tue Nov 28 20:44:10 2017 (r326343)
+++ vendor/lua/dist/doc/manual.css Tue Nov 28 22:55:31 2017 (r326344)
@@ -8,20 +8,14 @@ pre, code {
}
span.apii {
+ color: gray ;
float: right ;
font-family: inherit ;
font-style: normal ;
font-size: small ;
- color: gray ;
}
-p+h1, ul+h1 {
- font-style: normal ;
- padding-top: 0.4em ;
- padding-bottom: 0.4em ;
- padding-left: 16px ;
- margin-left: -16px ;
- background-color: #D0D0FF ;
- border-radius: 8px ;
- border: solid #000080 1px ;
+h2:before {
+ content: "" ;
+ padding-right: 0em ;
}
Modified: vendor/lua/dist/doc/manual.html
==============================================================================
--- vendor/lua/dist/doc/manual.html Tue Nov 28 20:44:10 2017 (r326343)
+++ vendor/lua/dist/doc/manual.html Tue Nov 28 22:55:31 2017 (r326344)
@@ -1,39 +1,41 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-
-<head>
-<title>Lua 5.3 Reference Manual</title>
-<link rel="stylesheet" type="text/css" href="lua.css">
-<link rel="stylesheet" type="text/css" href="manual.css">
+<HTML>
+<HEAD>
+<TITLE>Lua 5.3 Reference Manual</TITLE>
+<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css">
+<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css">
<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
-</head>
+</HEAD>
-<body>
+<BODY>
-<hr>
-<h1>
-<a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a>
+<H1>
+<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A>
Lua 5.3 Reference Manual
-</h1>
+</H1>
+<P>
by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
-<p>
-<small>
-Copyright © 2015 Lua.org, PUC-Rio.
+
+<P>
+<SMALL>
+Copyright © 2015–2017 Lua.org, PUC-Rio.
Freely available under the terms of the
<a href="http://www.lua.org/license.html">Lua license</a>.
-</small>
-<hr>
-<p>
+</SMALL>
-<a href="contents.html#contents">contents</A>
+<DIV CLASS="menubar">
+<A HREF="contents.html#contents">contents</A>
·
-<a href="contents.html#index">index</A>
+<A HREF="contents.html#index">index</A>
+·
+<A HREF="http://www.lua.org/manual/">other versions</A>
+</DIV>
<!-- ====================================================================== -->
<p>
-<!-- $Id: manual.of,v 1.146 2015/01/06 11:23:01 roberto Exp $ -->
+<!-- $Id: manual.of,v 1.167 2017/01/09 15:18:11 roberto Exp $ -->
@@ -41,30 +43,47 @@ Freely available under the terms of the
<h1>1 – <a name="1">Introduction</a></h1>
<p>
-Lua is an extension programming language designed to support
-general procedural programming with data description
-facilities.
-Lua also offers good support for object-oriented programming,
-functional programming, and data-driven programming.
-Lua is intended to be used as a powerful, lightweight,
-embeddable scripting language for any program that needs one.
+Lua is a powerful, efficient, lightweight, embeddable scripting language.
+It supports procedural programming,
+object-oriented programming, functional programming,
+data-driven programming, and data description.
+
+
+<p>
+Lua combines simple procedural syntax with powerful data description
+constructs based on associative arrays and extensible semantics.
+Lua is dynamically typed,
+runs by interpreting bytecode with a register-based
+virtual machine,
+and has automatic memory management with
+incremental garbage collection,
+making it ideal for configuration, scripting,
+and rapid prototyping.
+
+
+<p>
Lua is implemented as a library, written in <em>clean C</em>,
the common subset of Standard C and C++.
+The Lua distribution includes a host program called <code>lua</code>,
+which uses the Lua library to offer a complete,
+standalone Lua interpreter,
+for interactive or batch use.
+Lua is intended to be used both as a powerful, lightweight,
+embeddable scripting language for any program that needs one,
+and as a powerful but lightweight and efficient stand-alone language.
<p>
As an extension language, Lua has no notion of a "main" program:
-it only works <em>embedded</em> in a host client,
+it works <em>embedded</em> in a host client,
called the <em>embedding program</em> or simply the <em>host</em>.
+(Frequently, this host is the stand-alone <code>lua</code> program.)
The host program can invoke functions to execute a piece of Lua code,
can write and read Lua variables,
and can register C functions to be called by Lua code.
Through the use of C functions, Lua can be augmented to cope with
a wide range of different domains,
thus creating customized programming languages sharing a syntactical framework.
-The Lua distribution includes a sample host program called <code>lua</code>,
-which uses the Lua library to offer a complete, standalone Lua interpreter,
-for interactive or batch use.
<p>
@@ -113,15 +132,15 @@ There are eight basic types in Lua:
<em>nil</em>, <em>boolean</em>, <em>number</em>,
<em>string</em>, <em>function</em>, <em>userdata</em>,
<em>thread</em>, and <em>table</em>.
-<em>Nil</em> is the type of the value <b>nil</b>,
+The type <em>nil</em> has one single value, <b>nil</b>,
whose main property is to be different from any other value;
it usually represents the absence of a useful value.
-<em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>.
+The type <em>boolean</em> has two values, <b>false</b> and <b>true</b>.
Both <b>nil</b> and <b>false</b> make a condition false;
any other value makes it true.
-<em>Number</em> represents both
+The type <em>number</em> represents both
integer numbers and real (floating-point) numbers.
-<em>String</em> represents immutable sequences of bytes.
+The type <em>string</em> represents immutable sequences of bytes.
Lua is 8-bit clean:
strings can contain any 8-bit value,
@@ -132,6 +151,7 @@ it makes no assumptions about the contents of a string
<p>
The type <em>number</em> uses two internal representations,
+or two subtypes,
one called <em>integer</em> and the other called <em>float</em>.
Lua has explicit rules about when each representation is used,
but it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>).
@@ -142,7 +162,7 @@ or to assume complete control over the representation
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 for both integers and floats
+The option with 32 bits for both integers and floats
is particularly attractive
for small machines and embedded systems.
(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.)
@@ -185,8 +205,8 @@ even those that do not support threads natively.
The type <em>table</em> implements associative arrays,
that is, arrays that can be indexed not only with numbers,
but with any Lua value except <b>nil</b> and NaN.
-(<em>Not a Number</em> is a special numeric value used to represent
-undefined or unrepresentable results, such as <code>0/0</code>.)
+(<em>Not a Number</em> is a special value used to represent
+undefined or unrepresentable numerical results, such as <code>0/0</code>.)
Tables can be <em>heterogeneous</em>;
that is, they can contain values of all types (except <b>nil</b>).
Any key with value <b>nil</b> is not considered part of the table.
@@ -196,7 +216,7 @@ an associated value <b>nil</b>.
<p>
Tables are the sole data-structuring mechanism in Lua;
-they can be used to represent ordinary arrays, sequences,
+they can be used to represent ordinary arrays, lists,
symbol tables, sets, records, graphs, trees, etc.
To represent records, Lua uses the field name as an index.
The language supports this representation by
@@ -206,13 +226,6 @@ There are several convenient ways to create tables in
<p>
-We use the term <em>sequence</em> to denote a table where
-the set of all positive numeric keys is equal to {1..<em>n</em>}
-for some non-negative integer <em>n</em>,
-which is called the length of the sequence (see <a href="#3.4.7">§3.4.7</a>).
-
-
-<p>
Like indices,
the values of table fields can be of any type.
In particular,
@@ -348,8 +361,8 @@ It is up to the Lua program or its host to handle such
When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>,
you may give a <em>message handler</em>
to be called in case of errors.
-This function is called with the original error message
-and returns a new error message.
+This function is called with the original error object
+and returns a new error object.
It is called before the error unwinds the stack,
so that it can gather more information about the error,
for instance by inspecting the stack and creating a stack traceback.
@@ -358,6 +371,9 @@ 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.
+It is not called for memory-allocation errors
+nor for errors while running finalizers.)
@@ -379,23 +395,30 @@ Lua calls this function to perform the addition.
<p>
-The keys in a metatable are derived from the <em>event</em> names;
+The key for each event in a metatable is a string
+with the event name prefixed by two underscores;
the corresponding values are called <em>metamethods</em>.
-In the previous example, the event is <code>"add"</code>
+In the previous example, the key is "<code>__add</code>"
and the metamethod is the function that performs the addition.
<p>
You can query the metatable of any value
using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
+Lua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>).
+So, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>,
+Lua does the equivalent to the following code:
+<pre>
+ rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>")
+</pre>
<p>
You can replace the metatable of tables
using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function.
-You cannot change the metatable of other types from Lua
+You cannot change the metatable of other types from Lua code
(except by using the debug library (<a href="#6.10">§6.10</a>));
-you must use the C API for that.
+you should use the C API for that.
<p>
@@ -417,23 +440,7 @@ when a userdata or a table is garbage collected (<a hr
<p>
-A detailed list of events controlled by metatables is given next.
-Each operation is identified by its corresponding event name.
-The key for each event is a string with its name prefixed by
-two underscores, '<code>__</code>';
-for instance, the key for operation "add" is the
-string "<code>__add</code>".
-Note that queries for metamethods are always raw;
-the access to a metamethod does not invoke other metamethods.
-You can emulate how Lua queries a metamethod for an object <code>obj</code>
-with the following code:
-
-<pre>
- rawget(getmetatable(obj) or {}, "__" .. event_name)
-</pre>
-
-<p>
-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,
equal to the first one.
This extra operand is only to simplify Lua's internals
@@ -442,17 +449,21 @@ and may be removed in future versions.
(For most uses this extra operand is irrelevant.)
+<p>
+A detailed list of events controlled by metatables is given next.
+Each operation is identified by its corresponding key.
-<ul>
-<li><b>"add": </b>
-the <code>+</code> operation.
+<ul>
+
+<li><b><code>__add</code>: </b>
+the addition (<code>+</code>) operation.
If any operand for an addition is not a number
(nor a string coercible to a number),
Lua will try to call a metamethod.
First, Lua will check the first operand (even if it is valid).
-If that operand does not define a metamethod for the "<code>__add</code>" event,
+If that operand does not define a metamethod for <code>__add</code>,
then Lua will check the second operand.
If Lua can find a metamethod,
it calls the metamethod with the two operands as arguments,
@@ -463,99 +474,84 @@ Otherwise,
it raises an error.
</li>
-<li><b>"sub": </b>
-the <code>-</code> operation.
-
-Behavior similar to the "add" operation.
+<li><b><code>__sub</code>: </b>
+the subtraction (<code>-</code>) operation.
+Behavior similar to the addition operation.
</li>
-<li><b>"mul": </b>
-the <code>*</code> operation.
-
-Behavior similar to the "add" operation.
+<li><b><code>__mul</code>: </b>
+the multiplication (<code>*</code>) operation.
+Behavior similar to the addition operation.
</li>
-<li><b>"div": </b>
-the <code>/</code> operation.
-
-Behavior similar to the "add" operation.
+<li><b><code>__div</code>: </b>
+the division (<code>/</code>) operation.
+Behavior similar to the addition operation.
</li>
-<li><b>"mod": </b>
-the <code>%</code> operation.
-
-Behavior similar to the "add" operation.
+<li><b><code>__mod</code>: </b>
+the modulo (<code>%</code>) operation.
+Behavior similar to the addition operation.
</li>
-<li><b>"pow": </b>
-the <code>^</code> (exponentiation) operation.
-
-Behavior similar to the "add" operation.
+<li><b><code>__pow</code>: </b>
+the exponentiation (<code>^</code>) operation.
+Behavior similar to the addition operation.
</li>
-<li><b>"unm": </b>
-the <code>-</code> (unary minus) operation.
-
-Behavior similar to the "add" operation.
+<li><b><code>__unm</code>: </b>
+the negation (unary <code>-</code>) operation.
+Behavior similar to the addition operation.
</li>
-<li><b>"idiv": </b>
-the <code>//</code> (floor division) operation.
-
-Behavior similar to the "add" operation.
+<li><b><code>__idiv</code>: </b>
+the floor division (<code>//</code>) operation.
+Behavior similar to the addition operation.
</li>
-<li><b>"band": </b>
-the <code>&</code> (bitwise and) operation.
-
-Behavior similar to the "add" operation,
+<li><b><code>__band</code>: </b>
+the bitwise AND (<code>&</code>) operation.
+Behavior similar to the addition operation,
except that Lua will try a metamethod
-if any operator is neither an integer
+if any operand is neither an integer
nor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>).
</li>
-<li><b>"bor": </b>
-the <code>|</code> (bitwise or) operation.
-
-Behavior similar to the "band" operation.
+<li><b><code>__bor</code>: </b>
+the bitwise OR (<code>|</code>) operation.
+Behavior similar to the bitwise AND operation.
</li>
-<li><b>"bxor": </b>
-the <code>~</code> (bitwise exclusive or) operation.
-
-Behavior similar to the "band" operation.
+<li><b><code>__bxor</code>: </b>
+the bitwise exclusive OR (binary <code>~</code>) operation.
+Behavior similar to the bitwise AND operation.
</li>
-<li><b>"bnot": </b>
-the <code>~</code> (bitwise unary not) operation.
-
-Behavior similar to the "band" operation.
+<li><b><code>__bnot</code>: </b>
+the bitwise NOT (unary <code>~</code>) operation.
+Behavior similar to the bitwise AND operation.
</li>
-<li><b>"shl": </b>
-the <code><<</code> (bitwise left shift) operation.
-
-Behavior similar to the "band" operation.
+<li><b><code>__shl</code>: </b>
+the bitwise left shift (<code><<</code>) operation.
+Behavior similar to the bitwise AND operation.
</li>
-<li><b>"shr": </b>
-the <code>>></code> (bitwise right shift) operation.
-
-Behavior similar to the "band" operation.
+<li><b><code>__shr</code>: </b>
+the bitwise right shift (<code>>></code>) operation.
+Behavior similar to the bitwise AND operation.
</li>
-<li><b>"concat": </b>
-the <code>..</code> (concatenation) operation.
-
-Behavior similar to the "add" operation,
+<li><b><code>__concat</code>: </b>
+the concatenation (<code>..</code>) operation.
+Behavior similar to the addition operation,
except that Lua will try a metamethod
-if any operator is neither a string nor a number
+if any operand is neither a string nor a number
(which is always coercible to a string).
</li>
-<li><b>"len": </b>
-the <code>#</code> (length) operation.
-
+<li><b><code>__len</code>: </b>
+the length (<code>#</code>) operation.
If the object is not a string,
Lua will try its metamethod.
If there is a metamethod,
@@ -568,42 +564,40 @@ then Lua uses the table length operation (see <a href=
Otherwise, Lua raises an error.
</li>
-<li><b>"eq": </b>
-the <code>==</code> (equal) operation.
-
-Behavior similar to the "add" operation,
+<li><b><code>__eq</code>: </b>
+the equal (<code>==</code>) operation.
+Behavior similar to the addition operation,
except that Lua will try a metamethod only when the values
being compared are either both tables or both full userdata
and they are not primitively equal.
The result of the call is always converted to a boolean.
</li>
-<li><b>"lt": </b>
-the <code><</code> (less than) operation.
-
-Behavior similar to the "add" operation,
+<li><b><code>__lt</code>: </b>
+the less than (<code><</code>) operation.
+Behavior similar to the addition operation,
except that Lua will try a metamethod only when the values
being compared are neither both numbers nor both strings.
The result of the call is always converted to a boolean.
</li>
-<li><b>"le": </b>
-the <code><=</code> (less equal) operation.
-
+<li><b><code>__le</code>: </b>
+the less equal (<code><=</code>) operation.
Unlike other operations,
-The less-equal operation can use two different events.
-First, Lua looks for the "<code>__le</code>" metamethod in both operands,
-like in the "lt" operation.
+the less-equal operation can use two different events.
+First, Lua looks for the <code>__le</code> metamethod in both operands,
+like in the less than operation.
If it cannot find such a metamethod,
-then it will try the "<code>__lt</code>" event,
+then it will try the <code>__lt</code> metamethod,
assuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>.
As with the other comparison operators,
the result is always a boolean.
+(This use of the <code>__lt</code> event can be removed in future versions;
+it is also slower than a real <code>__le</code> metamethod.)
</li>
-<li><b>"index": </b>
+<li><b><code>__index</code>: </b>
The indexing access <code>table[key]</code>.
-
This event happens when <code>table</code> is not a table or
when <code>key</code> is not present in <code>table</code>.
The metamethod is looked up in <code>table</code>.
@@ -613,16 +607,18 @@ The metamethod is looked up in <code>table</code>.
Despite the name,
the metamethod for this event can be either a function or a table.
If it is a function,
-it is called with <code>table</code> and <code>key</code> as arguments.
+it is called with <code>table</code> and <code>key</code> as arguments,
+and the result of the call
+(adjusted to one value)
+is the result of the operation.
If it is a table,
the final result is the result of indexing this table with <code>key</code>.
(This indexing is regular, not raw,
and therefore can trigger another metamethod.)
</li>
-<li><b>"newindex": </b>
+<li><b><code>__newindex</code>: </b>
The indexing assignment <code>table[key] = value</code>.
-
Like the index event,
this event happens when <code>table</code> is not a table or
when <code>key</code> is not present in <code>table</code>.
@@ -641,29 +637,47 @@ and therefore can trigger another metamethod.)
<p>
-Whenever there is a "newindex" metamethod,
+Whenever there is a <code>__newindex</code> metamethod,
Lua does not perform the primitive assignment.
(If necessary,
the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a>
to do the assignment.)
</li>
-<li><b>"call": </b>
+<li><b><code>__call</code>: </b>
The call operation <code>func(args)</code>.
-
This event happens when Lua tries to call a non-function value
(that is, <code>func</code> is not a function).
The metamethod is looked up in <code>func</code>.
If present,
the metamethod is called with <code>func</code> as its first argument,
followed by the arguments of the original call (<code>args</code>).
+All results of the call
+are the result of the operation.
+(This is the only metamethod that allows multiple results.)
</li>
</ul>
+<p>
+It is a good practice to add all needed metamethods to a table
+before setting it as a metatable of some object.
+In particular, the <code>__gc</code> metamethod works only when this order
+is followed (see <a href="#2.5.1">§2.5.1</a>).
+<p>
+Because metatables are regular tables,
+they can contain arbitrary fields,
+not only the event names defined above.
+Some functions in the standard library
+(e.g., <a href="#pdf-tostring"><code>tostring</code></a>)
+use other fields in metatables for their own purposes.
+
+
+
+
<h2>2.5 – <a name="2.5">Garbage Collection</a></h2>
<p>
@@ -752,8 +766,6 @@ and the metatable has a field indexed by the string "<
Note that if you set a metatable without a <code>__gc</code> field
and later create that field in the metatable,
the object will not be marked for finalization.
-However, after an object has been marked,
-you can freely change the <code>__gc</code> field of its metatable.
<p>
@@ -794,7 +806,7 @@ Moreover, if the finalizer marks a finalizing object f
its finalizer will be called again in the next cycle where the
object is unreachable.
In any case,
-the object memory is freed only in the GC cycle where
+the object memory is freed only in a GC cycle where
the object is unreachable and not marked for finalization.
@@ -822,8 +834,8 @@ then the garbage collector will collect that object.
<p>
A weak table can have weak keys, weak values, or both.
-A table with weak keys allows the collection of its keys,
-but prevents the collection of its values.
+A table with weak values allows the collection of its values,
+but prevents the collection of its keys.
A table with both weak keys and weak values allows the collection of
both keys and values.
In any case, if either the key or the value is collected,
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-src-all
mailing list