Hook

Hook.py is a provided piece of SuperBot2. It is where plugins and services get the descriptors that are required for SuperBot2 to properly manage them.

Currently the provided descriptors are:

• bindFunction
  • This should be applied to functions in a service or plugin that want to react to an event
• dedicated
  • This should be applied to functions that should always be running in the background
• requires
  • During plugin loading, if a plugin requires a service, the service will be loaded if necessary, if it cant be loaded, the plugin fails to load.
• prefers
  • This is similar to 'requires' with the exception of if it fails to load, the plugin can still be loaded.

bindFunction

The bindFunction descriptor is used on functions inside a Plugin's self-titled class. The arguments are key-value pairs, where the key is used as the key to the event being tested, and the value is a regular expression to match against the value.

Example usage:

from Hook import bindFunction
class MyPlugin:
  @bindFunction(foo="ba+r"):
     print "Foo matches 'ba+r'

A bindFunction can also contain multiple arguments, ALL key-value pairs need to be matched for that bind to fire. Example usage

from Hook import bindFunction
class MyPlugin:
  @bindFunction(foo="ba+r", baz="a+"):
     print "Foo matches 'ba+r', baz matches 'a+'"

Finally multiple bindFunctions can be stacked in front of a function, if ANY of the bindFunctions match the function will be called. See: Issue 9

Currently regular expressions are the only comparison method See: Issue 6

dedicated

Dedicated functions will run in the background. If they return or yield anything that output will be sent to the connector. If a dedicated function returns, or throws an exception the function will be called again. Example usage

from Hook import dedicated
class MyPlugin:
  count = 0
  @dedicated():
  def Loop(self,response):
    self.count = self.count + 1
    return response.say("#foo",str(self.count))

requires and prefers

requires and prefers are the two service binding descriptors. These descriptors go on the class itself. When a plugin is loaded, before its constructed the requires and prefers descriptors are checked, in both cases if the service is present nothing is done, if not the service is loaded. If a service fails to load its required, the plugins is not loaded. If a service fails to load its preferred, the plugins is loaded and the missing event information will be 'None'.

Example usage

from Hook import requires,prefers
@requires("Service1")
@prefers("Service2")
class MyPlugin:
    ...

Like with bindFunction, these can be stacked, also multiple arguments are added as well. Example usage

from Hook import requires,prefers
@requires("Service1","Service2")
@prefers("Service3")
@prefers("Service4")
class MyPlugin:
    ...