lua-immutable/README.md

# ImmuTable

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

## Build

Lua 5.1/5.2/5.3+ or LuaJIT 2.0+ built from source code is a prerequisite. Lua can be downloaded from the [lua.org downloads page](https://www.lua.org/ftp/), and LuaJIT can be downloaded from the [LuaJIT.org downloads page](http://luajit.org/download.html).

`make` or for LuaJIT: `make LUA=luajit` (you can also optionally specify the path to the directory containing lua.h and lauxlib.h with `LUA_INC` and the path to the directory containing the lua binary with `LUA_BIN`).

## Usage

```
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:
```
Singleton = immutable()
assert(Singleton() == Singleton())
```
Or if you want methods/class variables:
```
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:
```
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)")
```