There are several changes and improvements to the event module. I think it's a good idea for all of us to do everything through PRs so we can review each other's code and make sure it meets quality standards, among other things.
I thoroughly tested the module using a test script that I built in my Sandbox mod. It passes heavy mode checks and doesn't desync in multiplayer. Everything behaves properly so far as I can tell.
Here are the major changes versus the version on master:
Handler raising behavioral change
The previous version of the event module would fire the handler once, then skip to the next handler. Now, if several conditional events meet the requirements for execution, it will do all of them. This means that a handler registered to two conditional events will fire twice, give that the right conditions are met.
This will allow my GUI module to work by reading GUI filters for every event, instead of getting stuck after the first one.
Conditional name passed in the event table
A conditional handler's event name will be passed in the event table when it is dispatched. This (again) is for my GUI module to be able to match the correct filters, but can be used elsewhere as well. For example, the same handler could be registered to two conditional events, and can take slightly different actions depending on which one was raised.
Removed __version and event module migrations
The event module would store a __version key inside of global.__flib to use during migrations. I realized that this is no longer needed, as that is a relic from when my lualib was something I copied in between mods. One can simply use the version changes given on on_configuration_changed for migrations.
The other change is to remove the code that would have done migrations on event data. This is unused at the moment, and can be re-added back in if migrations ever need to be done (which hopefully they won't).
General code improvements
I refactored the dispatch_event and event.raise functions to have better quality and faster execution time. For example, dispatch_event no longer uses a goto to break execution order. I also cleaned up some redundant if statements.
Documentation
Most of the functions in the module are now documented, with usage examples for each. There are two places where the documentation needs work:
Shortcut functions
All but one of the shortcut functions are generated dynamically, and I have no idea how to document that in LDoc:
---@section Shortcut functions
-- TODO: how to document!?
function event.on_nth_tick(nth_tick, handler, options)
return event.register(-nth_tick, handler, options)
end
for n,_ in pairs(bootstrap_events) do
event[n] = function(handler)
event.register(n, handler)
end
end
for n,id in pairs(defines.events) do
event[n] = function(handler, options)
event.register(id, handler, options)
end
end
Concepts
There are several "concepts" that the event module uses, and I am unsure on the formatting for documenting them. For now I copy/pasted the explanations verbatim from my RaiLuaLib documentation, but it exceeds the line count and is formatted in Markdown. I am unsure of how to proceed here. These are located at the bottom of the file.
There are several changes and improvements to the event module. I think it's a good idea for all of us to do everything through PRs so we can review each other's code and make sure it meets quality standards, among other things.
I thoroughly tested the module using a test script that I built in my Sandbox mod. It passes heavy mode checks and doesn't desync in multiplayer. Everything behaves properly so far as I can tell.
Here are the major changes versus the version on master:
Handler raising behavioral change
The previous version of the event module would fire the handler once, then skip to the next handler. Now, if several conditional events meet the requirements for execution, it will do all of them. This means that a handler registered to two conditional events will fire twice, give that the right conditions are met.
This will allow my GUI module to work by reading GUI filters for every event, instead of getting stuck after the first one.
Conditional name passed in the event table
A conditional handler's event name will be passed in the event table when it is dispatched. This (again) is for my GUI module to be able to match the correct filters, but can be used elsewhere as well. For example, the same handler could be registered to two conditional events, and can take slightly different actions depending on which one was raised.
Removed __version and event module migrations
The event module would store a
__version
key inside ofglobal.__flib
to use during migrations. I realized that this is no longer needed, as that is a relic from when my lualib was something I copied in between mods. One can simply use the version changes given onon_configuration_changed
for migrations.The other change is to remove the code that would have done migrations on event data. This is unused at the moment, and can be re-added back in if migrations ever need to be done (which hopefully they won't).
General code improvements
I refactored the
dispatch_event
andevent.raise
functions to have better quality and faster execution time. For example,dispatch_event
no longer uses agoto
to break execution order. I also cleaned up some redundantif
statements.Documentation
Most of the functions in the module are now documented, with usage examples for each. There are two places where the documentation needs work:
Shortcut functions
All but one of the shortcut functions are generated dynamically, and I have no idea how to document that in LDoc:
Concepts
There are several "concepts" that the event module uses, and I am unsure on the formatting for documenting them. For now I copy/pasted the explanations verbatim from my RaiLuaLib documentation, but it exceeds the line count and is formatted in Markdown. I am unsure of how to proceed here. These are located at the bottom of the file.