Symbolic (virtual) types for Lua.
Lua's built-in type() only knows eight types, and every table is just a "table". luaVirtualTypes lets you tag a table with a custom type name stored in a __vtype field, and then query it the same way you would use type().
local vtype = require("luavirtualtypes")
local banana = { __vtype = "fruit" }
print(vtype(banana)) --> fruit
print(vtype("text")) --> string
print(vtype(nil)) --> nilIf an object has no __vtype, the module falls back to the regular Lua type, so it works as a drop-in replacement for type().
- Lua >= 5.4
With LuaRocks:
luarocks install luavirtualtypesOr copy source/init.lua into your project.
1) Directly on the object
---@type Virtual_Type_Obj<"fruit">
local banana = { __vtype = "fruit" }2) On an existing object
local apple = {}
vtype:set(apple, "fruit")
---@cast apple Virtual_Type_Obj<"fruit">The @cast line is optional. It only helps the Lua language server (LuaLS) know the type, because it can't track values assigned at runtime.
print(vtype(banana)) --> fruit
print(vtype:vtype(banana)) --> fruit (same thing)
print(vtype(42)) --> numberif vtype:MultOrVerify(obj, "fruit", "vegetable") then
print("it's food")
endMultOrVerify returns true if the type of obj matches any of the given names. Both virtual types and default Lua types are accepted.
| Function | Description |
|---|---|
vtype(obj) |
Shortcut for vtype:vtype(obj). |
vtype:vtype(obj) |
Returns obj.__vtype if obj is a table with a string __vtype, otherwise type(obj). |
vtype:MultOrVerify(obj, ...) |
Returns true if the type of obj equals any of the given names. |
vtype:set(obj, name) |
Sets obj.__vtype = name and returns obj. |
vtype:vtype(obj)raises an error ifobj.__vtypeexists but is not a string.vtype:set(obj, name)raises an error ifobjis not a table ornameis not a string.
__vtypeis read with normal indexing, so it respects__index. A table whose metatable inherits from a "class" will also inherit its virtual type.- Use
:(colon) to call the functions. With.the first argument is taken asself.
The module ships with LuaLS annotations. To get a precise type in your editor, annotate your objects:
---@class Fruit: Virtual_Type_Obj<"fruit">MIT, see LICENSE.
davi / pessoa736