Skip to main content

Using Squirrel Metamethods

How To Override Operators In Classes And Tables

Metamethods allow Squirrel programmers to override existing language operators. Essentially each metamethod provides a means by which Squirrel can substitute your functionality for its own, standard operations whenever it encounters one of a specific set of operators.

This is best explained with an example. When Squirrel encounters any one of the relative comparison operators — <=, >=, < and > — to the right of an object, it immediately looks in that object’s specified delegate (if it has one) for the _cmp metamethod. If Squirrel finds a function named _cmp(), it will call that function, otherwise it runs code of its own. There is a full list of available metamethods at the end of this guide.

An instance’s delegate is always its Squirrel type or custom class. Tables have no delegate by default, but you can set one (always another table) using its setdelegate() method. Of course, you will also have to write a custom _cmp() function. The code below provides an example of the use of another metamethod, _newslot, which is triggered by the <-operator:

function _newslot(key, value) {
    // _newslot metamethod must take two parameters
    server.log("Slot '" + key + "' added (value: " + value + ")");
}

local prefs = {};
prefs.setdelegate(this);
prefs.on <- true;
prefs.red <- 0;
prefs.green <- 0;
prefs.blue <- 255;
prefs.brightness <- 100;

Run this code and you will see the following in the log:

2015-11-20 10:14:27 [agent.log] Slot 'on' added (value: true)
2015-11-20 10:14:27 [agent.log] Slot 'red' added (value: 0)
2015-11-20 10:14:27 [agent.log] Slot 'green' added (value: 0)
2015-11-20 10:14:27 [agent.log] Slot 'blue' added (value: 255)
2015-11-20 10:14:27 [agent.log] Slot 'brightness' added (value: 100)

For simplicity, we have defined _newslot() in Squirrel’s root table, referenced here by this. Tables have no delegate by default, so we need to explicitly add one to prefs using the setdelegate() method. Your metamethod definitions for operators performed on tables are always entered into this second, delegate table. Your delegate need not be the root table, but can instead be — and more commonly is — a specially created table:

local delegateTable = {
    function _newslot(key, value) {
        server.log("Slot '" + key + "' added (value: " + value + ")");
    }
}

local prefs = {};
prefs.setdelegate(delegateTable);
prefs.on <- true;
prefs.red <- 0;
prefs.green <- 0;
prefs.blue <- 255;
prefs.brightness <- 100;

The _newslot() function only works for prefs; slots created in other tables will be created as normal, unless they too have had delegateTable or another table set as their delegate.

Metamethods only work with certain entities — tables, class objects and class instances — and a given metamethod will not necessarily work with all of those entities. The metamethod _newslot, used above, is only relevant to tables, not to class instances or class objects.

For instances of Squirrel classes, the approach is slightly different: the ‘delegate’ is always the class itself. All instances of the same class therefore share the same delegate, and you declare your metamethods in the class definition. You can’t call setdelegate() on an instance, and you can’t use a class as the delegate of a table.

You may have noticed that _newslot() doesn’t actually create the slot. It needs to do this, since Squirrel is now relying on it to do so. All we have to do is add a line to _newslot():

function _newslot(key, value) {
    server.log("Slot '" + key + "' added (value: " + value + ")");
    this[key] <- value;
}

this is the hidden parameter passed into all function calls that points to the object making the call — in this case, the table prefs. We put key in square brackets because this is Squirrel syntax for creating a new slot whose name is the value of key, ie. not the string "key" itself.

If you’re also interested in the removal of slots from a table, you can use the _delslot metamethod to override Squirrel’s delete keyword.

Squirrel also provides two other metamethods, _set and _get, which can be used when working with tables (and class instances). Remember, everything in Squirrel is, at heart, a table. _get is called when your delegated table attempts to get a value from a key that doesn’t exist. Instead of simply reporting the usual “missing index” runtime error, Squirrel gives you a chance to override that behavior:

function _get(key) {
    // The delegated table has no key 'key' so
    // report it, but don't cause a runtime error
    server.error("Index '" + key + "' doesn’t exist");
}

_set works the same way, but for cases where you are attempting to set a value to a non-existent slot:

