beholder.lua/README.textile

h1. beholder.lua

A simple event observer for Lua.

h2. Example

<pre>
beholder = require 'beholder'

...

local goblin1 = {x=100, y=100}
goblin1.pauseId = beholder.observe("PAUSE", function() goblin1.paused = true end)

...

local goblin2 = {x=200, y=100}
goblin2.pauseId = beholder.observe("PAUSE", function() goblin2.paused = true end)

...


function pauseButtonPressed()
  beholder.trigger("PAUSE")
end


...

function updateGoblin(goblin)
  if goblin.paused then
    return "zzz"
  else
    return "waaargh!"
  end
end

...

function destroyGoblin(goblin)
  beholder.stopObserving(goblin.pauseId)
end
</pre>

(Note. if you are doing lots of that "if whatever.state then ..." you might want to give a look to "stateful.lua".http.//github.com/kikito/stateful.lua )

h2. Why?

This library tries to solve the following problem. some actions need to be executed when some asynchronous condition is fulfilled. By "asyncronous" we mean that it something that typically doesn't depend on the code. Hence precalculating it beforehand is impractical.

Some examples.

* The pause menu is brought up, and all the actors in your videogame need to be frozen.
* An image has item has been loaded from disk, and a progress bar needs to be updated.
* The user presses certain combination of keys.

The way these problems are typically handed is by continuously polling for the trigger condition. For example, on the pause menu, one would find this code on the enemy movement routines.

<pre>
if pause_menu_is_up then
  -- do the pause-related stuff
else
  -- do the non-pause related stuff.
end
</pre>

You will have a code similar to that on each part that needs to be stopped. on your enemy code, the bullet code, the player code, etc.

But the biggest problem with that code is lack of separation. The code dealign with your goblins should only deal with goblin stuff. It should not "know" about the menu system, or the keyboard actions, or the file loader. And the same goes with your bullet code, player code, etc. They don't need to know about exernal systems, such as the keyboard.

This library allows you to build "walls" between them. your keyboard code will just raise events, and your player code will observe those events. This allows for better encapsulation; if you later add multiplayer functionality, for example, the network module will just have to raise the same events just like the keyboard module did; your player logic will be unaffected.

You can obviously attach any number of observers to any given event. Similarly, you are


h2. Events in beholder

h3. Observing subjects

A very common situation in programming is that you want to attach observations and events to a particular subject: for example, you want a button to observe a mouseclick, but only until that button is garbage-collected.

Having to store the @id@ of the observed button and using it to call @beholder.stopObserving(id)@ when the button is destroyed is tiresome and clunky:

<pre>
  local button = buildAButton(callback)
  local id = beholder.observe('mouseclick', function(x,y)
    if isInside(button, x, y) then
      callback()
    end
  end)

  ...

  beholder.stopObserving(id)
  button = nil
</pre>

It would be much better if beholder provided a way to "observe events while an object exists", and cancelling those observations automatically when the object stops existing.

This is possible through the @beholder.observeSubject@ method:

<pre>
  local button = buildAButton(callback)
  beholder.observeSubject(button, 'mouseclick', function(x,y)
    if isInside(button, x, y) then
      callback()
    end
  end)

  ...

  button = nil
</pre>

Notice that beholder relies on weak tables and the garbage collector in order to clean up unused references.

If you need to make sure that unused references are collected before triggering an event, invoke the garbage collector manualy:

<pre>
  collectgarbage('collect') -- this makes beholder "forget" any remove buttons
  beholder.trigger('mouseclick', 100, 200)
</pre>


h3. Halting event observation

Every call to @beholder.observe@ returns an identifier which can be stored.

<pre>local id = beholder.observe("FOO", bar, baz)</pre>

That identifier can be used to cancel the observation at any moment. You can do so by using the @beholder.stopObserving@ method.

<pre>beholder.stopObserving(id)</pre>

Another option is using @beholder.observeSubject@ and relying on the Garbage Collector as suggested above.

h3. Composed events

Events can be any type of Lua object. On the example, we used the "PAUSE" string. It could also be a number, a function or a table. The == operator is used in all cases.

Composed events are built from more than one lua object. You can do them by simply adding more parameters to the observe/trigger functions. For example, this trigger.

<pre>beholder.trigger('PLAYERDETECTION', player1, 100, 200)</pre>

Will trigger this action.

<pre>beholder.observe('PLAYERDETECTION', player1, 100, 200, function() print("player1 detected at 100, 200") end)</pre>

Composed events are inclusive. This means that this other observer will also get activated by the aforementioned trigger.

<pre>beholder.observe('PLAYERDETECTION', player1, function(x,y) print("player1 detected at ",x,y)</pre>

Notice that the two "non-observed integers" will be passed to the callback as additional parameters. That second action will be executed any time player1 is detected, no matter what coordinates.

Similarly, you can add an action that will be triggered for any player detection.

<pre>beholder.observe('PLAYERDETECTION', function(player,x,y) print(player.no," detected at ",x,y)</pre>

h3. The nil event

If you want to detect all signals raised (i.e. for logging and debugging) you can do so by observing the "empty" event - simply pass a function to observe, without adding any more params.

<pre>beholder.observe(function(...) log("Event triggered", ...) end)</pre>

A quick and dirty way of dumping all events in the standard output is just observing the nil event with @print@.

<pre>beholder.observe(print)</pre>

If you want to trigger the events attached only to the nil event, you can do so by calling trigger without params.

<pre>beholder.trigger()</pre>

h3. Triggering all callbacks

You can use the @triggerAll@ method to trigger all observed events (this will be useful mostly for debugging).

<pre>beholder.triggerAll(...)</pre>

Note that you can pass parameters to @triggerAll@. These will be passed to all callbacks (make sure that they are prepared for this, or you will get errors).



h2. Installation

Just copy the beholder.lua file wherever you want it (for example on a lib/ folder). Then write this in any Lua file where you want to use it.

<pre>local beholder = require 'beholder'</pre>

On this example I've assigned it to a local variable. If you are going to use beholder across multiple files, it's better to require the file just once and make the variable global.

The @package.path@ variable must be configured so that the folder in which beholder.lua is copied is available, of course.

Please make sure that you read the license, too (for your convenience it's now included at the beginning of the beholder.lua file).

h2. Specs

This project uses "telescope".https.//github.com/norman/telescope for its specs. If you want to run the specs, you will have to install telescope first. Then just execute the following from the root inspect folder.

<pre>
tsc -f spec/*.lua
</pre>