lua-immutable/README.md

# ImmuTable

This is a Lua library that allows the creation of lightweight immutable tables.

## Build

This code has been tested with Lua 5.1.5, Lua 5.2.3, Lua 5.3.5, and LuaJIT 2.0.5. To build, simply `make` or for LuaJIT: `make LUA=luajit` (you can also optionally specify `LUA_INC=<path to the directory containing lua.h and lauxlib.h>` or `LUA_BIN=<path to the directory containing the lua binary>`).

Or, with [luarocks](https://luarocks.org/): `luarocks make immutable-table-scm-1.rockspec`

## Usage
Here's a simple implementation of a 2-d vector using immutable tables:
```lua
immutable = require "immutable"
Vec = immutable({"x","y"}, {
    name='Vector',
    len2=function(self)
        return self.x*self.x + self.y*self.y
    end,
    class_variable = "classvar",
    __add=function(self, other)
        local cls = getmetatable(self)
        return cls(self.x+other.x, self.y+other.y)
    end,
})
v = Vec(2, 3)
assert(v.x == 2 and v.y == 3)
also_v = Vec(2, 3)
assert(v == also_v)
t = {[v]='yep'}
assert(t[also_v] == 'yep')
assert(v + Vec(0,1) == Vec(2,4))
assert(#v == 2)
assert(v:len2() == 13)
assert(v.class_variable == "classvar")
assert(tostring(v) == 'Vector(x=2, y=3)')
assert(Vec:is_instance(v) and not Vec:is_instance({x=2,y=3}))
for k, v in pairs(v) do
    assert((k == 'x' and v == 2) or (k == 'y' and v == 3))
end
for i, v in ipairs(v) do
    assert((i == 1 and v == 2) or (i == 2 and v == 3))
end
NotVec = immutable({"x","y"})
assert(NotVec(1,2) ~= Vec(1,2))
```

## Singleton recipe
Singletons are pretty straightforward:
```lua
Singleton = immutable()
assert(Singleton() == Singleton())
```
Or if you want methods/class variables:
```lua
DogSingleton = immutable(0, {name="DogSingleton", bark=function(self) print("woof") end})
DogSingleton():bark()
```

## Tuples
If no field names are passed in, `immutable()` defaults to creating immutable tables that behave like Python's tuples:
```lua
local Tuple = immutable()
local t0 = Tuple()
local t1 = Tuple(1,2)
local t2 = Tuple(1,2,3,4,5)
assert(t0 == Tuple())
assert(({[t1]='yep'})[Tuple(1,2)])
assert(tostring(Tuple(1,2)) == "(1, 2)")
```

## New Metamethods
This library adds support for two new user-defined metamethods: `__new` and `__missing`. `__new` is called when an instance is created. It takes as arguments the immutable class and all arguments the user passed in, and whatever values it returns are used to create the instance. This is pretty handy for default or derived values.
```lua
local Foo = immutable({"x","y","xy"}, {
    __new = function(cls, x, y)
        y = y or 3
        return x, y, x*y
    end
})
assert(Foo(2).xy == 6)
```
`__missing` is similar to `__index`, except that it only gets called when accessing a key that is neither one of the immutable class's instance keys, nor one of the keys in the class table.
```lua
local Foo = immutable({"x","y"}, {
    classvar = 23,
    __missing = function(self, key)
        return "MISSING"
    end
})
local f = Foo(1, nil)
assert(f.x == 1 and f.y == nil and f.classvar == 23 and f.asdf == "MISSING")
```
If you override `__index` instead of `__missing`, the function you provide will get called for every member access, even valid keys, since immutable table instances are userdatas.

The library also defines a `__hash` metamethod that returns the hash value used internally for instances. Overriding this value does not affect the underlying implementation, but you may find it useful for overriding `__index`:
```lua
local Foo
Foo = immutable({"x","y"}, {
    classvar = 23,
    __index = function(self, key)
        local cls = getmetatable(self)
        if cls.__indices[key] != nil then
            local value = cls.__instances[cls.__hash(self)][self][key]
            return value == nil and "nil inst value" or value
        else
            local value = cls[key]
            return value == nil and "undefined value" or value
        end
    end
})
local f = Foo(1,nil)
assert(f.x == 1 and f.y == "nil inst value" and f.classvar == 23 and f.asdf == 999)
```

## General purpose immutable table recipe
Using tuples, you can make a function that returns an immutable version of a table with arbitrary keys, though it is a little bit hacky.
```lua
local Tuple = immutable()
local immutable_classes = {}
Immutable = function(t)
    local keys = {}
    for k,_ in pairs(t) do keys[#keys+1] = k end
    keys = Tuple(unpack(keys))
    if not immutable_classes[keys] then
        immutable_classes[keys] = immutable(keys, {name="Immutable"})
    end
    return immutable_classes[keys]:from_table(t)
end
assert(Immutable{x=1} == Immutable{x=1})
assert(Immutable{a=1,b=2,c=3} == Immutable{a=1,b=2,c=3})
```

## Performance
This library is pretty dang fast, but it's still slower than native Lua tables. Based on my local testing, immutable tables add a couple nanoseconds to table operations in the worst case scenario. In LuaJIT, there is a bigger performance discrepancy because regular tables are more heavily optimized in LuaJIT. Your mileage may vary, but I'd say that immutable tables will probably never be a performance bottleneck for your program, especially if you use them in place of code that already used a constructor function and metatables. In some cases, immutable tables may also help reduce your program's memory footprint (if your program has many duplicate objects in memory) and may even improve speed (e.g. if your program uses a lot of deep equality checks). Don't trust this paragraph though! If in doubt, profile your code!

## Implementation details

You can read more about the implementation details in the [implementation documentation](./implementation.md).