Lua Metatable Events

A listing of all the 'special' keys in a metatable (called 'metaevents'), and the metamethods which they perform. Most information comes from the Lua manual section on metatables.

• __index - Control 'prototype' inheritance. When accessing myTable[key] and the key is not present 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 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.
• __gc - Table finalizer code. When a table is set to be garbage collected, if the metatable has a __gc field pointing to a function, that function is first invoked, passing the table to it.

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 + value or value + 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.
• __pow - Involution. Similar to addition, using the '^' operator.
• __concat - Concatenation. Similar to addition, using the '..' operator.
• __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.
• __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 __lt function.

    a >= b == b <= a

  • If this metamethod doesn't exist but the <= or >= operators are used, then the __lt metamethod is used as a fallback, under the (sometimes incorrect) assumption that:

    a <= b == !(b < a)