The keys in a metatable are derived from the event names; the corresponding values are called metamethods. In the previous example, the event is "add" and the metamethod is the function that performs the addition.

    You can query the metatable of any value using the function.

    You can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua (except by using the debug library); you must use the C API for that.

    Tables and full userdata have individual metatables (although multiple tables and userdata can share their metatables). Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see ).

    A metatable controls how an object behaves in arithmetic operations, order comparisons, concatenation, length operation, and indexing. A metatable also can define a function to be called when a userdata or a table is garbage collected. When Lua performs one of these operations over a value, it checks whether this value has a metatable with the corresponding event. If so, the value associated with that key (the metamethod) controls how Lua will perform the operation.

    Metatables control the operations listed next. Each operation is identified by its corresponding name. The key for each operation is a string with its name prefixed by two underscores, ‘__‘; for instance, the key for operation “add” is the string “__add“.

    The semantics of these operations is better explained by a Lua function describing how the interpreter executes the operation. The code shown here in Lua is only illustrative; the real behavior is hard coded in the interpreter and it is much more efficient than this simulation. All functions used in these descriptions (rawget, , etc.) are described in §6.1. In particular, to retrieve the metamethod of a given object, we use the expression

    This should be read as

    1.      rawget(getmetatable(obj) or {}, event)

    This means that the access to a metamethod does not invoke other metamethods, and access to objects with no metatables does not fail (it simply results in nil).

    • “add”: the + operation.

      The function getbinhandler below defines how Lua chooses a handler for a binary operation. First, Lua tries the first operand. If its type does not define a handler for the operation, then Lua tries the second operand.

      1.      function getbinhandler (op1, op2, event)
      2.        return metatable(op1)[event] or metatable(op2)[event]
      3.      end

      By using this function, the behavior of the is

      1.      function add_event (op1, op2)
      2.        local o1, o2 = tonumber(op1), tonumber(op2)
      3.        if o1 and o2 then  -- both operands are numeric?
      4.          return o1 + o2   -- '+' here is the primitive 'add'
      5.        else  -- at least one of the operands is not numeric
      6.          local h = getbinhandler(op1, op2, "__add")
      7.          if h then
      8.            -- call the handler with both operands
      9.            return (h(op1, op2))
      10.          else  -- no handler available: default behavior
      11.            error(···)
      12.          end
      13.        end
      14.      end

    • “sub”: the - operation. Behavior similar to the “add” operation.

    • “mul”: the * operation. Behavior similar to the “add” operation.
    • “div”: the / operation. Behavior similar to the “add” operation.
    • “mod”: the % operation. Behavior similar to the “add” operation, with the operation o1 - floor(o1/o2)*o2 as the primitive operation.
    • “pow”: the ^ (exponentiation) operation. Behavior similar to the “add” operation, with the function pow (from the C math library) as the primitive operation.

    • “unm”: the unary - operation.

    • “concat”: the .. (concatenation) operation.

      1.      function concat_event (op1, op2)
      2.        if (type(op1) == "string" or type(op1) == "number") and
      3.           (type(op2) == "string" or type(op2) == "number") then
      4.          return op1 .. op2  -- primitive string concatenation
      5.        else
      6.          local h = getbinhandler(op1, op2, "__concat")
      7.          if h then
      8.            return (h(op1, op2))
      9.          else
      10.            error(···)
      11.          end
      12.        end
      13.      end

    • “len”: the # operation.

      1.      function len_event (op)
      2.        if type(op) == "string" then
      3.          return strlen(op)      -- primitive string length
      4.          local h = metatable(op).__len
      5.          if h then
      6.            return (h(op))       -- call handler with the operand
      7.          elseif type(op) == "table" then
      8.            return #op              -- primitive table length
      9.          else  -- no handler available: error
      10.            error(···)
      11.          end
      12.        end
      13.      end

      See for a description of the length of a table.

    • “eq”: the == operation. The function defines how Lua chooses a metamethod for equality. A metamethod is selected only when both values being compared have the same type and the same metamethod for the selected operation, and the values are either tables or full userdata.

      1.      function getequalhandler (op1, op2)
      2.        if type(op1) ~= type(op2) or
      3.           (type(op1) ~= "table" and type(op1) ~= "userdata") then
      4.          return nil     -- different values
      5.        end
      6.        local mm1 = metatable(op1).__eq
      7.        local mm2 = metatable(op2).__eq
      8.        if mm1 == mm2 then return mm1 else return nil end
      9.      end

      Note that the result is always a boolean.

    • “lt”: the < operation.

      1.      function lt_event (op1, op2)
      2.        if type(op1) == "number" and type(op2) == "number" then
      3.          return op1 < op2   -- numeric comparison
      4.        elseif type(op1) == "string" and type(op2) == "string" then
      5.          return op1 < op2   -- lexicographic comparison
      6.        else
      7.          local h = getbinhandler(op1, op2, "__lt")
      8.          if h then
      9.            return not not h(op1, op2)
      10.          else
      11.            error(···)
      12.          end
      13.        end
      14.      end

      Note that the result is always a boolean.

    • “le”: the <= operation.

      1.      function le_event (op1, op2)
      2.        if type(op1) == "number" and type(op2) == "number" then
      3.          return op1 <= op2   -- numeric comparison
      4.        elseif type(op1) == "string" and type(op2) == "string" then
      5.          return op1 <= op2   -- lexicographic comparison
      6.        else
      7.          local h = getbinhandler(op1, op2, "__le")
      8.            return not not h(op1, op2)
      9.          else
      10.            h = getbinhandler(op1, op2, "__lt")
      11.            if h then
      12.              return not h(op2, op1)
      13.            else
      14.              error(···)
      15.            end
      16.          end
      17.        end
      18.      end

      Note that, in the absence of a “le” metamethod, Lua tries the “lt”, assuming that a <= b is equivalent to not (b < a).

      As with the other comparison operators, the result is always a boolean.

    • “index”: The indexing access table[key]. Note that the metamethod is tried only when key is not present in table. (When table is not a table, no key is ever present, so the metamethod is always tried.)

      1.      function gettable_event (table, key)
      2.        local h
      3.        if type(table) == "table" then
      4.          local v = rawget(table, key)
      5.          -- if key is present, return raw value
      6.          if v ~= nil then return v end
      7.          h = metatable(table).__index
      8.          if h == nil then return nil end
      9.        else
      10.          h = metatable(table).__index
      11.          if h == nil then
      12.            error(···)
      13.          end
      14.        end
      15.        if type(h) == "function" then
      16.          return (h(table, key))     -- call the handler
      17.        else return h[key]           -- or repeat operation on it
      18.        end
      19.      end

    • “newindex”: The indexing assignment table[key] = value. Note that the metamethod is tried only when key is not present in table.

    • “call”: called when Lua calls a value.

      1.      function function_event (func, ...)
      2.        if type(func) == "function" then
      3.          return func(...)   -- primitive call
      4.        else
      5.          local h = metatable(func).__call
      6.          if h then
      7.            return h(func, ...)
      8.          else
      9.            error(···)
      10.          end
      11.      end