libs/AceConfig-3.0/AceConfigRegistry-3.0/AceConfigRegistry-3.0.lua

   1 --- AceConfigRegistry-3.0 handles central registration of options tables in use by addons and modules.\\
   2 -- Options tables can be registered as raw tables, OR as function refs that return a table.\\
   3 -- Such functions receive three arguments: "uiType", "uiName", "appName". \\
   4 -- * Valid **uiTypes**: "cmd", "dropdown", "dialog". This is verified by the library at call time. \\
   5 -- * The **uiName** field is expected to contain the full name of the calling addon, including version, e.g. "FooBar-1.0". This is verified by the library at call time.\\
   6 -- * The **appName** field is the options table name as given at registration time \\
   7 --
   8 -- :IterateOptionsTables() (and :GetOptionsTable() if only given one argument) return a function reference that the requesting config handling addon must call with valid "uiType", "uiName".
   9 -- @class file
  10 -- @name AceConfigRegistry-3.0
  11 -- @release $Id: AceConfigRegistry-3.0.lua 1161 2017-08-12 14:30:16Z funkydude $
  12 local CallbackHandler = LibStub("CallbackHandler-1.0")
  13
  14 local MAJOR, MINOR = "AceConfigRegistry-3.0", 17
  15 local AceConfigRegistry = LibStub:NewLibrary(MAJOR, MINOR)
  16
  17 if not AceConfigRegistry then return end
  18
  19 AceConfigRegistry.tables = AceConfigRegistry.tables or {}
  20
  21 if not AceConfigRegistry.callbacks then
  22         AceConfigRegistry.callbacks = CallbackHandler:New(AceConfigRegistry)
  23 end
  24
  25 -- Lua APIs
  26 local tinsert, tconcat = table.insert, table.concat
  27 local strfind, strmatch = string.find, string.match
  28 local type, tostring, select, pairs = type, tostring, select, pairs
  29 local error, assert = error, assert
  30
  31 -----------------------------------------------------------------------
  32 -- Validating options table consistency:
  33
  34
  35 AceConfigRegistry.validated = {
  36         -- list of options table names ran through :ValidateOptionsTable automatically.
  37         -- CLEARED ON PURPOSE, since newer versions may have newer validators
  38         cmd = {},
  39         dropdown = {},
  40         dialog = {},
  41 }
  42
  43
  44
  45 local function err(msg, errlvl, ...)
  46         local t = {}
  47         for i=select("#",...),1,-1 do
  48                 tinsert(t, (select(i, ...)))
  49         end
  50         error(MAJOR..":ValidateOptionsTable(): "..tconcat(t,".")..msg, errlvl+2)
  51 end
  52
  53
  54 local isstring={["string"]=true, _="string"}
  55 local isstringfunc={["string"]=true,["function"]=true, _="string or funcref"}
  56 local istable={["table"]=true,   _="table"}
  57 local ismethodtable={["table"]=true,["string"]=true,["function"]=true,   _="methodname, funcref or table"}
  58 local optstring={["nil"]=true,["string"]=true, _="string"}
  59 local optstringfunc={["nil"]=true,["string"]=true,["function"]=true, _="string or funcref"}
  60 local optstringnumberfunc={["nil"]=true,["string"]=true,["number"]=true,["function"]=true, _="string, number or funcref"}
  61 local optnumber={["nil"]=true,["number"]=true, _="number"}
  62 local optmethod={["nil"]=true,["string"]=true,["function"]=true, _="methodname or funcref"}
  63 local optmethodfalse={["nil"]=true,["string"]=true,["function"]=true,["boolean"]={[false]=true},  _="methodname, funcref or false"}
  64 local optmethodnumber={["nil"]=true,["string"]=true,["function"]=true,["number"]=true,  _="methodname, funcref or number"}
  65 local optmethodtable={["nil"]=true,["string"]=true,["function"]=true,["table"]=true,  _="methodname, funcref or table"}
  66 local optmethodbool={["nil"]=true,["string"]=true,["function"]=true,["boolean"]=true,  _="methodname, funcref or boolean"}
  67 local opttable={["nil"]=true,["table"]=true,  _="table"}
  68 local optbool={["nil"]=true,["boolean"]=true,  _="boolean"}
  69 local optboolnumber={["nil"]=true,["boolean"]=true,["number"]=true,  _="boolean or number"}
  70
  71 local basekeys={
  72         type=isstring,
  73         name=isstringfunc,
  74         desc=optstringfunc,
  75         descStyle=optstring,
  76         order=optmethodnumber,
  77         validate=optmethodfalse,
  78         confirm=optmethodbool,
  79         confirmText=optstring,
  80         disabled=optmethodbool,
  81         hidden=optmethodbool,
  82                 guiHidden=optmethodbool,
  83                 dialogHidden=optmethodbool,
  84                 dropdownHidden=optmethodbool,
  85         cmdHidden=optmethodbool,
  86         icon=optstringnumberfunc,
  87         iconCoords=optmethodtable,
  88         handler=opttable,
  89         get=optmethodfalse,
  90         set=optmethodfalse,
  91         func=optmethodfalse,
  92         arg={["*"]=true},
  93         width=optstring,
  94 }
  95
  96 local typedkeys={
  97         header={},
  98         description={
  99                 image=optstringnumberfunc,
 100                 imageCoords=optmethodtable,
 101                 imageHeight=optnumber,
 102                 imageWidth=optnumber,
 103                 fontSize=optstringfunc,
 104         },
 105         group={
 106                 args=istable,
 107                 plugins=opttable,
 108                 inline=optbool,
 109                         cmdInline=optbool,
 110                         guiInline=optbool,
 111                         dropdownInline=optbool,
 112                         dialogInline=optbool,
 113                 childGroups=optstring,
 114         },
 115         execute={
 116                 image=optstringnumberfunc,
 117                 imageCoords=optmethodtable,
 118                 imageHeight=optnumber,
 119                 imageWidth=optnumber,
 120         },
 121         input={
 122                 pattern=optstring,
 123                 usage=optstring,
 124                 control=optstring,
 125                 dialogControl=optstring,
 126                 dropdownControl=optstring,
 127                 multiline=optboolnumber,
 128         },
 129         toggle={
 130                 tristate=optbool,
 131                 image=optstringnumberfunc,
 132                 imageCoords=optmethodtable,
 133         },
 134         tristate={
 135         },
 136         range={
 137                 min=optnumber,
 138                 softMin=optnumber,
 139                 max=optnumber,
 140                 softMax=optnumber,
 141                 step=optnumber,
 142                 bigStep=optnumber,
 143                 isPercent=optbool,
 144         },
 145         select={
 146                 values=ismethodtable,
 147                 style={
 148                         ["nil"]=true,
 149                         ["string"]={dropdown=true,radio=true},
 150                         _="string: 'dropdown' or 'radio'"
 151                 },
 152                 control=optstring,
 153                 dialogControl=optstring,
 154                 dropdownControl=optstring,
 155                 itemControl=optstring,
 156         },
 157         multiselect={
 158                 values=ismethodtable,
 159                 style=optstring,
 160                 tristate=optbool,
 161                 control=optstring,
 162                 dialogControl=optstring,
 163                 dropdownControl=optstring,
 164         },
 165         color={
 166                 hasAlpha=optmethodbool,
 167         },
 168         keybinding={
 169                 -- TODO
 170         },
 171 }
 172
 173 local function validateKey(k,errlvl,...)
 174         errlvl=(errlvl or 0)+1
 175         if type(k)~="string" then
 176                 err("["..tostring(k).."] - key is not a string", errlvl,...)
 177         end
 178         if strfind(k, "[%c\127]") then
 179                 err("["..tostring(k).."] - key name contained control characters", errlvl,...)
 180         end
 181 end
 182
 183 local function validateVal(v, oktypes, errlvl,...)
 184         errlvl=(errlvl or 0)+1
 185         local isok=oktypes[type(v)] or oktypes["*"]
 186
 187         if not isok then
 188                 err(": expected a "..oktypes._..", got '"..tostring(v).."'", errlvl,...)
 189         end
 190         if type(isok)=="table" then             -- isok was a table containing specific values to be tested for!
 191                 if not isok[v] then
 192                         err(": did not expect "..type(v).." value '"..tostring(v).."'", errlvl,...)
 193                 end
 194         end
 195 end
 196
 197 local function validate(options,errlvl,...)
 198         errlvl=(errlvl or 0)+1
 199         -- basic consistency
 200         if type(options)~="table" then
 201                 err(": expected a table, got a "..type(options), errlvl,...)
 202         end
 203         if type(options.type)~="string" then
 204                 err(".type: expected a string, got a "..type(options.type), errlvl,...)
 205         end
 206
 207         -- get type and 'typedkeys' member
 208         local tk = typedkeys[options.type]
 209         if not tk then
 210                 err(".type: unknown type '"..options.type.."'", errlvl,...)
 211         end
 212
 213         -- make sure that all options[] are known parameters
 214         for k,v in pairs(options) do
 215                 if not (tk[k] or basekeys[k]) then
 216                         err(": unknown parameter", errlvl,tostring(k),...)
 217                 end
 218         end
 219
 220         -- verify that required params are there, and that everything is the right type
 221         for k,oktypes in pairs(basekeys) do
 222                 validateVal(options[k], oktypes, errlvl,k,...)
 223         end
 224         for k,oktypes in pairs(tk) do
 225                 validateVal(options[k], oktypes, errlvl,k,...)
 226         end
 227
 228         -- extra logic for groups
 229         if options.type=="group" then
 230                 for k,v in pairs(options.args) do
 231                         validateKey(k,errlvl,"args",...)
 232                         validate(v, errlvl,k,"args",...)
 233                 end
 234                 if options.plugins then
 235                         for plugname,plugin in pairs(options.plugins) do
 236                                 if type(plugin)~="table" then
 237                                         err(": expected a table, got '"..tostring(plugin).."'", errlvl,tostring(plugname),"plugins",...)
 238                                 end
 239                                 for k,v in pairs(plugin) do
 240                                         validateKey(k,errlvl,tostring(plugname),"plugins",...)
 241                                         validate(v, errlvl,k,tostring(plugname),"plugins",...)
 242                                 end
 243                         end
 244                 end
 245         end
 246 end
 247
 248
 249 --- Validates basic structure and integrity of an options table \\
 250 -- Does NOT verify that get/set etc actually exist, since they can be defined at any depth
 251 -- @param options The table to be validated
 252 -- @param name The name of the table to be validated (shown in any error message)
 253 -- @param errlvl (optional number) error level offset, default 0 (=errors point to the function calling :ValidateOptionsTable)
 254 function AceConfigRegistry:ValidateOptionsTable(options,name,errlvl)
 255         errlvl=(errlvl or 0)+1
 256         name = name or "Optionstable"
 257         if not options.name then
 258                 options.name=name       -- bit of a hack, the root level doesn't really need a .name :-/
 259         end
 260         validate(options,errlvl,name)
 261 end
 262
 263 --- Fires a "ConfigTableChange" callback for those listening in on it, allowing config GUIs to refresh.
 264 -- You should call this function if your options table changed from any outside event, like a game event
 265 -- or a timer.
 266 -- @param appName The application name as given to `:RegisterOptionsTable()`
 267 function AceConfigRegistry:NotifyChange(appName)
 268         if not AceConfigRegistry.tables[appName] then return end
 269         AceConfigRegistry.callbacks:Fire("ConfigTableChange", appName)
 270 end
 271
 272 -- -------------------------------------------------------------------
 273 -- Registering and retreiving options tables:
 274
 275
 276 -- validateGetterArgs: helper function for :GetOptionsTable (or, rather, the getter functions returned by it)
 277
 278 local function validateGetterArgs(uiType, uiName, errlvl)
 279         errlvl=(errlvl or 0)+2
 280         if uiType~="cmd" and uiType~="dropdown" and uiType~="dialog" then
 281                 error(MAJOR..": Requesting options table: 'uiType' - invalid configuration UI type, expected 'cmd', 'dropdown' or 'dialog'", errlvl)
 282         end
 283         if not strmatch(uiName, "[A-Za-z]%-[0-9]") then -- Expecting e.g. "MyLib-1.2"
 284                 error(MAJOR..": Requesting options table: 'uiName' - badly formatted or missing version number. Expected e.g. 'MyLib-1.2'", errlvl)
 285         end
 286 end
 287
 288 --- Register an options table with the config registry.
 289 -- @param appName The application name as given to `:RegisterOptionsTable()`
 290 -- @param options The options table, OR a function reference that generates it on demand. \\
 291 -- See the top of the page for info on arguments passed to such functions.
 292 -- @param skipValidation Skip options table validation (primarily useful for extremely huge options, with a noticeable slowdown)
 293 function AceConfigRegistry:RegisterOptionsTable(appName, options, skipValidation)
 294         if type(options)=="table" then
 295                 if options.type~="group" then   -- quick sanity checker
 296                         error(MAJOR..": RegisterOptionsTable(appName, options): 'options' - missing type='group' member in root group", 2)
 297                 end
 298                 AceConfigRegistry.tables[appName] = function(uiType, uiName, errlvl)
 299                         errlvl=(errlvl or 0)+1
 300                         validateGetterArgs(uiType, uiName, errlvl)
 301                         if not AceConfigRegistry.validated[uiType][appName] and not skipValidation then
 302                                 AceConfigRegistry:ValidateOptionsTable(options, appName, errlvl)        -- upgradable
 303                                 AceConfigRegistry.validated[uiType][appName] = true
 304                         end
 305                         return options
 306                 end
 307         elseif type(options)=="function" then
 308                 AceConfigRegistry.tables[appName] = function(uiType, uiName, errlvl)
 309                         errlvl=(errlvl or 0)+1
 310                         validateGetterArgs(uiType, uiName, errlvl)
 311                         local tab = assert(options(uiType, uiName, appName))
 312                         if not AceConfigRegistry.validated[uiType][appName] and not skipValidation then
 313                                 AceConfigRegistry:ValidateOptionsTable(tab, appName, errlvl)    -- upgradable
 314                                 AceConfigRegistry.validated[uiType][appName] = true
 315                         end
 316                         return tab
 317                 end
 318         else
 319                 error(MAJOR..": RegisterOptionsTable(appName, options): 'options' - expected table or function reference", 2)
 320         end
 321 end
 322
 323 --- Returns an iterator of ["appName"]=funcref pairs
 324 function AceConfigRegistry:IterateOptionsTables()
 325         return pairs(AceConfigRegistry.tables)
 326 end
 327
 328
 329
 330
 331 --- Query the registry for a specific options table.
 332 -- If only appName is given, a function is returned which you
 333 -- can call with (uiType,uiName) to get the table.\\
 334 -- If uiType&uiName are given, the table is returned.
 335 -- @param appName The application name as given to `:RegisterOptionsTable()`
 336 -- @param uiType The type of UI to get the table for, one of "cmd", "dropdown", "dialog"
 337 -- @param uiName The name of the library/addon querying for the table, e.g. "MyLib-1.0"
 338 function AceConfigRegistry:GetOptionsTable(appName, uiType, uiName)
 339         local f = AceConfigRegistry.tables[appName]
 340         if not f then
 341                 return nil
 342         end
 343
 344         if uiType then
 345                 return f(uiType,uiName,1)       -- get the table for us
 346         else
 347                 return f        -- return the function
 348         end
 349 end