[luadist-git] add pluto-2.4-Windows-x86

dist.info

@@ -0,0 +1,31 @@
+type = "x86"
+arch = "Windows"
+author = "Ben Sunshine-Hill"
+depends = {
+[[lua ~> 5.1]],
+}
+
+desc = "Heavy duty persistence for Lua"
+version = "2.4"
+maintainer = "Peter Kapec"
+files = {
+Runtime = {
+[[lib\lua\pluto.dll]],
+}
+,
+Data = {
+[[share\pluto\README]],
+[[share\pluto\THANKS]],
+[[share\pluto\CHANGELOG]],
+}
+,
+Test = {
+[[share\pluto\test\pptest.lua]],
+[[share\pluto\test\puptest.lua]],
+}
+,
+}
+
+license = "Public domain"
+name = "pluto"
+url = "http://lua-users.org/wiki/PlutoLibrary"

share/pluto/CHANGELOG

@@ -0,0 +1,38 @@
+$Id$
+
+-- 2.4 --
+* Changed upval unboxing to allow upvals which contain func-housed cycles
+* Added stack checking to all stack-growing functions
+* Serialized debug information for functions
+
+-- 2.3 --
+* Added LUALIB_API declaration for luaopen_pluto
+
+-- 2.2 --
+* Rolled all internal Lua dependencies into the Pluto distribution
+* Made the unit tests depend on dynamically loading Pluto
+
+-- 2.1 --
+* Various fixes to make the GC happy
+* stack size always expanded where necessary
+* fixed some memory leaks
+* GC disabled during unpersist
+* callstack initialized for traversal
+
+This changelog is maintained as of version 2.0alpha1. 
+Earlier versions are changelogged on the LuaForge site.
+
+-- 2.0 --
+* Fixed a few format changes to 5.1.3
+* Fixed myriad warnings
+* GCC compliance: not incrementing cast results
+* Fix for self-referring upvals
+* Renamed loading function to work with Lua module system
+* Loading tables with __newindex works
+* unpersist makes buffer copy
+
+-- 2.0alpha1 --
+* Fixed all outstanding 5.0->5.1 conversion issues
+* Made heavier use of size_t in preference to int
+* Fixed GC/Upval issue (thanks to Eric Jacobs)
+

share/pluto/README

