README

Lua-based Event library to allow event emitting with attached callbacks.

Usage:

  require "events"

  -- Create an event.
  Event.create("join")

  -- Observe the event with a callback.
  -- The callback function will receive an event object
  -- which will have two parameters:
  --   .type -- a string, which is the type of this event.
  --   .args -- a table with data relative to this event.
  -- There is an optional 3rd argument to observe(), which 
  -- if true, will create the event if it does not already 
  -- exist.
  function a_callback(event)
    io.write(string.format("I got an event: %s\n", event.type))
    io.write(string.format("With %d arguments.\n", table.getn(event.args)))
  end

  Event.observe("join", a_callback)

  -- Emit the event!
  -- The second argument to emit() should be a table 
  -- of data related to the event. It can be nil, in 
  -- which case the created event object's .args 
  -- property will be set to {}.
  Event.emit("join", {nick = "foobar", host = "..."})

  -- To no longer observe and event, pass in the callback
  -- function once again. Callbacks are matched based on
  -- the function you passed in. Remember, it HAS to be the
  -- same function; passing in anonymous functions won't work, 
  -- unless you save the return value from Event.observe(), 
  -- since it returns the callback function provided.
  Event.unobserve("join", a_callback)

  -- Silence an event if you wanted to prevent callbacks from 
  -- being called.
  Event.silence("join")

  -- any callbacks won't be called now.
  Event.emit("join", {nick = "foobar", host = "..."})

  -- Allow callbacks to happen once more.
  Event.unsilence("join")

  -- You can also silence an event for a single call of a 
  -- function. The next argument after the event to silence
  -- is the name of the function to call after silencing the 
  -- event, and any additional arguments are passed to that
  -- function.
  function func(arg1, arg2)
    ...
  end

  Event.silence("join", func, "foo", "bar")

  -- Finally, you can remove events as well. This will remove
  -- the event and all of it's callbacks by setting the event
  -- to nil, allowing it to be garbage collected.
  Event.remove("join")