local __V_MAJOR, __V_MINOR, __V_PATCH = 1, 0, 1
local __VERSION = string.format("%d.%d.%d", __V_MAJOR, __V_MINOR, __V_PATCH)
 
local PPI_list = {}
 
local myID = GetPluginID()
local myPPI = {}
 
local array_id   = function(id)      return "PPIarray_" .. id   end
local params_id  = function(id)      return "PPIparams_" .. id  end
local method_id  = function(id)      return "PPImethod_" .. id  end
 
local request_id = function(id) return "PPI_" .. id .. "_REQUEST" end
local cleanup_id = function(id) return "PPI_" .. id .. "_CLEANUP" end
 
 
function serialize(params, params_list)
  if not params_list then
    local params_list = {}
    serialize(params, params_list)
   
    local list = {}
    for k,v in ipairs(params_list) do
      list[k] = v
    end
    return list
  end
 
  if params_list[params] then
    return params_list[params]
  end
 
  local index = #params_list + 1
  params_list[params] = index
  params_list[index] = true
 
  local id = array_id(index)
  ArrayCreate(id)
 
  for k,v in pairs(params) do
    local key = nil
    if type(k) == "string" then
      key = "s:" .. k
    elseif type(k) == "number" then
      key = "n:" .. k
    end
   
    if key then
      local value = "z:~"
     
      if type(v) == "string" then
        value = "s:" .. v
      elseif type(v) == "number" then
        value = "n:" .. v
      elseif type(v) == "boolean" then
        value = "b:" .. (v and "1" or "0")
      elseif type(v) == "table" then
        value = "t:" .. serialize(v, params_list)
      end
     
      ArraySet(id, key, value)
    end
  end
 
  params_list[index] = ArrayExport(id, "|")
  ArrayDelete(id)
 
  return index
end
 
function deserialize(data_list, index, state)
  if not index or not state then
    return deserialize(data_list, 1, {})
  end
 
  if state[index] then
    return state[index]
  end
 
  local tbl = {}
  state[index] = tbl
 
  local id = array_id(index)
  ArrayCreate(id)
  ArrayImport(id, data_list[index], "|")
 
  for k,v in pairs(ArrayList(id)) do
    local key_type = k:sub(1,1)
    local key = nil
   
    if key_type == "s" then
      key = k:sub(3)
    elseif key_type == "n" then
      key = tonumber(k:sub(3))
    end
   
    if key then
      local item_type = v:sub(1,1)
      local item = v:sub(3)
     
      if item_type == "s" then
        tbl[key] = item
      elseif item_type == "n" then
        tbl[key] = tonumber(item)
      elseif item_type == "b" then
        tbl[key] = ((item == "1") and true or false)
      elseif item_type == "t" then
        tbl[key] = deserialize(data_list, tonumber(item), state)
      else
        tbl[key] = nil
      end
    end
  end
 
  ArrayDelete(id)
 
  return tbl
end
 
local function request(id, func_name, ...)
  -- Prepare the arguments
  local params = {...}
  for k,v in ipairs(serialize(params)) do
    SetVariable(params_id(id) .. "_" .. k, v)
  end
 
  -- Call the method
  SetVariable(method_id(id), func_name)
  CallPlugin(id, request_id(id), myID)
 
  -- Clean up the arguments
  for i=1,#params do
    DeleteVariable(params_id(id) .. "_" .. i)
  end
  DeleteVariable(method_id(id))
 
  -- Gather the return values
  local returns = {}
  local i = 1
  while GetPluginVariable(id, params_id(myID) .. "_" .. i) do
    returns[i] = GetPluginVariable(id, params_id(myID) .. "_" .. i)
    i = i + 1
  end
  returns = deserialize(returns)
 
  -- Have the other plugin clean up its return values
  CallPlugin(id, cleanup_id(id), myID)
 
  return unpack(returns)
end
 
-- A 'thunk' is a delayed resolver function.
local function new_thunk(id, func_name)
  return function(...)
    return request(id, func_name, ...)
  end
