eventDispatcherAPI

-- vim: set filetype=lua:

local handlers = {}
local defaultHandler = nil

--- adds a handler to be called in case an event with eventName and if the first parameter == filter gets queued (see http://computercraft.info/wiki/Os.pullEvent#Event_types)
-- @param eventName a string that identifies the event
-- @param side the side-filter for this function, can also be the name of a wired-network peripheral, like "monitor_0"
-- @param func the callback function that will be called
function addFilteredHandler(eventName, filter, func)
	assert(type(func) == "function", "addSidedHandler: func is no function")
	if handlers[eventName] == nil then
		handlers[eventName] = {}
	end
	if handlers[eventName][filter] == nil then
		handlers[eventName][filter] = {}
	end
	table.insert(handlers[eventName][filter], func)
end

--- adds an handler to be called in case an event with eventName gets queued
-- @param eventName a string that identifies the event
-- @param func the callback function that will be called
function addHandler(eventName, func)
	assert(type(func) == "function", "addHandler: func is no function")
	addFilteredHandler(eventName, "___all", func)
end

--- sets the default handler, which will be called if
-- * no event handler exists and
-- * the event is not "terminate"
-- to handle "terminate" manually just 
-- @param func the function callback
function setDefaultHandler(func)
	assert(type(func) == "function", "func is no function")
	defaultHandler = func
end

--- just for the sake of completness
-- this is just a wrapper to os.queueEvent()
function queueEvent(eventName, param1, param2, param3)
	os.queueEvent(eventName, param1, param2, param3)
end

--- fires up the event dispatcher
-- procedure:
-- * event gets queued
-- * dispatcher fetches it and checks if there are any handlers interessted in this event and calls them one by one
-- * if no handler is registered, checks if is the "terminate" event, runDispatchLoop will return in this case
-- * if this is not the case and a default handler has been set, this one will be called
-- * otherwise the event will just be ignored
function runDispatchLoop()
	abort = false
	repeat
		params = {os.pullEventRaw()}
		eventName = params[1]
		side = params[2]
		if handlers[eventName] ~= nil then
			if handlers[eventName][side] ~= nil then
				for _, func in pairs(handlers[eventName][side]) do
					abort = func(unpack(params)) or abort
				end
			end
			if handlers[eventName]["___all"] ~= nil then
				for _, func in pairs(handlers[eventName]["___all"]) do
					abort = func(unpack(params)) or abort
				end
			end
		elseif eventName == "terminate" then
			return
		else
			if defaultHandler ~= nil then
				abort = defaultHandler(unpack(params)) or abort
			end
		end
	until abort
end