function _set(key, value) {
    // The delegated table has no key 'key' so
    // report it, but don't cause a runtime error
    server.error("Index '" + key + "' doesn’t exist");
}

Metamethod Restrictions On Agents

If you run the above examples in agent code, you may get the error “halting stuck metamethod”. This arises because Squirrel agent code is time-sliced with all other Squirrel agent code. For technical reasons, Squirrel can’t be time-sliced while executing a metamethod. So each metamethod call is limited to a single time-slice (1000 Squirrel compiled bytecode instructions) before it is aborted as a potential CPU hog, ie. potentially unfair to other agents running on the same system. There is no way around this other than to make the metamethod use fewer instructions.

Device-side Squirrel code, which can’t be ‘unfair’ to anyone except itself and so is not time-sliced, does not have this restriction.

Applying Metamethods

So what, then, are metamethods actually for? Why would you use them?

Essentially, metamethods provide you with a means to create new data types which require operations not supported by standard Squirrel.

For example, let’s say your application works with points in three-dimensional space. You might create a class to represent each such point:

class Point {
    x = 0;
    y = 0;
    z = 0;

    constructor (...) {
        // NOTE the parameter ... passes all arguments as the array 'vargv'
        if (vargv.len() != 3) throw "Three co-ordinates (x,y,z), please";
        x = vargv[0];
        y = vargv[1];
        z = vargv[2];
    }
}

If we have two Point instances and we wish to multiply them, the following code will produce the wrong result:

local p1 = Point(1,2,3);
local p2 = Point(5,6,7);
local p3 = p1 * p2;

This is because p1 and p2 are references to the two instances of Point, so p3 will be the product of those references. In fact, this is an operation that Squirrel doesn’t allow — try the code above and you’ll get an “arith op * on between ‘instance’ and ‘instance’” error. Clearly, this isn’t what we want: we expect p3 to be an instance of Point generated by multiplying the two other co-ordinate sets (ie. two 3 x 1 matrices). So we need to override the * operator. To do this, we use the metamethod _mul, which we add to the Point class definition:

function _mul(p) {
    return Point(x * p.x, y * p.y, z * p.z);
}

This time when Squirrel reaches the * operator following a Point instance, it checks for and finds _mul() in p1 and uses that method in place of its usual multiplication routine, by passing p2 into p1’s _mul() method. We can confirm that by adding:

server.log("("+ p3.x + "," + p3.y + "," + p3.z + ")");

which logs:

2015-11-20 12:46:47 [agent.log] (5,12,21)

Squirrel provides metamethods for other arithmetic functions: _add, _sub, _div, _mod (modulo, the % operator) and _unm (unary minus, the operator which negates a value).

It’s important to understand that the order of the elements in the statement is important. Squirrel checks for metamethods only on the operand on the left of the operator. For example, you might want to multiply a Point by an integer. Your code can check the value passed into your _mul() code and perform the calculation accordingly. However, you must write such a sum in the following order:

local p3 = p1 * 5;

If you were to write the (ordinarily) mathematically equivalent:

local p3 = 5 * p1;

then Squirrel will throw an error: it sees the first term, the 5, and fixes itself to perform integer math. The Point instance, p1, isn’t an integer, and hence the error message. Even if p1 has a _mul metamethod, it will not be called. p1 must come first. This runs contrary to how a number of other languages handle operator overrides.

There are other metamethods too. For example, if we later want to check whether a poorly name variable, a, is an instance of Point, we can add the following code to the class to make use of the _typeof metamethod:

function _typeof() {
    return "Point";
}

then if we add the following line to the body of our program:

server.log(typeof p3);

we will see:

2015-11-20 12:46:47 [agent.log] Point

A more practical use of this is in the class’ _mul metamethod to make sure that the passed parameter is valid:

function _mul(p2) {
    if (typeof p2 != "Point") throw "Operand is not a Point object";
    return Vector(x * p2.x, y * p2.y, z * p2.z);
}

Other useful metamethods include _tostring, which returns a string representation of the table or instances’s value whenever you call its .tostring() delegate method. For example:

function _tostring() {
    return (x + "," + y + "," + z);
}

