Guide

Subscribing

To subscribe your function to another function use

subtofunc(subto, subscriber, post, priority)

• subto : string, function you'd like to subscribe to
• subscriber : func, the function that is being subscribed
• post : boolean, will execute the subscriber after subto if true, it will execute before otherwise
• priority : int, specifies the priority of the subscription. Higher number = higher priority. subscribed functions with higher priority will be executed first

Working with the event and function parameters

Say function f is subscribed to type When function type is now called subtofunc will call f(event)

• event : Event, contains important information.
  • event.canceled : boolean, specifies wether the event is set to be canceled
  • event.canceloriginal : boolean, specifies wether the initial function should be canceled
  • event.source : string, name of the file the function was called from
  • event.line : int, line the function was called from
  • event.locals : table contains all local fields of the callers scope
  • event.args : table contains the parameters entered into the initial function

Canceling events

To cancel an event you can just set event.canceled = true on the event passed into your subscriber. You will however have to check for yourself wether an event has been canceled, e.g.:

function f()
 print("f")
end
 
subttofunc("type", f, true, 5)

f will still print "f" if type is run, even if event.canceled is true. To prevent your code from running if the event is canceled simply add an if clause:

function f(event)
 if (not event.canceled)
  print("f")
 end
end

To cancel the initial function just set event.canceloriginal = true

source and line

event.source contains the source file the function was called from in format @filename.lua as a string event.line contains the specific line the function was called from as an integer

They are supposed to be used to run code in your subscriber depending on where the function has been called from. This allows for injecting functions at basically any point in the code.

locals

event.locals contains all local fields of the callers scope.

function f(event)
 print(event.locals.sometable.x)
end
 
subttofunc("somefunction", f, false, 5)

local sometable = {x = 9}
somefunction()

f will now print 9 when somefunction is executed. This functionality may also be used to modify objects in event.locals which are stored by reference.

parameters/ args

subtofunc will also pass the subscribed to functions parameters to the subscriber inside of the event.

function f(event)
 print(event.args[1] .. event.args[2] .. event.args[3])
end
 
subttofunc("somefunction", f, false, 5)

somefunction(1, 2, 3, 4)

In this example f will print 123 before somefunction is executed.

If the parameters inside event.args are modified then the original function will be executed using them as well. You could even append new arguments, but they would probably just be discarded.