end
 
-- If the requested function hasn't yet had a thunk created,
-- create a new thunk and return it.
local PPI_meta = {
  __index = function(tbl, idx)
    local thunk = new_thunk(PPI_list[tbl].id, idx)
    tbl[idx] = thunk
    return thunk
  end,
}
 
local PPI = {
  __V = __VERSION,
  __V_MAJOR = __V_MAJOR,
  __V_MINOR = __V_MINOR,
  __V_PATCH = __V_PATCH,
 
  -- Used to retreive a PPI for a specified plugin.
  Load = function(plugin_id)
    if not IsPluginInstalled(plugin_id) then
      return false
    end
   
    local tbl = PPI_list[plugin_id]
    if not tbl then
      tbl = setmetatable({}, PPI_meta)
      PPI_list[tbl] = {id = plugin_id}
      PPI_list[plugin_id] = tbl
    end
    return tbl
  end,
 
  -- Used by a plugin to expose methods to other plugins
  -- through its own PPI.
  Expose = function(name, func)
    myPPI[name] = (func and func or _G[name])
  end,
}
 
-- PPI request resolver
_G[request_id(myID)] = function(id)
  -- Get requested method
  local func = myPPI[GetPluginVariable(id, method_id(myID))]
  if not func then
    return
  end
 
  -- Deserialize parameters
  local params = {}
  local i = 1
  while GetPluginVariable(id, params_id(myID) .. "_" .. i) do
    params[i] = GetPluginVariable(id, params_id(myID) .. "_" .. i)
    i = i + 1
  end
  params = deserialize(params)
 
  -- Call method, return values
  local returns = {func(unpack(params))}
  for k,v in ipairs(serialize(returns)) do
    SetVariable(params_id(id) .. "_" .. k, v)
  end
end
 
-- Return value cleaner
_G[cleanup_id(myID)] = function(id)
  local i = 1
  while GetVariable(params_id(id) .. "_" .. i) do
    DeleteVariable(params_id(id) .. "_" .. i)
    i = i + 1
  end
end
 
return PPI

Run-time error
Plugin: ppi_test_client (called from world: SmaugFUSS)
Function/Sub: OnPluginListChanged called by Plugin ppi_test_client
Reason: Executing plugin ppi_test_client sub OnPluginListChanged
[string "Plugin"]:9: Dependency plugin not installed!
stack traceback:
        [C]: in function 'error'
        [string "Plugin"]:9: in function <[string "Plugin"]:3>
Error context in script:
   5 :   my_service = ppi.Load("15783160bde378741f9652d1")
   6 :   if my_service then
   7 :     tprint (my_service)
   8 :   else
   9*:     error("Dependency plugin not installed!")
  10 :   end
  11 :   
  12 : end
  13 : 

This plugin requires you to install: Twisols_Stats_Gather plugin.

This is available from: www.somewebsite.com

Please download and install that, and then try again.

EnablePlugin(GetPluginID (), false)

if my_service then
  my_service.DoSomethingHere (a, b, c)
end -- if plugin available

