local _ENV = mkmodule('persist-table')

--[[

persist-table.lua

author expwnent

This module is intended to help facilitate persistent table lookups.

It is a wrapper over dfhack.persistent calls.

It supports tables of arbitrary dimension and shape.

It stores information about each table and subtable's size and children.

For convenience, all stored information is itself persistent.

It would be more efficient to cache stored information in global variables and update it on save/load but this is not yet implemented.

Ask expwnent to try this if performance is bad.

Usage:

local persistTable = require 'persist-table'

persistTable.GlobalTable.doomitude = 'doom!' -- will be stored persistently

print(persistTable.GlobalTable.doomitude) --doom!

persistTable.GlobalTable.doomitude = nil --delete the persistent record

print(persistTable.GlobalTable.doomitude) --nil

persistTable.GlobalTable.mana = {} --allocate a subtable for mana

local mana = persistTable.GlobalTable.mana --setting elements in this table will be persistent too

mana['1'] = '3' --slightly faster than persistTable.GlobalTable.mana['1'] = '3'

--be aware that if you don't change the local variable mana when the game exits and reloads a different save you will run into mysterious problems so don't do that

mana['2'] = '100'

mana.maximum = '1000' --tables can be any arbitrary shape

local globalTable = persistTable.GlobalTable --this is safe too

globalTable.mana = nil --this is safe: it will deallocate all subtables cleanly

globalTable.revengeDesire = {}

--globalTable.revengeDseire.foo = {} -- error: tables must be allocated first with parentTable.subtableName = {}

--you can check if it exists with globalTable.tableName != nil

local revengeTable = globalTable.revengeDesire

revengeTable['2'] = revengeTable['2'] or {} --this is fine too

revengeTable['2']['3'] = 'totally a lot, man'

revengeTable['3'] = {}

revengeTable['3']['2'] = 'maybe a little bit'

revengeTable['2'] = nil

-------------

And so on.

Be careful not to name your tables in a way that will conflict with other scripts! The easiest way is to just put all your tables in one giant table named based on your script.

All stored values MUST be strings. Numbers can be supported later but are not yet supported. Keep in mind there is a significant overhead for each table element so don't go totally crazy storing massive amounts of information or the game will run out of RAM.

--table._children returns a list of child keys

for _,childKey in ipairs(table._children) do

local child = table[childKey]

--blah

end

--]]

local prefix = 'persist-table'

local function ensure(name)

return dfhack.persistent.save({key=name})

end

local function gensym()

local availables = dfhack.persistent.get_all(prefix .. '$available') or {}

local available = nil

local smallest = nil

for _,candidate in pairs(availables) do

--TODO: it would be great if we could iterate over these in order but we can't

local score = tonumber(candidate.value)

--print('gensym', candidate, score, available, smallest)

if (score and (not available or score < smallest)) then

smallest = score

available = candidate

end

end

if available then

local value = available.value

available:delete()

--print('gensym: allocate ' .. value)

return value

end

--none explicitly available, so smallest unused is the next available number

local smallestUnused = ensure(prefix .. '$smallest_unused')

if smallestUnused.value == '' then

smallestUnused.value = '0'

end

local result = smallestUnused.value

smallestUnused.value = tostring(1+tonumber(result))

smallestUnused:save()

--print('gensym: allocate ' .. result)

return result

end

local function releasesym(symb)

local availables = dfhack.persistent.get_all(prefix .. '$available') or {}

for _,available in pairs(availables) do

--print('releasesym: ', symb, available.value, available)

if available.value == symb then

print('error: persist-table.releasesym(' .. symb .. '): available.value = ' .. available.value)

return

end

end

dfhack.persistent.save({key=prefix .. '$available', value=symb}, true)

--print('releasesym: unallocate ' .. symb)

end

local intCount = 7

local existIndex = intCount-0

local existValue = 1

local pointerIndex = intCount-1

local pointerValue = 1

local defaultValue = -1

local function isEmpty(table)