@@ -0,0 +1,133 @@
+$Id$
+
+PLUTO - Heavy duty persistence for Lua
+
+Pluto is a library which allows users to write arbitrarily large portions
+of the "Lua universe" into a flat file, and later read them back into the
+same or a different Lua universe. Object references are appropriately
+handled, such that the file contains everything needed to recreate the
+objects in question.
+
+Pluto has the following major features: 
+* Can persist any Lua function
+* Can persist threads 
+* Works with any Lua chunkreader/chunkwriter 
+* Support for "invariant" permanent objects, of all datatypes
+* Can invoke metafunctions for custom persistence of tables and userdata
+
+Pluto 2.2 requires Lua 5.1.3. If you need to use Pluto with Lua
+5.0, please use version 1.2 of Pluto.
+
+Starting with version 2.2, Pluto no longer depends on the Lua sources.
+Instead, it subsumes the required headers into its own codebase.
+As a result, it may not work properly with Lua version 5.1.4 or later.
+
+Pluto may have bugs. Users are advised to define lua_assert in 
+luaconf.h to something useful when compiling in debug mode, to catch
+assertions by Pluto and Lua.
+
+The Pluto library consists of two public functions.
+
+int pluto_persist(lua_State *L, lua_Chunkwriter writer, void *ud)
+
+This function recursively persists the Lua object in stack position 2
+and all other objects which are directly or indirectly referenced by
+it, except those referenced in the permanent object table. The data
+is written using the chunk-writer given, and that writer is passed
+the arbitrary pointer value ud.
+
+The Lua stack must contain exactly and only these two items, in order:
+
+1. A table of permanent objects, that should not be persisted. For each
+permanent object, the object itself should be the key, and a unique
+object of any type should be the value. Likely candidates for this table 
+include Lua functions (including those in the Lua libraries) that are 
+loaded at load-time. It must include all non-persistable objects that 
+are referenced by the object to be persisted. The table is not modified 
+by the function. Objects in this table are considered "opaque" and are 
+not examined or descended into. Objects should not appear in the table 
+multiple times; the result of doing this is undefined (though probably 
+harmless). NOTE: If you are planning to persist threads, keep in mind 
+that all yielded threads have coroutine.yield on the tops of their 
+stacks. Since it's a C function, it should be put here.  For complex 
+permanents, it may be a good idea to use the __index meta-function of 
+the permanents table to "search" for permanents.
+
+2. The single object to be persisted. In many cases, this will be the
+global table. For more flexibility, however, it may be something like a
+table built for the occasion, with various values to keep track of. The
+object may not be nil.
+
+
+int pluto_unpersist(lua_State *L, lua_Chunkreader reader, void *ud)
+
+This function loads in a Lua object and places it on top of the stack. All
+objects directly or indirectly referenced by it are also loaded.
+
+The Lua stack must contain, as its top value, a table of permanent
+objects. This table should be like the permanent object table used when
+persisting, but with the key and value of each pair reversed. These 
+objects are used as substitutes for those referenced in their positions 
+when persisting, and under most circumstances should be identical objects
+to those referenced in the permanents table used for persisting. It's 
+okay for multiple keys to refer to the same object.
+
+
+RUNNING PLUTO FROM LUA:
+It is also possible to invoke pluto from a Lua script. The C function
+pluto_open() will register pluto.persist and pluto.unpersist, lua functions
+which operate on strings. The first takes a permanents table and a root 
+object, and returns a string; the second takes a permanents table and a 
+string, and returns the root object.
+
+An error will be raised if pluto.persist is called from a thread which is
+itself referenced by the root object.
+
+SPECIAL PERSISTENCE:
+Tables and userdata have special persistence semantics. These semantics are
+keyed to the value of the object's metatable's __persist member, if any. This
+member may be any of the following four values:
+1. Boolean "true": The table or userdata is persisted literally; tables are
+persisted member-by-member, and userdata are written out as literal data.
+2. Boolean "false": An error is returned, indicating that the object cannot
+be persisted.
+3. A function: This function should take one argument, the object in question,
+and return one result, a closure. This "fixup closure", in turn, will be 
+persisted, and during unpersistence will be called. The closure will be 
+responsible for recreating the object with the appropriate data, based on 
+its upvalues.
+4. Nil, or no metatable. In the case of tables, the table is literally
+persisted. In the case of userdata, an error is returned.
+
+Here's an example of special persistence for a simple 3d vector object:
+
+vec = { x = 2, y = 1, z = 4 }
+setmetatable(vec, { __persist = function(oldtbl)
+	local x = oldtbl.x
+	local y = oldtbl.y
+	local z = oldtbl.z
+	local mt = getmetatable(oldtbl)
+	return function()
+		newtbl = {}
+		newtbl.x = x
+		newtbl.y = y
+		newtbl.z = z
+		setmetatable(newtbl, mt)
+		return newtbl
+	end
+end })
+
+Note how x, y, z, and the mt are explicitly pulled out of the table. It is 
+important that the fixup closure returned not reference the original table 
+directly, as that table would again be persisted as an upvalue, leading to an 
+infinite loop. Also note that the object's metatable is NOT automatically 
+persisted; it is necessary for the fixup closure to reset it, if it wants.
+
+LIMITATIONS/TODO: 
+* Light userdata are persisted literally, as their pointer values. This 
+may or may not be what you want.  
+* Closures of C functions may not be persisted. Once it becomes possible
+to specify a C function "proto" as a permanent object, this restriction
+will be relaxed.
+
+BUGS: None known. Emphasis on the 'known'.

share/pluto/THANKS

