Mercurial > wow > icu

annotate Libs/AceConfig-3.0/AceConfigRegistry-3.0/AceConfigRegistry-3.0.lua @ 0:98c6f55e6619

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