Mercurial > wow > hotcorners

annotate Libs/AceConfig-3.0/AceConfigRegistry-3.0/AceConfigRegistry-3.0.lua @ 25:ac501d71c890 tip

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