Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/simenkid/lua-events
A Lua EventEmitter class in node.js style.
https://github.com/simenkid/lua-events
Last synced: about 1 month ago
JSON representation
A Lua EventEmitter class in node.js style.
- Host: GitHub
- URL: https://github.com/simenkid/lua-events
- Owner: simenkid
- License: mit
- Created: 2015-12-29T07:13:03.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2016-02-14T05:16:31.000Z (over 8 years ago)
- Last Synced: 2024-10-01T15:33:44.389Z (about 1 month ago)
- Language: Lua
- Homepage:
- Size: 13.7 KB
- Stars: 61
- Watchers: 3
- Forks: 15
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
lua-events
========================
Current version: v1.0.0 (stable)
Compatible Lua version: 5.1.x
## Table of Contents
1. [Overiew](#Overiew)
2. [Installation](#Installation)
3. [APIs](#APIs)
**lua-events** is an EventEmitter class that provides you with APIs in node.js style.
I am using this module with my own [**nodemcu**](https://github.com/nodemcu/nodemcu-firmware) project on [ESP8266](http://www.esp8266.com/) 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**](https://github.com/simenkid/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.
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)
* [EventEmitter:new()](#API_new)
* [emitter:emit()](#API_emit)
* [emitter:on()](#API_on)
* [emitter:once()](#API_once)
* [emitter:addListener()](#API_addListener)
* [emitter:removeListener()](#API_removeListener)
* [emitter:removeAllListeners()](#API_removeAllListeners)
* [emitter:getMaxListeners()](#API_getMaxListeners)
* [emitter:listenerCount()](#API_listenerCount)
* [emitter:listeners()](#API_listeners)
* [emitter:setMaxListeners()](#API_setMaxListeners)
*************************************************
### EventEmitter Class
Exposed by `require 'events'`
```lua
local EventEmitter = require 'events' -- or 'events_min'
```
### EventEmitter:new([table])
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')
```
********************************************
### emitter:emit(event[, ...])
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')
```
********************************************
### emitter:on(event, listener)
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.')
});
```
********************************************
### emitter:once(event, listener)
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.')
});
```
********************************************
### emitter:addListener(event, listener)
This is an alias of [emitter.on(event, listener)](#API_on).
********************************************
### emitter:removeListener(event, listener)
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)
```
********************************************
### emitter:removeAllListeners([event])
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')
```
********************************************
### emitter:getMaxListeners()
Returns the current max listener value of the emitter.
**Arguments:**
1. _none_
**Returns:**
* (_number_) Number of current max listeners.
********************************************
### emitter:listenerCount(event)
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')
```
********************************************
### emitter:listeners(event)
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')
```
********************************************
### emitter:setMaxListeners(n)
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