Metatable Events

wiki

• __index - Control 'prototype' inheritance. When accessing "myTable[key]" and the key does not appear in the table, but the metatable has an __index property:
  • if the value is a function, the function is called, passing in the table and the key; the return value of that function is returned as the result.
  • if the value is another table, the value of the key in that table is asked for and returned
    • (and if it doesn't exist in that table, but that table's metatable has an __index property, then it continues on up)
  • Use "rawget(myTable,key)" to skip this metamethod.

• __newindex - Control property assignment. When calling "myTable[key] = value", if the metatable has a __newindex key pointing to a function, call that function, passing it the table, key, and value.
  • Use "rawset(myTable,key,value)" to skip this metamethod.
  • (If the __newindex function does not set the key on the table (using rawset) then the key/value pair is not added to myTable.)

• __mode - Control weak references. A string value with one or both of the characters 'k' and 'v' which specifies that the the keys and/or values in the table are weak references.

• __call - Treat a table like a function. When a table is followed by parenthesis such as "myTable( 'foo' )" and the metatable has a __call key pointing to a function, that function is invoked (passing any specified arguments) and the return value is returned.

• __metatable - Hide the metatable. When "getmetatable( myTable )" is called, if the metatable for myTable has a __metatable key, the value of that key is returned instead of the actual metatable.

• __tostring - Control string representation. When the builtin "tostring( myTable )" function is called, if the metatable for myTable has a __tostring property set to a function, that function is invoked (passing myTable to it) and the return value is used as the string representation.

• __len - Control table length. When the table length is requested using the length operator ( '#' ), if the metatable for myTable has a __len key pointing to a function, that function is invoked (passing myTable to it) and the return value used as the value of "#myTable".

• __gc - Userdata finalizer code. When userdata is set to be garbage collected, if the metatable has a __gc field pointing to a function, that function is first invoked, passing the userdata to it. The __gc metamethod is not called for tables. (See http://lua-users.org/lists/lua-l/2006-11/msg00508.html)

Mathematic Operators

• __unm - Unary minus. When writing "-myTable", if the metatable has a __unm key pointing to a function, that function is invoked (passing the table), and the return value used as the value of "-myTable".
• __add - Addition. When writing "myTable + object" or "object + myTable", if myTable's metatable has an __add key pointing to a function, that function is invoked (passing the left and right operators in order) and the return value used.
  • ''If both operands are tables, the left table is checked before the right table for the presence of an __add metaevent.

• __sub - Subtraction. Similar to addition, using the '-' operator.
• __mul - Multiplication. Similar to addition, using the '*' operator.
• __div - Division. Similar to addition, using the '/' operator.
• __mod - Modulo. Similar to addition, using the '%' operator.
• __pow - Involution. Similar to addition, using the '^' operator.
• __concat - Concatenation. Similar to addition, using the '..' operator.

Equivalence Comparison Operators

• __eq - Check for equality. This method is invoked when "myTable1 == myTable2" is evaluated, but only if both tables have the exact same metamethod for __eq.
  • For example, see the following code:

  
  t1a = {}
  
  t1b = {}
  
  t2  = {}
  
  mt1 = { __eq = function( o1, o2 ) return 'whee' end }
  
  mt2 = { __eq = function( o1, o2 ) return 'whee' end }
  
  
  
  setmetatable( t1a, mt1 )
  
  setmetatable( t1b, mt1 )
  
  setmetatable( t2,  mt2 )
  
  
  
  print( t1a == t1b )     --> true
  
  print( t1a == t2 )      --> false
  
  

  • If the function returns nil or false, the result of the comparison is false; otherwise, the result is true.

• If t1 and t2 are referencing the same table, the __eq method is not invoked for t1 == t2 :

function foo (o1, o2) 

  print( '__eq call' )

  return false 

end



t1 = {}

setmetatable( t1, {__eq = foo} )



t2 = t1

print( t1 == t2 ) --> true

        -- string '__eq call' not printed (and comparison result is true, not like the return value of foo(...)), so no foo(...) call here



t3 = {}

setmetatable( t3, {__eq = foo} )

if t1 == t3 then end  --> __eq call

        -- foo(...) was called

• __lt - Check for less-than. Similar to equality, using the '<' operator.
  • Greater-than is evaluated by reversing the order of the operands passed to the __lt function.

  
  a > b == b < a
  
  

• __le - Check for less-than-or-equal. Similar to equality, using the '<=' operator.
  • Greater-than-or-equal is evaluated by reversing the order of the operands passed to the __le function.

  
  a >= b == b <= a