This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.
The third edition targets Lua 5.2 and is available at Amazon and other bookstores.
By buying the book, you also help to support the Lua project.

13.1 – Arithmetic Metamethods

In this section, we will introduce a simple example to explain how to use metatables. Suppose we are using tables to represent sets, with functions to compute the union of two sets, intersection, and the like. As we did with lists, we store these functions inside a table and we define a constructor to create new sets:

    Set = {}
    
    function Set.new (t)
      local set = {}
      for _, l in ipairs(t) do set[l] = true end
      return set
    end
    
    function Set.union (a,b)
      local res = Set.new{}
      for k in pairs(a) do res[k] = true end
      for k in pairs(b) do res[k] = true end
      return res
    end
    
    function Set.intersection (a,b)
      local res = Set.new{}
      for k in pairs(a) do
        res[k] = b[k]
      end
      return res
    end

    function Set.tostring (set)
      local s = "{"
      local sep = ""
      for e in pairs(set) do
        s = s .. sep .. e
        sep = ", "
      end
      return s .. "}"
    end
    
    function Set.print (s)
      print(Set.tostring(s))
    end

Now, we want to make the addition operator (`+´) compute the union of two sets. For that, we will arrange that all tables representing sets share a metatable and this metatable will define how they react to the addition operator. Our first step is to create a regular table that we will use as the metatable for sets. To avoid polluting our namespace, we will store it in the Set table:

    Set.mt = {}    -- metatable for sets

    function Set.new (t)   -- 2nd version
      local set = {}
      setmetatable(set, Set.mt)
      for _, l in ipairs(t) do set[l] = true end
      return set
    end

    s1 = Set.new{10, 20, 30, 50}
    s2 = Set.new{30, 1}
    print(getmetatable(s1))          --> table: 00672B60
    print(getmetatable(s2))          --> table: 00672B60

Finally, we add to the metatable the so-called metamethod, a field __add that describes how to perform the union:

    Set.mt.__add = Set.union

With the metamethod in place, we can use the addition operator to do set unions:

    s3 = s1 + s2
    Set.print(s3)  --> {1, 10, 20, 30, 50}

    Set.mt.__mul = Set.intersection
    
    Set.print((s1 + s2)*s1)     --> {10, 20, 30, 50}

For each arithmetic operator there is a corresponding field name in a metatable. Besides __add and __mul, there are __sub (for subtraction), __div (for division), __unm (for negation), and __pow (for exponentiation). We may define also the field __concat, to define a behavior for the concatenation operator.

When we add two sets, there is no question about what metatable to use. However, we may write an expression that mixes two values with different metatables, for instance like this:

    s = Set.new{1,2,3}
    s = s + 8

Lua does not care about those mixed types, but our implementation does. If we run the s = s + 8 example, the error we get will be inside Set.union:

    bad argument #1 to `pairs' (table expected, got number)

    function Set.union (a,b)
      if getmetatable(a) ~= Set.mt or
         getmetatable(b) ~= Set.mt then
        error("attempt to `add' a set with a non-set value", 2)
      end
      ...  -- same as before

• __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 the table as the first argument, followed by 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