misc/lua/sde/hooks.lua

   1 -- --- T2-COPYRIGHT-NOTE-BEGIN ---
   2 -- This copyright note is auto-generated by ./scripts/Create-CopyPatch.
   3 --
   4 -- T2 SDE: misc/lua/sde/hooks.lua
   5 -- Copyright (C) 2005 - 2006 The T2 SDE Project
   6 -- Copyright (C) 2005 - 2006 Juergen "George" Sawinski
   7 --
   8 -- More information can be found in the files COPYING and README.
   9 --
  10 -- This program is free software; you can redistribute it and/or modify
  11 -- it under the terms of the GNU General Public License as published by
  12 -- the Free Software Foundation; version 2 of the License. A copy of the
  13 -- GNU General Public License can be found in the file COPYING.
  14 -- --- T2-COPYRIGHT-NOTE-END ---
  15
  16 -- TODO:
  17 --  - add "protected" hooks (hooks, that can't be overriden simply)
  18
  19 -- DESCRIPTION:
  20 -- 1. Create a new hook
  21 --    h = hook() or h = hook.new()
  22 --
  23 -- 2. Using hooks
  24 --
  25 -- Access to the hooks with a given hook level (from 1 to 9):
  26 --    h[num]:add(function-or-string)
  27 --      Add a function to the hook with a hook level (num).
  28 --
  29 --    h[num]:set(function-or-string)
  30 --      Replace the contents of hook-order "num" with a new function
  31 --
  32 --    h[num]:clear()
  33 --      Clear all hooks.
  34 --
  35 --    h[num]:run()
  36 --      Run a specific hook level
  37 --
  38 -- Access without hook level:
  39 --    h:add(function-or-string)
  40 --      Equivalent to h[5]:add(function-or-string)
  41 --
  42 --    h:set(function-or-string)
  43 --      Equivalent to h[5]:set(function-or-string), however, clears
  44 --      all other levels
  45 --
  46 --    h:clear()
  47 --      Clear all hooks in all levels.
  48 --
  49 --    h:run()
  50 --      Execute the hooks in all levels, starting at hook level 1.
  51
  52 -- INTERFACE -----------------------------------------------------------------
  53 hook = { level = {} }
  54 meta = {}
  55
  56 function hook.new()
  57    local h = hook
  58    return setmetatable(h, meta)
  59 end
  60
  61 function hook:add(data)
  62    self[5]:add(data)
  63 end
  64
  65 function hook:set(data)
  66    self:clear()
  67    self[5]:set(data)
  68 end
  69
  70 function hook:run()
  71    for _,l in pairs(self.level) do l:run() end
  72 end
  73
  74 function hook:clear()
  75    for _,l in pairs(self.level) do l:clear() end
  76 end
  77
  78 -- h = hook()
  79 setmetatable(hook, { __call = hook.new })
  80
  81 -- INTERNAL HOOKS __hook -----------------------------------------------------
  82 local __hook = {}
  83 local __meta = { __index = {} }
  84
  85 -- create a new __hook
  86 function __hook.new()
  87    local h = { hooks = {} }
  88    return setmetatable(h, __meta)
  89 end
  90
  91 -- __hook.add(hook-table, function-or-string)
  92 -- add a function to the __hook
  93 function __hook.add(h, data)
  94    if type(data) == "table" then
  95       for _,f in pairs(data) do
  96          __hook.add(h, f)
  97       end
  98       return
  99    end
 100
 101    -- insert hook
 102    if type(data) == "function" then
 103       table.insert(h.hooks, data)
 104    elseif type(data) == "string" then
 105       local f = loadstring(data)
 106       table.insert(h.hooks, f)
 107    else
 108       assert(type(data) == "function",
 109              "function or string expected in hook.add(table, pos, function-or-string)")
 110    end
 111 end
 112
 113 -- __hook.set(hook-table, function-or-string-or-nil)
 114 -- add a function to the __hook
 115 function __hook.set(h, data)
 116    h.hooks = {}
 117    __hook.add(h, data)
 118 end
 119
 120 -- __hook.run(hook-table)
 121 -- execute the hooks
 122 function __hook.run(h)
 123    for _,f in pairs(h.hooks) do
 124       if f then f() end
 125    end
 126 end
 127
 128 -- __hook.clear(hook-table)
 129 -- clear all hooks
 130 function __hook.clear(h)
 131    h.hooks = {}
 132 end
 133
 134 -- METATABLE -----------------------------------------------------------------
 135 function __meta.__index:add(data) __hook.add(self, data) end
 136 function __meta.__index:set(data) __hook.set(self, data) end
 137 function __meta.__index:clear()   __hook.clear(self) end
 138 function __meta.__index:run()     __hook.run(self) end
 139
 140 function meta.__index(self, pos, data)
 141    -- clamp position
 142    if pos < 1 then pos = 1 end
 143    if pos > 9 then pos = 9 end
 144
 145    -- create if it does not exist
 146    if not self.level[pos] then
 147       table.insert(self.level, pos, __hook.new())
 148    end
 149
 150    return self.level[pos]
 151 end
 152
 153 function meta.__newindex(self, pos, data)
 154    self[pos]:set(data)
 155 end