Prototype the skang package in Lua. I'll translate this into C later.

1 files changed, 186 insertions, 0 deletions

diff --git a/ClientHamr/GuiLua/skang.lua b/ClientHamr/GuiLua/skang.lua
new file mode 100644
index 0000000..25aedac
--- /dev/null
+++ b/ClientHamr/GuiLua/skang.lua
@@ -0,0 +1,186 @@
+-- Trying to capture best practices here for creating modules, especially since module() is broken and deprecated.
+
+-- Wrapping the entire module in do .. end helps if people just join a bunch of modules together, which apparently is popular.
+-- By virtue of the fact we are stuffing our result into package.loaded[], just plain running this works as "loading the module".
+--   TODO - Except for the "passing the name in as ..." part.  B-(
+do      -- Only I'm not gonna indent this.
+
+
+local skangModuleBegin = function (name, author, copyright, version, timestamp, skin)
+    local _M = {}                       -- This is what we return to require().
+    _M._NAME = name                     -- Catch the module name passed in from require(), so that the file name can change.
+    _M._M = _M                  -- So that references to _M below the setfenv() actually go to the real _M.
+    _M._PACKAGE = string.gsub(_M._NAME, "[^.]*$", "")   -- Strip the name down to the package name.
+
+    _M.AUTHOR = author
+    _M.COPYRIGHT = copyright .. ' ' .. author
+    _M.VERSION = version .. ' lookup version here ' .. timestamp
+    -- TODO - If there's no skin passed in, try to find the file skin .. '.skang' and load that instead.
+    _M.DEFAULT_SKANG = skin
+
+    package.loaded[_M._NAME] = _M       -- Stuff the result into where require() can find it, instead of returning it at the end.
+                                -- Returning it at the end does the same thing.
+                                -- This is so that we can have all the module stuff at the top.
+                                -- Should do this before any further require(), so that circular references don't blow out.
+
+    --_G[_M._NAME] = _M         -- Stuff it into a global of the same name.
+                                -- Not such a good idea to stomp on global name space.
+                                -- It's also redundant coz we get stored in package.loaded[_M._NAME] anyway.
+                                -- This is why module() is broken.
+
+    --local _G = _G                     -- Stop stuff from here leaking into the callers _G.
+                                -- Also works around the setfenv() below discarding all the old globals.
+                                -- Though now we have to use _G.foo to access globals.
+
+    -- An alternative to the local _G is to declare as local ALL our imports here.  May be worthwhile to do both this and local _G?
+    -- basic, is it called "basic", might be called "base"?  Might have to include individual names.
+    _M.print = print
+    _M.getfenv = getfenv
+    _M.setfenv = setfenv
+    _M.require = require
+    _M.coroutine = coroutine    -- Apparently this is part of basic, but it comes in it's own table anyway.
+    _M.package = package
+    _M.string = string
+    _M.table = table
+    _M.math = math
+    _M.io = io
+    _M.os = os
+    _M.debug = debug
+
+    _M.savedEnvironment = getfenv(3)
+    -- setfenv() sets the environment for the FUNCTION, but we are not in a function.
+    -- Though if we are being require()ed, then require() calls a loader, which calls us, hence we are the function.
+    -- The number is the stack level -
+    --   0 running thread, 1 current function, 2 function that called this function, etc
+    setfenv(3, _M)                      -- Use the result for our internal global environment, so we don't need to qualify our internal names.
+                                -- So the below "_M.bar" becomes "bar".  Which might not be what we want, since we are using 
+                                -- _M.bar for the Thing, not the local bar the Thing wraps.  So we leave _M.bar as is, coz we have _M._M above.  B-)
+                                -- Since _M is empty at this point, we loose the other globals, but that's we why declare local copies of stuff above.
+                                -- Dunno if this causes problems with the do ... end style of joining modules.  It does.
+                                -- Next question, does this screw with the environment of the skang module?  No it doesn't, coz that's set up at require 'skang' time.
+
+    return _M
+end
+
+-- This is so the setfenv() stack count above is correct, and we can access ThingSpace in the final moduleBegin() version below, and STILL use this for ourselves.  lol
+local smb = function (name, author, copyright, version, timestamp, skin)
+    local result = skangModuleBegin(name, author, copyright, version, timestamp, skin)
+    return result
+end
+
+local _M = smb(..., 'David Seikel', '2014', '0.0', '2014-03-19 19:01:00', nil)
+
+ThingSpace = {}
+ThingSpace.cache = {}
+ThingSpace.commands = {}
+ThingSpace.modules = {}
+ThingSpace.parameters = {}
+ThingSpace.widgets = {}
+
+moduleBegin = function (name, author, copyright, version, timestamp, skin)
+    local result = skangModuleBegin(name, author, copyright, version, timestamp, skin)
+    ThingSpace.modules[name] = {module = _M, name = name, }
+    return result
+end
+
+module = function ()
+end
+load = function ()
+end
+clear = function ()
+end
+window = function (width, height, title)
+end
+quit = function ()
+end
+
+-- skang.newParam stashes the default value into _M['bar'], and the details into ThingSpace.parameters['bar'].
+-- Actually, if it's not required, and there's no default, then skip setting _M['bar'].
+-- Could even use _index to skip setting it if it's not required and there is a default.
+-- Also should add a metatable, and __newindex() that passes all setting of this variable to skang so it can update other stuff like linked widgets.
+-- TODO - Users might want to use two or more copies of this module.  Keep that in mind.  local a = require 'test', b = require 'test' might handle that though?
+--   Not unless skang.newParam() knows about a and b, which it wont.
+--   Both a and b get the same table, not different copies of it.
+--   Perhaps clone the table if it exists?  There is no Lua table cloner, would have to write one.  Only clone the parameters, the rest can be linked back to the original.
+--   Then we have to deal with widgets linking to specific clones.
+--   Actually, not sure matrix-RAD solved that either.  lol
+-- This could even be done with an array of these arguments, not including the _M.
+newParam = function (module, name, required, shortcut, default, help)
+    module[name] = default
+    ThingSpace.parameters[name] = {module = module, name = name, required = required, shortcut = shortcut, default = default, help = help, }
+    print(name .. ' -> ' .. shortcut .. ' -> ' .. help)
+end
+
+-- skang.newCommand stashes the function into _M['func'], and stashes it all (including the function) into ThingSpace.commands['func'].
+-- TODO - Could use _call so that ThingSpace.commands['foo'](arg) works.
+newCommand = function (module, name, types, help, func)
+    module[name] = func
+    ThingSpace.commands[name] = {module = module, name = name, help = help, func = func, }
+    print(name .. '(' .. types ..  ') -> ' .. help)
+end
+
+
+-- TODO - Some function stubs, for now.  Fill them up later.
+module = function (name)
+end
+clear = function ()
+end
+window = function (width, height, title)
+end
+load = function (name)
+end
+get = function (name)
+end
+set = function (name, value)
+end
+quit = function ()
+end
+
+newCommand(_M, 'module',        'name',         '',     module)
+newCommand(_M, 'clear',         '',             '',     clear)
+newCommand(_M, 'window',        'w,h,name',     '',     window)
+newCommand(_M, 'load',          'name',         '',     load)
+newCommand(_M, 'get',           'name',         '',     get)    -- This should be in the modules, not actually here.
+newCommand(_M, 'set',           'name,data',    '',     set)    -- This should be in the modules, not actually here.
+newCommand(_M, 'quit',          '',             '',     quit)
+
+
+-- Restore the environment.
+moduleEnd = function (module)
+    setfenv(2, module.savedEnvironment)
+end
+
+moduleEnd(_M)
+
+end
+
+
+
+
+-- Gotta check out this _ENV thing, 5.2 only.  Seems to replace the need for setfenv().  Seems like setfenv should do what we want, and is more backward compatible.
+--   "_ENV is not supported directly in 5.1, so its use can prevent a module from remaining compatible with 5.1.
+--   Maybe you can simulate _ENV with setfenv and trapping gets/sets to it via __index/__newindex metamethods, or just avoid _ENV."
+--[[ This is a Lua version of what module() does.  Apparently the _LOADED stuff is needed somehow, even though it's a local?  Think that was bogus.
+
+local _LOADED = package.loaded
+function _G.module (modname, ...)
+  local ns = _LOADED[modname]
+  if type(ns) ~= "table" then
+    ns = findtable (_G, modname)
+    if not ns then
+      error (string.format ("name conflict for module '%s'", modname))
+    end
+    _LOADED[modname] = ns
+  end
+  if not ns._NAME then
+    ns._NAME = modname
+    ns._M = ns
+    ns._PACKAGE = gsub (modname, "[^.]*$", "")
+  end
+  setfenv (2, ns)
+  for i, f in ipairs (arg) do
+    f (ns)
+  end
+end
+
+]]