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