return next(table) == nil

end

local function deletePersistent(name)

if name == '' then

return

end

local children = dfhack.persistent.get_all(prefix .. name) or {}

for _,childKey in ipairs(children) do

local childEntry = ensure(prefix .. name .. '$$' .. childKey.value)

if childEntry.ints[existIndex] == existValue and childEntry.ints[pointerIndex] == pointerValue then

deletePersistent(childEntry.value)

end

childEntry:delete()

childKey:delete()

end

releasesym(name)

end

GlobalTable = GlobalTable or {key = 'mastertable'}

GlobalTable.mt = GlobalTable.mt or {}

GlobalTable.mt.__index = GlobalTable.mt.__index or function(theTable, key)

if key == '_children' then

return rawget(theTable,key)

end

--print(rawget(theTable,'key') .. '[' .. key .. ']')

local entry = ensure(prefix .. rawget(theTable,'key') .. '$$' .. key)

if entry.ints[existIndex] == existValue and entry.ints[pointerIndex] == defaultValue then

--print('string: ' .. entry.value)

return entry.value

end

if entry.ints[pointerIndex] == pointerValue then

--pre-existing pointer

local result = {key = entry.value}

result.mt = rawget(GlobalTable,'mt')

local childArgs = dfhack.persistent.get_all(prefix .. entry.value)

result._children = {}

for _,childArg in ipairs(childArgs or {}) do

--print(result._children, childArg.value)

table.insert(result._children, childArg.value)

end

setmetatable(result,rawget(GlobalTable,'mt'))

--print('theTable: ' .. entry.value)

return result

end

entry:delete()

--print 'theTable[key] does not exist.'

return nil

end

GlobalTable.mt.__newindex = GlobalTable.mt.__newindex or function(theTable, key, value)

--print(rawget(theTable,'key') .. '[' .. key .. '] = ' .. tostring(value))

local entry = ensure(prefix .. rawget(theTable,'key') .. '$$' .. key)

local old = entry.value

local isNew = entry.ints[existIndex] == defaultValue

if entry.ints[existIndex] == existValue and entry.ints[pointerIndex] == pointerValue then

if type(value) == 'table' and rawget(value,'mt') == rawget(GlobalTable,'mt') and entry.value == rawget(value,'key') then

--if setting it to the same table it already is, then don't do anything

return

end

deletePersistent(entry.value)

end

if not value then

--print('__newindesx: delete')

--delete

for i,child in ipairs(dfhack.persistent.get_all(prefix .. rawget(theTable,'key')) or {}) do

if child.value == key then

child:delete()

end

end

entry:delete()

return

elseif type(value) == 'string' then

--print('__newindesx: string')

entry.value = value

entry.ints[pointerIndex] = defaultValue

entry.ints[existIndex] = existValue

entry:save()

if isNew then

--print('new child!')

dfhack.persistent.save({key=prefix .. rawget(theTable,'key'), value=key}, true)

end

return

elseif type(value) == 'table' then

--print('__newindesx: table')

if rawget(value,'mt') ~= rawget(GlobalTable,'mt') then

if not isEmpty(value) then

error('setting value to an invalid table')

end

--print('__newindesx: empty table')

--empty table: allocate a thing

entry.ints[pointerIndex] = pointerValue

entry.ints[existIndex] = existValue

entry.value = gensym()

entry:save()

if isNew then

--print('new child!')

dfhack.persistent.save({key=prefix .. rawget(theTable,'key'), value=key}, true)

end

return

end

--print('__newindesx: table assignment')

entry.value = rawget(value,'key')

entry.ints[pointerIndex] = pointerValue

entry.ints[existIndex] = existValue

entry:save()

if isNew then

--print('new child!')

dfhack.persistent.save({key=prefix .. rawget(theTable,'key'), value=key}, true)

end

return

else

error('type(value) = ' .. type(value))

end

end

setmetatable(GlobalTable, GlobalTable.mt)

return _ENV