@@ -0,0 +1,10 @@
+Pluto is surprisingly robust and useful. This would not be the case without
+the hard work and helpfulness of the following people, mentioned in no
+particular order:
+
+Ivko Stanilov
+Goran Adrinek
+Eric Jacobs
+Anolan Milanes
+Malte Thiesen
+

share/pluto/test/pptest.lua

@@ -0,0 +1,168 @@
+-- $Id$
+
+require "pluto"
+
+permtable = { 1234 } 
+
+perms = { [coroutine.yield] = 1, [permtable] = 2 }
+
+twithmt = {}
+setmetatable( twithmt, { __call = function() return 21 end } )
+
+function testfenv()
+	return abc
+end
+
+setfenv(testfenv, { abc = 456 })
+
+function fa(i)
+	local ia = i + 1
+	return fb(ia)
+end
+
+function fb(i)
+	local ib = i + 1
+	ib = ib + fc(ib)
+	return ib
+end
+
+function fc(i)
+	local ic = i + 1
+	coroutine.yield()
+	return ic*2
+end
+
+function func()
+	return 4
+end
+
+thr = coroutine.create(fa)
+coroutine.resume(thr, 2)
+
+testtbl = { a = 2, [2] = 4 }
+
+function funcreturningclosure(n)
+	return function()
+		return n
+	end
+end
+
+function nestedfunc(n)
+	return (function(m) return m+2 end)(n+3)
+end
+
+testloopa = {}
+testloopb = { testloopa = testloopa }
+testloopa.testloopb = testloopb
+
+sharedref = {}
+refa = {sharedref = sharedref}
+refb = {sharedref = sharedref}
+
+sptable = { a = 3 }
+
+setmetatable(sptable, { 
+	__persist = function(tbl)
+		local a = tbl.a
+		return function()
+			return { a = a+3 }
+		end
+	end 
+})
+
+literaludata = boxinteger(71)
+
+function booleanpersist(udata)
+	local b = unboxboolean(udata)
+	return function()
+		return boxboolean(b)
+	end
+end
+
+function makecounter()
+	local a = 0
+	return {
+		inc = function() a = a + 1 end,
+		cur = function() return a end
+	}
+end
+
+function uvinthreadfunc()
+	local a = 1
+	local b = function()
+		a = a+1
+		coroutine.yield()
+		a = a+1
+	end
+	a = a+1
+	b()
+	a = a+1
+	return a
+end
+
+uvinthread = coroutine.create(uvinthreadfunc)
+coroutine.resume(uvinthread)
+
+niinmt = { a = 3 }
+setmetatable(niinmt, {__newindex = function(key, val) end })
+
+
+
+
+local function GenerateObjects()
+   local Table = {}
+
+   function Table:Func()
+       return { Table, self }
+   end
+
+   function uvcycle()
+       return Table:Func()
+   end
+end
+
+GenerateObjects()
+
+
+
+function debuginfo(foo)
+	foo = foo + foo
+	return debug.getlocal(1,1)
+end
+
+rootobj = {
+	testfalse = false,
+	testtrue = true,
+	testseven = 7,
+	testfoobar = "foobar",
+	testfuncreturnsfour = func,
+	testnil = nil,
+	testthread = thr,
+	testperm = permtable,
+	testmt = twithmt,
+	testtbl = testtbl,
+	testfenv = testfenv,
+	testclosure = funcreturningclosure(11),
+	testnilclosure = funcreturningclosure(nil),
+	testnest = nestedfunc,
+	testludata = createludata(),
+	testlooptable = testloopa,
+	testsharedrefa = refa,
+	testsharedrefb = refb,
+	testsptable = sptable,
+	testliteraludata = literaludata,
+	testspudata1 = boxboolean(true),
+	testspudata2 = boxboolean(false),
+	testsharedupval = makecounter(),
+	testuvinthread = uvinthread,
+	testniinmt = niinmt,
+	testuvcycle = uvcycle,
+	testdebuginfo = debuginfo
+}
+
+buf = pluto.persist(perms, rootobj)
+
+onerror()
+outfile = io.open("test.plh", "wb")
+outfile:write(buf)
+outfile:close()