--[[

PLUGIN-to-PLUGIN-INTERFACE (PPI)

Author:  	Twisol 
Date:  3rd January 2010

Amendments: Nick Gammon
Date: 8th January 2010

Example of use:

SERVICE

-- require PPI module
require "ppi"

-- exposed function
function SomeMethodHere (a, b, c, d)
  -- do something with a, b, c, d
  return 1, 2, 3, 4
end

-- notify PPI of this function
ppi.Expose "SomeMethodHere"

-- Or, for anonymous functions:
ppi.Expose ("DoSomethingElse", function () print "hello" end)

CLIENT

-- require PPI module
require "ppi"

-- resolve dependencies
function OnPluginListChanged ()
  
  -- get PPI entries for all exposed function in this plugin
  my_service = ppi.Load ("15783160bde378741f9652d1")  -- plugin ID of service plugin

  if not my_service then
    Note ("Dependency plugin not installed!")
  end
  
end -- OnPluginListChanged

-- later on in plugin ...

-- call SomeMethodHere in other plugin, passing various data types, getting results

if my_service then
  w, x, y, z = my_service.SomeMethodHere (42, "Nick", true, { a = 63, b = 22 } )
end -- if service installed

NOTES
-----

ppi.Load returns a table with various values in it about the target plugin (see below
for what they are). For example, _name is the plugin name of the target plugin, and
_version is the version number of that plugin.

If ppi.Load returns no value (effectively, nil) then the target plugin was not installed.

Provided a non-nil result was returned, you can then call any exposed function in the 
target plugin. There is currently no mechanism for finding what functions are exposed, for
simplicity's sake. However it would be possible to make a service function that returned all
exposed functions. If service plugins evolve in functionality, checking the target plugin's
version (the _version variable) should suffice for making sure plugins are synchronized.

To avoid clashes in variable names, you cannot expose a function starting with an underscore.

Communication with the target plugin is by global variables set up by the Expose function, along
the lines of:

PPI_function_name_PPI_  (one for each exposed function)

Also:

PPI__returns__PPI_ is used for storing the returned values.

--]]

-- hide all except non-local variables
module (..., package.seeall)

-- for transferring variables
require "serialize"

-- PPI version
local V_MAJOR, V_MINOR, V_PATCH = 1, 1, 0
local VERSION = string.format ("%d.%d.%d", V_MAJOR, V_MINOR, V_PATCH)

-- called plugin uses this variable to store returned values
local RETURNED_VALUE_VARIABLE = "PPI__returns__PPI_"

-- For any function in our PPI table, try to call that in the target plugin
local PPI_meta = {
  __index = function (tbl, idx)
    if (idx:sub (1, 1) ~= "_") then
      return function(...)
          -- Call the method in the target plugin
          local status = CallPlugin (tbl._id, "PPI_" .. idx .. "_PPI_", serialize.save_simple {...})
          
          -- explain a bit if we failed
          if status ~= error_code.eOK then
            ColourNote ("white", "red", "Error calling " .. idx .. 
                        " in plugin " .. tbl._name .. 
                        " using PPI from " .. GetPluginName () ..
                        " (" .. error_desc [status] .. ")")
            check (status)
          end -- if
          
          -- call succeeded, get any returned values
          local returns = {}  -- table of returned values
          local s = GetPluginVariable(tbl._id, RETURNED_VALUE_VARIABLE) or "{}"
          local f = assert (loadstring ("t = " .. s))  -- convert serialized data back
          setfenv (f, returns) () -- load the returned values into 'returns'
          
          -- unpack returned values to caller
          return unpack (returns.t)
        end  -- generated function
      end -- not starting with underscore
    end  -- __index function
}  -- end PPI_meta table

-- PPI request resolver
local function PPI_resolver (func) 
  return function (s)  -- calling plugin serialized parameters into a single string argument
    local params = {}  -- table of parameters
    local f = assert (loadstring ("t = " .. s))  -- convert serialized data back
    setfenv (f, params) ()  -- load the parameters into 'params'
    
    -- call target function, get return values, serialize back into variable
    SetVariable(RETURNED_VALUE_VARIABLE, serialize.save_simple {func(unpack (params.t))})
  end -- generated function
  
end -- PPI_resolver

-- EXPOSED FUNCTIONS

-- We "load" a plugin by checking it exists, and creating a table saving the
-- target plugin ID etc., and have a metatable which will handle function calls
function Load (plugin_id)
  if IsPluginInstalled (plugin_id) then
    return setmetatable (
      { _id = plugin_id,   -- so we know which plugin to call
        _name = GetPluginInfo (plugin_id, 1),
        _author = GetPluginInfo (plugin_id, 2),
        _filename = GetPluginInfo (plugin_id, 6),
        _enabled = GetPluginInfo (plugin_id, 17),
        _version = GetPluginInfo (plugin_id, 18),
        _required_version = GetPluginInfo (plugin_id, 19),
        _directory = GetPluginInfo (plugin_id, 20),
        _PPI_V_MAJOR = V_MAJOR,  -- version info
        _PPI_V_MINOR = V_MINOR,
        _PPI_V_PATCH = V_PATCH,
        _PPI_VERSION = VERSION,
       }, 
       PPI_meta)  -- everything except the above will generate functions
  else
    return nil, "Plugin ID " .. plugin_id .. " not installed"  -- in case you assert
  end -- if 
