Tercio@23: --- AceConfigRegistry-3.0 handles central registration of options tables in use by addons and modules.\\ Tercio@23: -- Options tables can be registered as raw tables, OR as function refs that return a table.\\ Tercio@23: -- Such functions receive three arguments: "uiType", "uiName", "appName". \\ Tercio@23: -- * Valid **uiTypes**: "cmd", "dropdown", "dialog". This is verified by the library at call time. \\ Tercio@23: -- * 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: -- * The **appName** field is the options table name as given at registration time \\ Tercio@23: -- Tercio@23: -- :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: -- @class file Tercio@23: -- @name AceConfigRegistry-3.0 Tercio@58: -- @release $Id: AceConfigRegistry-3.0.lua 1169 2018-02-27 16:18:28Z nevcairiel $ Tercio@51: local CallbackHandler = LibStub("CallbackHandler-1.0") Tercio@51: Tercio@58: local MAJOR, MINOR = "AceConfigRegistry-3.0", 18 Tercio@23: local AceConfigRegistry = LibStub:NewLibrary(MAJOR, MINOR) Tercio@23: Tercio@23: if not AceConfigRegistry then return end Tercio@23: Tercio@23: AceConfigRegistry.tables = AceConfigRegistry.tables or {} Tercio@23: Tercio@23: if not AceConfigRegistry.callbacks then Tercio@23: AceConfigRegistry.callbacks = CallbackHandler:New(AceConfigRegistry) Tercio@23: end Tercio@23: Tercio@23: -- Lua APIs Tercio@23: local tinsert, tconcat = table.insert, table.concat Tercio@23: local strfind, strmatch = string.find, string.match Tercio@23: local type, tostring, select, pairs = type, tostring, select, pairs Tercio@23: local error, assert = error, assert Tercio@23: Tercio@23: ----------------------------------------------------------------------- Tercio@23: -- Validating options table consistency: Tercio@23: Tercio@23: Tercio@23: AceConfigRegistry.validated = { Tercio@23: -- list of options table names ran through :ValidateOptionsTable automatically. Tercio@23: -- CLEARED ON PURPOSE, since newer versions may have newer validators Tercio@23: cmd = {}, Tercio@23: dropdown = {}, Tercio@23: dialog = {}, Tercio@23: } Tercio@23: Tercio@23: Tercio@23: Tercio@23: local function err(msg, errlvl, ...) Tercio@23: local t = {} Tercio@23: for i=select("#",...),1,-1 do Tercio@23: tinsert(t, (select(i, ...))) Tercio@23: end Tercio@23: error(MAJOR..":ValidateOptionsTable(): "..tconcat(t,".")..msg, errlvl+2) Tercio@23: end Tercio@23: Tercio@23: Tercio@23: local isstring={["string"]=true, _="string"} Tercio@23: local isstringfunc={["string"]=true,["function"]=true, _="string or funcref"} Tercio@23: local istable={["table"]=true, _="table"} Tercio@23: local ismethodtable={["table"]=true,["string"]=true,["function"]=true, _="methodname, funcref or table"} Tercio@23: local optstring={["nil"]=true,["string"]=true, _="string"} Tercio@23: local optstringfunc={["nil"]=true,["string"]=true,["function"]=true, _="string or funcref"} Tercio@51: local optstringnumberfunc={["nil"]=true,["string"]=true,["number"]=true,["function"]=true, _="string, number or funcref"} Tercio@23: local optnumber={["nil"]=true,["number"]=true, _="number"} Tercio@23: local optmethod={["nil"]=true,["string"]=true,["function"]=true, _="methodname or funcref"} Tercio@23: local optmethodfalse={["nil"]=true,["string"]=true,["function"]=true,["boolean"]={[false]=true}, _="methodname, funcref or false"} Tercio@23: local optmethodnumber={["nil"]=true,["string"]=true,["function"]=true,["number"]=true, _="methodname, funcref or number"} Tercio@23: local optmethodtable={["nil"]=true,["string"]=true,["function"]=true,["table"]=true, _="methodname, funcref or table"} Tercio@23: local optmethodbool={["nil"]=true,["string"]=true,["function"]=true,["boolean"]=true, _="methodname, funcref or boolean"} Tercio@23: local opttable={["nil"]=true,["table"]=true, _="table"} Tercio@23: local optbool={["nil"]=true,["boolean"]=true, _="boolean"} Tercio@23: local optboolnumber={["nil"]=true,["boolean"]=true,["number"]=true, _="boolean or number"} Tercio@58: local optstringnumber={["nil"]=true,["string"]=true,["number"]=true, _="string or number"} Tercio@23: Tercio@23: local basekeys={ Tercio@23: type=isstring, Tercio@23: name=isstringfunc, Tercio@23: desc=optstringfunc, Tercio@23: descStyle=optstring, Tercio@23: order=optmethodnumber, Tercio@23: validate=optmethodfalse, Tercio@23: confirm=optmethodbool, Tercio@23: confirmText=optstring, Tercio@23: disabled=optmethodbool, Tercio@23: hidden=optmethodbool, Tercio@23: guiHidden=optmethodbool, Tercio@23: dialogHidden=optmethodbool, Tercio@23: dropdownHidden=optmethodbool, Tercio@23: cmdHidden=optmethodbool, Tercio@51: icon=optstringnumberfunc, Tercio@23: iconCoords=optmethodtable, Tercio@23: handler=opttable, Tercio@23: get=optmethodfalse, Tercio@23: set=optmethodfalse, Tercio@23: func=optmethodfalse, Tercio@23: arg={["*"]=true}, Tercio@58: width=optstringnumber, Tercio@23: } Tercio@23: Tercio@23: local typedkeys={ Tercio@23: header={}, Tercio@23: description={ Tercio@51: image=optstringnumberfunc, Tercio@23: imageCoords=optmethodtable, Tercio@23: imageHeight=optnumber, Tercio@23: imageWidth=optnumber, Tercio@23: fontSize=optstringfunc, Tercio@23: }, Tercio@23: group={ Tercio@23: args=istable, Tercio@23: plugins=opttable, Tercio@23: inline=optbool, Tercio@23: cmdInline=optbool, Tercio@23: guiInline=optbool, Tercio@23: dropdownInline=optbool, Tercio@23: dialogInline=optbool, Tercio@23: childGroups=optstring, Tercio@23: }, Tercio@23: execute={ Tercio@51: image=optstringnumberfunc, Tercio@23: imageCoords=optmethodtable, Tercio@23: imageHeight=optnumber, Tercio@23: imageWidth=optnumber, Tercio@23: }, Tercio@23: input={ Tercio@23: pattern=optstring, Tercio@23: usage=optstring, Tercio@23: control=optstring, Tercio@23: dialogControl=optstring, Tercio@23: dropdownControl=optstring, Tercio@23: multiline=optboolnumber, Tercio@23: }, Tercio@23: toggle={ Tercio@23: tristate=optbool, Tercio@51: image=optstringnumberfunc, Tercio@23: imageCoords=optmethodtable, Tercio@23: }, Tercio@23: tristate={ Tercio@23: }, Tercio@23: range={ Tercio@23: min=optnumber, Tercio@23: softMin=optnumber, Tercio@23: max=optnumber, Tercio@23: softMax=optnumber, Tercio@23: step=optnumber, Tercio@23: bigStep=optnumber, Tercio@23: isPercent=optbool, Tercio@23: }, Tercio@23: select={ Tercio@23: values=ismethodtable, Tercio@23: style={ Tercio@23: ["nil"]=true, Tercio@23: ["string"]={dropdown=true,radio=true}, Tercio@23: _="string: 'dropdown' or 'radio'" Tercio@23: }, Tercio@23: control=optstring, Tercio@23: dialogControl=optstring, Tercio@23: dropdownControl=optstring, Tercio@23: itemControl=optstring, Tercio@23: }, Tercio@23: multiselect={ Tercio@23: values=ismethodtable, Tercio@23: style=optstring, Tercio@23: tristate=optbool, Tercio@23: control=optstring, Tercio@23: dialogControl=optstring, Tercio@23: dropdownControl=optstring, Tercio@23: }, Tercio@23: color={ Tercio@23: hasAlpha=optmethodbool, Tercio@23: }, Tercio@23: keybinding={ Tercio@23: -- TODO Tercio@23: }, Tercio@23: } Tercio@23: Tercio@23: local function validateKey(k,errlvl,...) Tercio@23: errlvl=(errlvl or 0)+1 Tercio@23: if type(k)~="string" then Tercio@23: err("["..tostring(k).."] - key is not a string", errlvl,...) Tercio@23: end Tercio@23: if strfind(k, "[%c\127]") then Tercio@23: err("["..tostring(k).."] - key name contained control characters", errlvl,...) Tercio@23: end Tercio@23: end Tercio@23: Tercio@23: local function validateVal(v, oktypes, errlvl,...) Tercio@23: errlvl=(errlvl or 0)+1 Tercio@23: local isok=oktypes[type(v)] or oktypes["*"] Tercio@23: Tercio@23: if not isok then Tercio@23: err(": expected a "..oktypes._..", got '"..tostring(v).."'", errlvl,...) Tercio@23: end Tercio@23: if type(isok)=="table" then -- isok was a table containing specific values to be tested for! Tercio@23: if not isok[v] then Tercio@23: err(": did not expect "..type(v).." value '"..tostring(v).."'", errlvl,...) Tercio@23: end Tercio@23: end Tercio@23: end Tercio@23: Tercio@23: local function validate(options,errlvl,...) Tercio@23: errlvl=(errlvl or 0)+1 Tercio@23: -- basic consistency Tercio@23: if type(options)~="table" then Tercio@23: err(": expected a table, got a "..type(options), errlvl,...) Tercio@23: end Tercio@23: if type(options.type)~="string" then Tercio@23: err(".type: expected a string, got a "..type(options.type), errlvl,...) Tercio@23: end Tercio@23: Tercio@23: -- get type and 'typedkeys' member Tercio@23: local tk = typedkeys[options.type] Tercio@23: if not tk then Tercio@23: err(".type: unknown type '"..options.type.."'", errlvl,...) Tercio@23: end Tercio@23: Tercio@23: -- make sure that all options[] are known parameters Tercio@23: for k,v in pairs(options) do Tercio@23: if not (tk[k] or basekeys[k]) then Tercio@23: err(": unknown parameter", errlvl,tostring(k),...) Tercio@23: end Tercio@23: end Tercio@23: Tercio@23: -- verify that required params are there, and that everything is the right type Tercio@23: for k,oktypes in pairs(basekeys) do Tercio@23: validateVal(options[k], oktypes, errlvl,k,...) Tercio@23: end Tercio@23: for k,oktypes in pairs(tk) do Tercio@23: validateVal(options[k], oktypes, errlvl,k,...) Tercio@23: end Tercio@23: Tercio@23: -- extra logic for groups Tercio@23: if options.type=="group" then Tercio@23: for k,v in pairs(options.args) do Tercio@23: validateKey(k,errlvl,"args",...) Tercio@23: validate(v, errlvl,k,"args",...) Tercio@23: end Tercio@23: if options.plugins then Tercio@23: for plugname,plugin in pairs(options.plugins) do Tercio@23: if type(plugin)~="table" then Tercio@23: err(": expected a table, got '"..tostring(plugin).."'", errlvl,tostring(plugname),"plugins",...) Tercio@23: end Tercio@23: for k,v in pairs(plugin) do Tercio@23: validateKey(k,errlvl,tostring(plugname),"plugins",...) Tercio@23: validate(v, errlvl,k,tostring(plugname),"plugins",...) Tercio@23: end Tercio@23: end Tercio@23: end Tercio@23: end Tercio@23: end Tercio@23: Tercio@23: Tercio@23: --- Validates basic structure and integrity of an options table \\ Tercio@23: -- Does NOT verify that get/set etc actually exist, since they can be defined at any depth Tercio@23: -- @param options The table to be validated Tercio@23: -- @param name The name of the table to be validated (shown in any error message) Tercio@23: -- @param errlvl (optional number) error level offset, default 0 (=errors point to the function calling :ValidateOptionsTable) Tercio@23: function AceConfigRegistry:ValidateOptionsTable(options,name,errlvl) Tercio@23: errlvl=(errlvl or 0)+1 Tercio@23: name = name or "Optionstable" Tercio@23: if not options.name then Tercio@23: options.name=name -- bit of a hack, the root level doesn't really need a .name :-/ Tercio@23: end Tercio@23: validate(options,errlvl,name) Tercio@23: end Tercio@23: Tercio@23: --- Fires a "ConfigTableChange" callback for those listening in on it, allowing config GUIs to refresh. Tercio@23: -- You should call this function if your options table changed from any outside event, like a game event Tercio@23: -- or a timer. Tercio@23: -- @param appName The application name as given to `:RegisterOptionsTable()` Tercio@23: function AceConfigRegistry:NotifyChange(appName) Tercio@23: if not AceConfigRegistry.tables[appName] then return end Tercio@23: AceConfigRegistry.callbacks:Fire("ConfigTableChange", appName) Tercio@23: end Tercio@23: Tercio@23: -- ------------------------------------------------------------------- Tercio@23: -- Registering and retreiving options tables: Tercio@23: Tercio@23: Tercio@23: -- validateGetterArgs: helper function for :GetOptionsTable (or, rather, the getter functions returned by it) Tercio@23: Tercio@23: local function validateGetterArgs(uiType, uiName, errlvl) Tercio@23: errlvl=(errlvl or 0)+2 Tercio@23: if uiType~="cmd" and uiType~="dropdown" and uiType~="dialog" then Tercio@23: error(MAJOR..": Requesting options table: 'uiType' - invalid configuration UI type, expected 'cmd', 'dropdown' or 'dialog'", errlvl) Tercio@23: end Tercio@23: if not strmatch(uiName, "[A-Za-z]%-[0-9]") then -- Expecting e.g. "MyLib-1.2" Tercio@23: error(MAJOR..": Requesting options table: 'uiName' - badly formatted or missing version number. Expected e.g. 'MyLib-1.2'", errlvl) Tercio@23: end Tercio@23: end Tercio@23: Tercio@23: --- Register an options table with the config registry. Tercio@23: -- @param appName The application name as given to `:RegisterOptionsTable()` Tercio@23: -- @param options The options table, OR a function reference that generates it on demand. \\ Tercio@23: -- See the top of the page for info on arguments passed to such functions. Tercio@23: -- @param skipValidation Skip options table validation (primarily useful for extremely huge options, with a noticeable slowdown) Tercio@23: function AceConfigRegistry:RegisterOptionsTable(appName, options, skipValidation) Tercio@23: if type(options)=="table" then Tercio@23: if options.type~="group" then -- quick sanity checker Tercio@23: error(MAJOR..": RegisterOptionsTable(appName, options): 'options' - missing type='group' member in root group", 2) Tercio@23: end Tercio@23: AceConfigRegistry.tables[appName] = function(uiType, uiName, errlvl) Tercio@23: errlvl=(errlvl or 0)+1 Tercio@23: validateGetterArgs(uiType, uiName, errlvl) Tercio@23: if not AceConfigRegistry.validated[uiType][appName] and not skipValidation then Tercio@23: AceConfigRegistry:ValidateOptionsTable(options, appName, errlvl) -- upgradable Tercio@23: AceConfigRegistry.validated[uiType][appName] = true Tercio@23: end Tercio@23: return options Tercio@23: end Tercio@23: elseif type(options)=="function" then Tercio@23: AceConfigRegistry.tables[appName] = function(uiType, uiName, errlvl) Tercio@23: errlvl=(errlvl or 0)+1 Tercio@23: validateGetterArgs(uiType, uiName, errlvl) Tercio@23: local tab = assert(options(uiType, uiName, appName)) Tercio@23: if not AceConfigRegistry.validated[uiType][appName] and not skipValidation then Tercio@23: AceConfigRegistry:ValidateOptionsTable(tab, appName, errlvl) -- upgradable Tercio@23: AceConfigRegistry.validated[uiType][appName] = true Tercio@23: end Tercio@23: return tab Tercio@23: end Tercio@23: else Tercio@23: error(MAJOR..": RegisterOptionsTable(appName, options): 'options' - expected table or function reference", 2) Tercio@23: end Tercio@23: end Tercio@23: Tercio@23: --- Returns an iterator of ["appName"]=funcref pairs Tercio@23: function AceConfigRegistry:IterateOptionsTables() Tercio@23: return pairs(AceConfigRegistry.tables) Tercio@23: end Tercio@23: Tercio@23: Tercio@23: Tercio@23: Tercio@23: --- Query the registry for a specific options table. Tercio@23: -- If only appName is given, a function is returned which you Tercio@23: -- can call with (uiType,uiName) to get the table.\\ Tercio@23: -- If uiType&uiName are given, the table is returned. Tercio@23: -- @param appName The application name as given to `:RegisterOptionsTable()` Tercio@23: -- @param uiType The type of UI to get the table for, one of "cmd", "dropdown", "dialog" Tercio@23: -- @param uiName The name of the library/addon querying for the table, e.g. "MyLib-1.0" Tercio@23: function AceConfigRegistry:GetOptionsTable(appName, uiType, uiName) Tercio@23: local f = AceConfigRegistry.tables[appName] Tercio@23: if not f then Tercio@23: return nil Tercio@23: end Tercio@23: Tercio@23: if uiType then Tercio@23: return f(uiType,uiName,1) -- get the table for us Tercio@23: else Tercio@23: return f -- return the function Tercio@23: end Tercio@23: end