--[[nef_20221122 SUPPORT_continuity

All support functions are contained in the table game.SP.

Module contains:

user         - returns the human player as userdata Player
colored_link - can be used instead of the featured text link but will add
               a suitable background color.
background   - the table (function) used for colored_link allowing for more
               complex message strings.

get_link_bb - can be used to find a 'hot link' in a string.  Takes one argument - the string.  The function returns the identified object - userdata of type Tile, Unit, or City of the first valid link bbcode in the string and the 'name' if there is one.  Will return nil if this search fails.  If the argument is not a string then the argument is returned unchanged.  This allows the choice of providing a featured text string OR userdata using the form: object = get_link_bb(object).

do_signals - support for signal.* especially useful if the callback function name is not an identifier avoiding conflict with regular global names.  First argument is a table with fields: key = signal (as a string), value = callback function name (as a string).  The second argument determines whether the connects are done or removed.  This argument is also the return value.

The module defines the 'master' table used to contain tables used by utilities that require continuity from one turn to the next.  Also the common code to create those tables.

Module requires the FEATURED_TEXT and PARSER modules.
]]
do          --   SUPPORT_continuity
   local _G = _G
      
   local _ENV = _ENV
   _ENV = _G.log --[[ disable this if you want featured (etc.) to be global,
                    or change it to any other global table.]]
   local featured   = _G.setmetatable({},{  -- FEATURED_TEXT
     __index = function(t,k) local ft = featured
       return _G.assert(ft and ft[k], 'Featured text not loaded.'  ) end;}) 
   local function link (...) link  = featured.link;   return link (...) end
   local function color(...) color = featured.color;  return color(...) end
   
   local bb_iterate = function(...)         -- PARSER
       return _G.assert(bb_iterate,   'Parser not loaded.')(...) end
       
--   SUPPORT_basic
   local function DUP(t) return t,t end
   
   local _ENV = _ENV
   _ENV = _G.game --[[ disable this if you want SP to be global,
                       or change it to any other global table.]]
   _ENV, SP = DUP( SP or _G.setmetatable({},{
     __index = function(t,k) if k == 'user' then
        for player in _G.players_iterate() do 
            if   player.ai_controlled then
            else t[k] = function () return player end return t[k] 
            end
        end                  end
               end;                     }))
   background   =
         _G.setmetatable({Tile = "#ffffff";City = "#400040";Unit = '#404000';},
             {__index = function(t,k) return "#ffffff"  end;
              __call  = function(t,v) return t[_G.tolua.type(v)] end;})
   colored_link = function (object, text)
        return color (link(object, text),nil,background(object))
                  end;  
--   SUPPORT_extended
   get_link_bb  = function (text)
     if _G.type(text) ~= "string" then return text end
     local WE_size  = _G.find.tile (0, 0).y
     local SKEW     = WE_size ~= 0
     local get_link =  _G.setmetatable( {
       tile    = function (options) local x, y = options.x, options.y
                   return _G.find.tile( SKEW and (x-y + WE_size)//2 or x, 
                                     SKEW and  x+y - WE_size or y) end;
       unit    = function (options)
                   return _G.find.unit(nil, options.id), options.name end;
       city    = function (options)
                   return _G.find.city(nil, options.id), options.name end;
                                      },                { 
       __index =  function () return function () end end})
     for current, preamble, bbcode in bb_iterate(text) do
        if   bbcode and bbcode.bb =="l"
        then local options = bbcode.options;
             local target, name = get_link[options.tgt or options.target](options)
             if    target then return target, name end
        end
     end
   end
--   SUPPORT_continuity
   t_name       = '.tables'  -- leave this in SP or make it local ?
   tables       = function (t, MTs)
         _G[t_name]    = _G[t_name] or _G.setmetatable({},{_fc_keep = true}); 
         _G[t_name][t] = MTs and (_G.setmetatable(_G[t_name][t] or {},MTs[t])) 
         return _G[t_name][t]
                  end;
--[=[
--[[ Use this in utilities that need global tables.
          Define MTs fields with key = table_name, value = metatable,
          see examples for how to use meta methods in the metatable. 
          Tables can then be defined with first reference to
          get.<table_name>; use get "<table_name>" to delete table
          entries. The code below is private to each utility so you
          can change the name of get and/or MTs ]]
   local MTs = setmetatable({},
     {__newindex = function(t,k,v) rawset(t,k,v); v._fc_keep = true end})
   local get = setmetatable({}, {
    __index = function(t,k) t[k] = tables(k, MTs) return t[k] end;
    __call  = function(t,k) t[k] = tables(k)      return t[k] end;
                                })
--[[Warning: although the code above looks repetitious it must be included in each utility that uses the 'tables' feature, the reason being that the upvalue MTs will be private to each.]]
--]=]

   do_signals   = function (signals, active)
      local signal = active and _G.signal.replace or _G.signal.remove
      for Signal, callback in _G.pairs(signals) do signal(Signal, callback)
      end; return active
                  end;
--[[To use do_signals define a table containing fields with 
     key = <signal>, value = some string to be used as the the callback function name
     The only requirement for the string is that it be globally unique. 
     Callback functions are then defined in the form:
     _ENV[<table>.<signal>] = function .... end)   ]]
end
--           end SUPPORT_continuity