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