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.

	Programming in Lua
	Part II. Tables and Objects Chapter 13. Metatables and Metamethods

---

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

To help checking our examples, we also define a function to print sets:

    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

The next step is to modify the Set.new function, which creates sets. The new version has only one extra line, which sets mt as the metatable for the tables that it creates:

    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

After that, every set we create with Set.new will have that same table as its metatable:

    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

Whenever Lua tries to add two sets, it will call this function, with the two operands as arguments.

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}

Similarly, we may use the multiplication operator to perform set intersection:

    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

To choose a metamethod, Lua does the following: (1) If the first value has a metatable with an __add field, Lua uses this value as the metamethod, independently of the second value; (2) otherwise, if the second value has a metatable with an __add field, Lua uses this value as the metamethod; (3) otherwise, Lua raises an error. Therefore, the last example will call Set.union, as will the expressions 10 + s and "hy" + s.

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)

If we want more lucid error messages, we must check the type of the operands explicitly before attempting to perform the operation:

    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

---

Metatable Events

wiki

A listing of all the 'special' keys in a metatable, and the metamethods which they perform.

• __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
  

---

RecentChanges · preferences
edit · history
Last edited December 19, 2014 5:15 am GMT (diff)