end -- function Load 

-- Used by a plugin to expose methods to other plugins
-- Each exposed function will be added to global namespace as PPI_<name>_PPI_
function Expose (name, func)
  assert (type (func or _G [name]) == "function", "Function " .. name .. " does not exist.")
  _G ["PPI_" .. name .. "_PPI_"] = PPI_resolver (func or _G [name])
end -- function Expose

static int ll_seeall (lua_State *L) {
  luaL_checktype(L, 1, LUA_TTABLE);
  if (!lua_getmetatable(L, 1)) {
    lua_createtable(L, 0, 1); /* create new metatable */
    lua_pushvalue(L, -1);
    lua_setmetatable(L, 1);
  }
  lua_pushvalue(L, LUA_GLOBALSINDEX);
  lua_setfield(L, -2, "__index");  /* mt.__index = _G */
  return 0;
}

local myfile = [[
  module("test", package.seeall)
  function MYFOO()
    print("Hi.")
  end
]]

loadstring(myfile)()

"MYFOO"=function: 03083340
"_M":
  "MYFOO"=function: 03083340
  "_M"=table: 041A55A8
  "_NAME"="test"
  "_PACKAGE"=""
"_NAME"="test"
"_PACKAGE"=""

...
everything
...
"package":
    "preload":
    "loadlib"=function: 02F7A858
    "loaded":
      all other packages
      ...
      including this package
...

local script = [====[
--[[

<< put your function code here >>

]====]

local found = {}
local libs_used = {}

local funcs = {}
local libraries = {
      "string",
      "package",
      "os",
      "io",
      "bc",
      "progress",
      "bit",
      "rex",
      "utils",
      "table",
      "math",
      "debug",
      "coroutine",
      "lpeg",
      "sqlite3",
      "world",
  } -- end of libraries

local tables = {
      "trigger_flag",
      "alias_flag",
      "timer_flag",
      "custom_colour",
      "error_code",
      "sendto",
   }  -- end of tables

for k, v in pairs (_G) do
  if type (v) == "function" then
    funcs [k] = true
  end -- if 
end -- for

for _, lib in ipairs (libraries) do
  for k, v in pairs (_G [lib]) do
    if type (v) == "function" then
      funcs [lib .. "." .. k] = true
      if lib == "world" then
        funcs [k] = true
      end -- if
    end -- if 
  end -- for

end -- for each library

-- now do stuff like error_code, colours etc.

for _, lib in ipairs (tables) do
  for k, v in pairs (_G [lib]) do
      funcs [lib .. "." .. k] = true
  end -- for
end -- for each table

-- scan our script for matching functions

for w in string.gmatch (script, "[%a%d._]+") do
  if funcs [w] then
    local lib, func = string.match (w, "^([%a%d_]+)%.([%a%d_]+)")
    if lib then
      libs_used [lib] = libs_used [lib] or {}
      libs_used [lib] [func] = true
    else
      found [w] = true
    end -- if
  end -- if  

end -- for

local tl = {}
for k in pairs (libs_used) do
  table.insert (tl, k)
end -- for

table.sort (tl)

for _, lib in ipairs (tl) do
  print ("local", lib, "= {")
  for k in pairs (libs_used [lib]) do
    print ("  ", k, "=", lib .. "." .. k .. ",")
  end -- for
  print ("  }")
end -- for

local t = {}
for k in pairs (found) do
  table.insert (t, k)
end -- for

table.insert (t, "_G")

table.sort (t)

print ("local", table.concat (t, ", "), "=", table.concat (t, ", "))

-- hide all except non-local variables
module (...)