lua-immutable/README.md

# ImmuTable

This is a native Lua library that allows the creation of 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>`).

## 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()
```

## Tuple recipe
With immutable tables, it's pretty simple to emulate Python-like tuples:
```lua
local tuple_classes = {}
Tuple = function(...)
    local n = select('#', ...)
    if not tuple_classes[n] then
        tuple_classes[n] = immutable(n)
    end
    return tuple_classes[n](...)
end
assert(Tuple(5,6,7) == Tuple(5,6,7))
assert(tostring(Tuple(8,9)) == "(8, 9)")
```

## General purpose immutable table recipe
Using the tuple recipe above, you can make a function that returns an immutable version
of a table with arbitrary keys.
```lua
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})
```

## Implementation details
Under the hood, immutable tables are implemented in C as a userdata (that stores a hash value) with a metatable. That metatable has a weak-keyed mapping from hash -> userdata -> associated data. Immutable tables *are* garbage collected, so if you no longer have any references to the userdata, the userdata will get garbage collected, which will result in the entry being removed from the metatable's mapping. When new instances are created, a hash value is computed, and all the data in the associated hash bucket is scanned to look for duplicates. If a match is found, that existing instance is returned, otherwise a new one is created and added to the hash bucket. The following lua pseudocode approximates the C implementation's behavior:
```lua
function immutable(fields, class_fields)
    local cls = {
        __index = function(self, key)
            local cls = getmetatable(self)
            if cls.indices[key] then
                local data = cls.__instances[extract_hash(self)]
                return data[cls.indices[key]]
            else
                return cls[key]
            end
        end,
        __gc = function(self)
            local __instances = getmetatable(self).__instances
            local hash = extract_hash(self)
            __instances[hash][self] = nil
            if not next(__instances[hash]) then __instances[hash] = nil end
        end,
        -- also: __len, __pairs, __ipairs, __tostring, from_table, is_instance
    }
    for k,v in pairs(class_fields) do cls[k] = v end
    cls.__fields, cls.__indices = fields, {}
    for i,f in ipairs(fields) do cls.__indices[f] = i end
    cls.__instances = setmetatable({}, {__index=function(self, key)
        local bucket = setmetatable({}, {__mode='k'})
        self[key] = bucket
        return bucket
    end})
    return setmetatable(cls, {
        __call=function(cls, ...)
            local hash = make_hash(...)
            local bucket = cls.__instances[hash]
            for userdata, data in pairs(bucket) do
                local match = true
                for i=1,select('#',...) do
                    if data[i] ~= select(i, ...) then
                        match = false
                        break
                    end
                end
                if match then return userdata end
            end
            local userdata = setmetatable(new_userdata(hash), cls)
            bucket[userdata] = {...}
            return userdata
        end
    })
end
```