Mercurial > wow > hansgar_and_franzok_assist

annotate Libs/AceConfig-3.0/AceConfigRegistry-3.0/AceConfigRegistry-3.0.lua @ 58:0682d738499b v8.0.1.058

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