summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRoberto Ierusalimschy <roberto@inf.puc-rio.br>2019-10-08 10:34:43 -0300
committerRoberto Ierusalimschy <roberto@inf.puc-rio.br>2019-10-08 10:34:43 -0300
commit6c0e44464b9eef4be42e2c8181aabfb3301617ad (patch)
treeeac6b9aec36f32b3f7889bfae74d71082951e576
parent6a84c329005ab7fc3f17283feda3f41010728288 (diff)
downloadlua-5.4-beta.tar.gz
lua-5.4-beta.tar.bz2
lua-5.4-beta.zip
Improvements in the manual around metamethodsv5.4-beta
-rw-r--r--manual/manual.of77
1 files changed, 42 insertions, 35 deletions
diff --git a/manual/manual.of b/manual/manual.of
index cca4ca08..df7b74b4 100644
--- a/manual/manual.of
+++ b/manual/manual.of
@@ -295,9 +295,9 @@ although this behavior can be adapted from C @seeC{lua_setwarnf}.
295Every value in Lua can have a @emph{metatable}. 295Every value in Lua can have a @emph{metatable}.
296This @def{metatable} is an ordinary Lua table 296This @def{metatable} is an ordinary Lua table
297that defines the behavior of the original value 297that defines the behavior of the original value
298under certain special operations. 298under certain events.
299You can change several aspects of the behavior 299You can change several aspects of the behavior
300of operations over a value by setting specific fields in its metatable. 300of a value by setting specific fields in its metatable.
301For instance, when a non-numeric value is the operand of an addition, 301For instance, when a non-numeric value is the operand of an addition,
302Lua checks for a function in the field @St{__add} of the value's metatable. 302Lua checks for a function in the field @St{__add} of the value's metatable.
303If it finds one, 303If it finds one,
@@ -306,7 +306,7 @@ Lua calls this function to perform the addition.
306The key for each event in a metatable is a string 306The key for each event in a metatable is a string
307with the event name prefixed by two underscores; 307with the event name prefixed by two underscores;
308the corresponding values are called @def{metamethods}. 308the corresponding values are called @def{metamethods}.
309In the previous example, the key is @St{__add} 309In the previous example, the key is the string @St{__add}
310and the metamethod is the function that performs the addition. 310and the metamethod is the function that performs the addition.
311Unless stated otherwise, 311Unless stated otherwise,
312metamethods should be function values. 312metamethods should be function values.
@@ -328,22 +328,10 @@ one for all strings, etc.
328By default, a value has no metatable, 328By default, a value has no metatable,
329but the string library sets a metatable for the string type @see{strlib}. 329but the string library sets a metatable for the string type @see{strlib}.
330 330
331A metatable controls how an object behaves in 331A detailed list of operations controlled by metatables is given next.
332arithmetic operations, bitwise operations, 332Each event is identified by its corresponding key.
333order comparisons, concatenation, length operation, calls, and indexing. 333By convention, all metatable keys used by Lua are composed by
334A metatable also can define a function to be called 334two underscores followed by lowercase Latin letters.
335when a userdata or a table is @link{GC|garbage collected}.
336
337For the unary operators (negation, length, and bitwise NOT),
338the metamethod is computed and called with a dummy second operand,
339equal to the first one.
340This extra operand is only to simplify Lua's internals
341(by making these operators behave like a binary operation)
342and may be removed in future versions.
343(For most uses this extra operand is irrelevant.)
344
345A detailed list of events controlled by metatables is given next.
346Each operation is identified by its corresponding key.
347 335
348@description{ 336@description{
349 337
@@ -351,16 +339,16 @@ Each operation is identified by its corresponding key.
351the addition (@T{+}) operation. 339the addition (@T{+}) operation.
352If any operand for an addition is not a number, 340If any operand for an addition is not a number,
353Lua will try to call a metamethod. 341Lua will try to call a metamethod.
354First, Lua will check the first operand (even if it is valid). 342It starts by checking the first operand (even if it is a number);
355If that operand does not define a metamethod for @idx{__add}, 343if that operand does not define a metamethod for @idx{__add},
356then Lua will check the second operand. 344then Lua will check the second operand.
357If Lua can find a metamethod, 345If Lua can find a metamethod,
358it calls the metamethod with the two operands as arguments, 346it calls the metamethod with the two operands as arguments,
359and the result of the call 347and the result of the call
360(adjusted to one value) 348(adjusted to one value)
361is the result of the operation. 349is the result of the operation.
362Otherwise, 350Otherwise, if no metamethod is found,
363it raises an error. 351Lua raises an error.
364} 352}
365 353
366@item{@idx{__sub}| 354@item{@idx{__sub}|
@@ -467,7 +455,7 @@ the less than (@T{<}) operation.
467Behavior similar to the addition operation, 455Behavior similar to the addition operation,
468except that Lua will try a metamethod only when the values 456except that Lua will try a metamethod only when the values
469being compared are neither both numbers nor both strings. 457being compared are neither both numbers nor both strings.
470The result of the call is always converted to a boolean. 458Moreover, the result of the call is always converted to a boolean.
471} 459}
472 460
473@item{@idx{__le}| 461@item{@idx{__le}|
@@ -512,9 +500,9 @@ and therefore can trigger another metamethod.
512 500
513Whenever there is a @idx{__newindex} metamethod, 501Whenever there is a @idx{__newindex} metamethod,
514Lua does not perform the primitive assignment. 502Lua does not perform the primitive assignment.
515(If necessary, 503If needed,
516the metamethod itself can call @Lid{rawset} 504the metamethod itself can call @Lid{rawset}
517to do the assignment.) 505to do the assignment.
518} 506}
519 507
520@item{@idx{__call}| 508@item{@idx{__call}|
@@ -526,16 +514,29 @@ If present,
526the metamethod is called with @id{func} as its first argument, 514the metamethod is called with @id{func} as its first argument,
527followed by the arguments of the original call (@id{args}). 515followed by the arguments of the original call (@id{args}).
528All results of the call 516All results of the call
529are the result of the operation. 517are the results of the operation.
530This is the only metamethod that allows multiple results. 518This is the only metamethod that allows multiple results.
531} 519}
532 520
533} 521}
534 522
535It is a good practice to add all needed metamethods to a table 523In addition to the previous list,
536before setting it as a metatable of some object. 524the interpreter also respects the following keys in metatables:
537In particular, the @idx{__gc} metamethod works only when this order 525@idx{__gc} @see{finalizers},
538is followed @see{finalizers}. 526@idx{__close} @see{to-be-closed},
527@idx{__mode} @see{weak-table},
528and @idx{__name}.
529(The entry @idx{__name},
530when it contains a string,
531is used by some error-reporting functions to build error messages.)
532
533For the unary operators (negation, length, and bitwise NOT),
534the metamethod is computed and called with a dummy second operand,
535equal to the first one.
536This extra operand is only to simplify Lua's internals
537(by making these operators behave like a binary operation)
538and may be removed in future versions.
539For most uses this extra operand is irrelevant.
539 540
540Because metatables are regular tables, 541Because metatables are regular tables,
541they can contain arbitrary fields, 542they can contain arbitrary fields,
@@ -544,6 +545,13 @@ Some functions in the standard library
544(e.g., @Lid{tostring}) 545(e.g., @Lid{tostring})
545use other fields in metatables for their own purposes. 546use other fields in metatables for their own purposes.
546 547
548It is a good practice to add all needed metamethods to a table
549before setting it as a metatable of some object.
550In particular, the @idx{__gc} metamethod works only when this order
551is followed @see{finalizers}.
552It is also a good practice to set the metatable of an object
553right after its creation.
554
547} 555}
548 556
549@sect2{GC| @title{Garbage Collection} 557@sect2{GC| @title{Garbage Collection}
@@ -1012,7 +1020,7 @@ it must be expressed using exactly three digits.)
1012The @x{UTF-8} encoding of a @x{Unicode} character 1020The @x{UTF-8} encoding of a @x{Unicode} character
1013can be inserted in a literal string with 1021can be inserted in a literal string with
1014the escape sequence @T{\u{@rep{XXX}}} 1022the escape sequence @T{\u{@rep{XXX}}}
1015(with mandatory enclosing brackets), 1023(with mandatory enclosing braces),
1016where @rep{XXX} is a sequence of one or more hexadecimal digits 1024where @rep{XXX} is a sequence of one or more hexadecimal digits
1017representing the character code point. 1025representing the character code point.
1018This code point can be any value less than @M{2@sp{31}}. 1026This code point can be any value less than @M{2@sp{31}}.
@@ -5536,7 +5544,6 @@ creates a new table to be used as a metatable for userdata,
5536adds to this new table the pair @T{__name = tname}, 5544adds to this new table the pair @T{__name = tname},
5537adds to the registry the pair @T{[tname] = new table}, 5545adds to the registry the pair @T{[tname] = new table},
5538and returns 1. 5546and returns 1.
5539(The entry @idx{__name} is used by some error-reporting functions.)
5540 5547
5541In both cases, 5548In both cases,
5542the function pushes onto the stack the final value associated 5549the function pushes onto the stack the final value associated
@@ -5911,7 +5918,7 @@ The notation @fail means a return value representing
5911some kind of failure or the absence of a better value to return. 5918some kind of failure or the absence of a better value to return.
5912Currently, @fail is equal to @nil, 5919Currently, @fail is equal to @nil,
5913but that may change in future versions. 5920but that may change in future versions.
5914The recommendation is to test the success of these functions 5921The recommendation is to always test the success of these functions
5915with @T{(not status)}, instead of @T{(status == nil)}. 5922with @T{(not status)}, instead of @T{(status == nil)}.
5916 5923
5917 5924
@@ -8587,7 +8594,7 @@ This function has the following restrictions:
8587@item{@id{limit} cannot be less than the amount of C stack in use.} 8594@item{@id{limit} cannot be less than the amount of C stack in use.}
8588} 8595}
8589If a call does not respect some restriction, 8596If a call does not respect some restriction,
8590it returns @false. 8597it returns a falsy value.
8591Otherwise, 8598Otherwise,
8592the call returns the old limit. 8599the call returns the old limit.
8593 8600