# Module bait

the event emitter

### Introduction

Bait is the event emitter for Hilbish. Much like Node.js and its `events` system, many actions in Hilbish emit events. Unlike Node.js, Hilbish events are global. So make sure to pick a unique name!

Usage of the Bait module consists of userstanding event-driven architecture, but it’s pretty simple: If you want to act on a certain event, you can `catch` it. You can act on events via callback functions.

Examples of this are in the Hilbish default config! Consider this part of it:

    1bait.catch('command.exit', function(code)
    2	running = false
    3	doPrompt(code ~= 0)
    4	doNotifyPrompt()
    5end)

What this does is, whenever the `command.exit` event is thrown, this function will set the user prompt.

### Functions

catch(name, cb) | Catches an event. This function can be used to act on events.
catchOnce(name, cb) | Catches an event, but only once. This will remove the hook immediately after it runs for the first time.
hooks(name) -> table | Returns a table of functions that are hooked on an event with the corresponding `name`.
release(name, catcher) | Removes the `catcher` for the event with `name`.
throw(name, …args) | Throws a hook with `name` with the provided `args`.

#### bait.catch(name, cb)

Catches an event. This function can be used to act on events.

##### Parameters

`string` `name`
The name of the hook.

`function` `cb`
The function that will be called when the hook is thrown.

##### Example

    1bait.catch('hilbish.exit', function()
    2	print 'Goodbye Hilbish!'
    3end)

#### bait.catchOnce(name, cb)

Catches an event, but only once. This will remove the hook immediately after it runs for the first time.

##### Parameters

`string` `name`
The name of the event

`function` `cb`
The function that will be called when the event is thrown.

#### bait.hooks(name) -> table

Returns a table of functions that are hooked on an event with the corresponding `name`.

##### Parameters

`string` `name`
The name of the hook

#### bait.release(name, catcher)

Removes the `catcher` for the event with `name`.
For this to work, `catcher` has to be the same function used to catch
an event, like one saved to a variable.

##### Parameters

`string` `name`
Name of the event the hook is on

`function` `catcher`
Hook function to remove

##### Example

    1local hookCallback = function() print 'hi' end
    2
    3bait.catch('event', hookCallback)
    4
    5-- a little while later....
    6bait.release('event', hookCallback)
    7-- and now hookCallback will no longer be ran for the event.

#### bait.throw(name, ...args)

Throws a hook with `name` with the provided `args`.

##### Parameters

`string` `name`
The name of the hook.

`any` `args` (This type is variadic. You can pass an infinite amount of parameters with this type.)
The arguments to pass to the hook.

##### Example

    1bait.throw('greeting', 'world')
    2
    3-- This can then be listened to via
    4bait.catch('gretting', function(greetTo)
    5	print('Hello ' .. greetTo)
    6end)