Mercurial > wow > hotcorners

annotate Libs/AceConfig-3.0/AceConfigRegistry-3.0/AceConfigRegistry-3.0.lua @ 11:371e14cd2feb

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