will ensure that the code server.log(p3); prints out something useful.

The _nexti metamethod is triggered when a foreach structure loops. You might override this behavior to, say, iterate through every other item.

You can view an example of the use of _nexti in our mbstring library:

function _nexti(previdx) {
    // _str is the internal UTF-8 string buffer:
    // an array of 1-, 2-, 3- or 4-byte strings
    if (_str.len() == 0) {
        return null;
    } else if (previdx == null) {
        return 0;
    } else if (previdx == _str.len() - 1) {
        return null;
    } else {
        return previdx + 1;
    }
}

This code is called as users of the library use a foreach loop to iterate through the components of the UTF-8 string stored by an instance of the library class. For example:

#require "mbstring.class.nut:1.0.0"

local utf8String = mbstring("123«€àâäèéêëîïôœùûüÿçÀÂÄÈÉÊËÎÏÔŒÙÛÜŸ»")
foreach (index, character in utf8String) {
    server.log("Character: " + index + ": " + character);
}

Each time through the loop, Squirrel runs the mbstring’s _nexti() method to determine what the next value of the loop index (here placed in index) will be. In fact, the mbstring library, whose source code you can view in Electric Imp’s public GitHub repo provides a good example of the usage of many of the metamethods discussed above.

You should note, though, that _nexti() only works with class instances — it can’t be used to control an iteration working through a table’s keys, for example.

Both _inherited and _newmember are metamethods that allow you to override what takes place when, respectively, a parent class is overridden by an child class, and a class member entity is declared. _cloned is called when an object is copied. As such these two metamethods are only relevant to class objects. Indeed, they are the only metamethods available to class objects.

Finally, _call can be used in order to call a table or a class instance itself as if it were a function. For example, the following code will fail with the error, ERROR: attempt to call 'instance':

// Define a class
class C {
    function test() { server.log("test() called"); }
};

// Instance the class...
local c = C();

// ...and call the instance
c();

However, adding _call solves this, causing the correct output:

// Define a class
class C {
    function _call(x) { test() };
    function test() { server.log("test() called"); }
};

// Instance the class...
local c = C();

// ...and call the instance
c();

Available Metamethods

Metamethod Operator(s) Parameter(s) Use With Notes
_cmp <, >, <=, >= Operand to the right of the operator Table, class instance Perform a relative comparison, eg. if (a > b) { ... }
Function should return an integer:
1, if a > b
0, if a == b
-1, if a < b
_mul * Operand to the right of the operator Table, class instance Perform a multiplication, eg. local a = b * c
Returns the result
_add + Operand to the right of the operator Table, class instance Perform an addition, eg. local a = b + c
Returns the result
_sub - Operand to the right of the operator Table, class instance Perform a subtraction, eg. local a = b - c
Returns the result
_div / Operand to the right of the operator Table, class instance Perform a division, eg. local a = b / c
Returns the result
_mod % Operand to the right of the operator Table, class instance Perform a modulo, eg. local a = b % c
Returns the result
_unm - Operand to the right of the operator Table, class instance Perform a unary minus, eg. local a = -b
Returns the result
_newslot <- Key and value Table Creates and adds a new slot to a table
_delslot delete Key Table Removes a slot from a table
_set = Key and value Table, class instance Called when code attempts to set a non-existent slot’s key,
eg. table.a = b
_get = Key Table, class instance Called when code attempts to get the value of a non-existent slot,
eg. local a = table.b
_typeof typeof None Table, class instance Returns type of object or class instance as a string,
eg. local a = typeof b
_tostring .tostring() None Table, class instance Returns the value of the object or class instance as a string,
eg. local a = b.tostring()
_nexti foreach… in… Previous iteration index Class instance Called at each iteration of a foreach loop.
Parameter value will be null at the first iteration.
Function must return the next index value
_cloned clone The original instance or table Table, class instance Called when an instance or table is cloned
_inherited New class (as this) and its attributes Class object A parent class method is overridden by a child class
_newmember index, value, attributes, isstatic Class object Called when a new class member is declared. If implemented, members will not be added to the class
_call this and the function’s other (visible) parameters Table, class instance Called when the table or class instance is itself called as a function