lua-eventemitter

lua-events
========================
Current version: v1.0.0 (stable)
Compatible Lua version: 5.1.x

Table of Contents

1. Overiew
2. Installation
3. APIs

1. Overview

lua-events is an EventEmitter class that provides you with APIs in node.js style.

I am using this module with my own nodemcu project on ESP8266 WiFi Soc. It helps me write my code in event-driven style. I often grab a emitter from this module and use the emitter as an event hub in my application to control my program flow. Try it on nodemcu, it won't let you down.

If you like to code something in an asynchronous manner on nodemcu, might I sugguest nodemcu-timer? They are working well with each other to help arrange your asynchronous flow, e.g. your function can defer its callback and return right away.

2. Installation

Clone from github
> $ git clone https://github.com/simenkid/lua-events.git

or use npm install
> $ npm install lua-eventemitter

Just include the file events.lua or use the minified one events_min.lua in your project.
If you are with the nodemcu on ESP8266, it would be good for you to compile .lua text file into .lc bytecode to further reduce memory usage.

* FS/Memory footprint

* events.lua: ~5.1 KB(file size) / ~17 KB (heap available after loaded)
* events_min.lua: ~2.9 KB(size) / ~17 KB (heap)
* events.lc: ~4.0 KB(size) / ~24 KB (heap)
* timer.lc + events.lc: ~17.7 KB (heap)

3. APIs

* EventEmitter:new()
* emitter:emit()
* emitter:on()
* emitter:once()
* emitter:addListener()
* emitter:removeListener()
* emitter:removeAllListeners()
* emitter:getMaxListeners()
* emitter:listenerCount()
* emitter:listeners()
* emitter:setMaxListeners()

*

$3

Exposed by require 'events'

``lua
local EventEmitter = require 'events' -- or 'events_min'
`

$3

Create an instance of event emitter. If a table (or an object) is given, the table will inherit EventEmitter class and itself will be an event emiiter.

Arguments:

1. table (_table_): If given, the table (or an object) itself will be returned as an event emitter. If not given, a new emitter will be returned.

Returns:

* (_object_) emitter

Examples:

`lua
local EventEmitter = require 'events'

-- Inheritance
local myObject = {
name = 'foo',
greet = function ()
print('Hello!')
end
}

myObject = EventEmitter:new(myObject)

myObject:on('knock', function ()
print('knock, knock!')
end)

myObject:emit('knock')

-- A simple emitter
local hub = EventEmitter:new()

hub:on('sing', function (who)
print(who .. ' is singing.')
end)

hub:emit('sing', 'John')

`

**




$3

Calls each of the listeners in order with the given arguments.

Arguments:

1. event (_string_): Event name.
2. ... (_variadic arguments_): The parameters pass along with the event.

Returns:

* (_boolean_) Returns true if listeners exist, false otherwise.

Examples:

`lua
local greet = 'hello'
local name = 'John Doe'
emitter:emit('knock', greet, name)

emitter:emit('tick')
`

**




$3

Adds a listener to the listeners table of the specified event.

Arguments:

1. event (_string_): Event name.
2. listener (_listener_): Event handler.

Returns:

* (_object_) emitter

Examples:

`lua
emitter:on('knock', function () {
print('Someone knocks.')
});
`

**




$3

Attaches a one time listener to the specified event. This listener will be removed after invoked.

Arguments:

1. event (_string_): Event name.
2. listener (_listener_): Event handler.

Returns:

* (_object_) emitter

Examples:

`lua
emitter:once('knock', function () {
print('First visitor comes.')
});
`

**




$3

This is an alias of emitter.on(event, listener).

**

$3

Removes a listener from the listener table of the specified event.

Arguments:

1. event (_string_): Event name.
2. listener (_function_): Event handler

Returns:

* (_object_) emitter

Examples:

`lua
local callback = function (something)
print('Someone says ' .. greet)
end

emitter:on('greeting', callback)
-- ...
emitter:removeListener('greeting', callback)
`

**




$3

Removes all listeners, or those of the specified event.

Arguments:

1. event (_string_): This is optional. If given, all listeners attached to the specified event will be removed. If not given, all listeners of the emiiter will be removed.

Returns:

* (_object_) emitter

Examples:

`lua
emitter:removeAllListeners('foo_event')
`

**




$3

Returns the current max listener value of the emitter.

Arguments:

1. _none_

Returns:

* (_number_) Number of current max listeners.

**

$3

Returns the number of listeners listening to the specified event.

Arguments:

1. event (_string_): Event name.

Returns:

* (_number_) Total number of the listeners.

Examples:

`lua
local numOfListeners = emitter:listenerCount('knock')
`

**




$3

Returns a shallow copy of listener table for the specified event.

Arguments:

1. event (_string_): Event name.

Returns:

* (_table_) table of listeners

Examples:

`lua
local knockHandlers = emitter:listeners('knock')
`

**




$3

The emitter will print a warning if more than 10 listeners are added to a event. This method let you increase the maximum number of listeners attached to a event.

Arguments:

1. n` (_number_): Maximum number of listeners attached to a event.

Returns:

* (_object_) emitter



**

License

MIT