mtype – efficient enhanced types for Lua

mtype is a library that provides an enhanced version of the type function that looks for __type metafield on a table and userdata. For best performance it’s implemented both in Lua (for LuaJIT) and C (for Lua/PUC).

The Lua builtin function type has a disadvantage: it only returns a “primitive” Lua type of a value. So if you want to implement your own typing system with custom type names, type won’t provide you any interesting information:

local chair = setmetatable({}, { __type = 'Chair' })
print(type(chair))  -- prints 'table'

Some libraries (such as the I/O library included with standard Lua) offer alternative type functions for identifying types used within that library:

local value = io.open('/dev/null')
print(io.type(value))  -- prints 'file'

mtype allows you to define your own type tags:

local type = require('mtype').type

local chair = setmetatable({}, { __type = 'Chair' })
print(type(chair))  -- prints 'Chair'

print(type('allons-y!'))  -- prints 'string'
print(type(io.open('/dev/null')))  -- prints 'file'

mtype is very simple: it looks for a __type metafield on a table. If it’s a function, it passes the value to the function and uses the result as the type name. If it’s a string, it uses that. If __type is nil or returns nil, the builtin io.type or type is used.

TODO describe function istype

Installation

You can install mtype using LuaRocks (the Lua package manager):

luarocks install mtype

or to get the latest development version:

luarocks install --server=http://luarocks.org/dev mtype

Note: If you want to bootstrap development environment for running tests, read the next section.

Set up development environment

1. Clone this repository:

   git clone https://github.com/jirutka/mtype.git
   cd mtype

2. Source file .envrc into your shell (or manually add $(pwd)/.venv/bin to your PATH):

   source .envrc

3. Install Lua and modules for running tests into directory .venv:

   ./script/bootstrap

4. Start hacking!

• Build native extension:

  ./script/build

• Run tests and linters:

  ./script/test

• Run benchmarks:

  lua bench.lua

Performance

Lua 5.3.4

value	type	mtype (pure)	mtype (native)
number	1.0	2.3	1.1
string	1.0	2.2	1.2
table without __type	1.0	5.0	1.6
table with string __type	1.0	4.9	1.4
table with func __type	1.0	6.3	2.4

LuaJIT 2.1 (disabled JIT)

value	type	mtype (pure)	mtype (native)
number	1.0	1.7	2.7
string	1.0	1.7	2.6
table without __type	1.0	2.4	3.3
table with string __type	1.0	2.6	2.6
table with func __type	1.0	2.9	3.0

Note: These numbers are measured with disabled JIT, so they represent the worst case. When you run this benchmark with enabled JIT, then “type” and “mtype (pure)” finishes basically in no time.

Acknowledgement

This library is functionally the same as lua-typical, just much faster.

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.