{"id":15490029,"url":"https://github.com/sheeep/lua-event-dispatcher","last_synced_at":"2025-03-28T16:26:39.677Z","repository":{"id":77828804,"uuid":"233297686","full_name":"sheeep/lua-event-dispatcher","owner":"sheeep","description":"An Event Dispatcher component for Lua","archived":false,"fork":false,"pushed_at":"2020-01-15T19:40:00.000Z","size":55,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-19T09:03:44.922Z","etag":null,"topics":["event-dispatcher","lua"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sheeep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-11T21:09:08.000Z","updated_at":"2021-07-19T10:49:56.000Z","dependencies_parsed_at":"2023-06-05T01:00:18.124Z","dependency_job_id":null,"html_url":"https://github.com/sheeep/lua-event-dispatcher","commit_stats":{"total_commits":65,"total_committers":1,"mean_commits":65.0,"dds":0.0,"last_synced_commit":"0d6a59dd939559671d0b25f7df994f24a4a91704"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheeep%2Flua-event-dispatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheeep%2Flua-event-dispatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheeep%2Flua-event-dispatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheeep%2Flua-event-dispatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sheeep","download_url":"https://codeload.github.com/sheeep/lua-event-dispatcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246061483,"owners_count":20717444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["event-dispatcher","lua"],"created_at":"2024-10-02T07:09:04.247Z","updated_at":"2025-03-28T16:26:39.655Z","avatar_url":"https://github.com/sheeep.png","language":"Lua","readme":"# Lua Event Dispatcher\n\nThis is an implementation of the Mediator pattern for Lua. It provides\nan event dispatcher and a generic event object, supports priorities,\npropagation stops and error safe executors.\n\n[![Build Status](https://travis-ci.com/sheeep/lua-event-dispatcher.svg?branch=master)](https://travis-ci.com/sheeep/lua-event-dispatcher)\n[![Coverage Status](https://coveralls.io/repos/github/sheeep/lua-event-dispatcher/badge.svg?branch=master\u0026cache-buster=1)](https://coveralls.io/github/sheeep/lua-event-dispatcher?branch=master)\n\n## Installation\n\nInstall `lua-event-dispatcher` through `luarocks`.\n\n```\n$ luarocks install lua-event-dispatcher\n```\n\n## Documentation\n\nUsage examples can be found in the `spec/` folder in form of tests.\n\n* [Basic usage](#basic-usage)\n* [The event object](#event-object)\n* [Priority queues](#priority-queues)\n* [Stop propagation](#stop-propagation)\n* [Executors](#executors)\n* [Remove event listeners](#remove-event-listeners)\n\n### Basic usage\n\nA simple example of how to use this library is the following one.\n\n```lua\nlocal Dispatcher = require \"event-dispatcher.Dispatcher\"\nlocal Event = require \"event-dispatcher.Event\"\n\n-- Create an event dispatcher\nlocal dispatcher = Dispatcher:new()\n\n-- Create an event listener\nlocal listener = function(event)\n  event.data.meep = 2\nend\n\n-- Register this listener to a specific event\ndispatcher:on(\"event-name\", listener)\n\n-- Create an event object with\nlocal event = Event:new({\n  meep = 1\n})\n\ndispatcher:dispatch(\"event-name\", event)\n```\n\n### Event object\n\nThe event object already contains a data table on the key `data` which\ncan be used to store any arbitrary data. The same Event instance is passed\nto all the listeners. This allows for data to be changed along the way.\n\nThe data passed to the constructor of the event object is stored as the\ninitial data for this event.\n\n```lua\nlocal event = Event:new({\n    foo: true\n    bar: false\n})\n\nprint(event.data.foo) -- true\nprint(event.data.bar) -- false\n```\n\nYou don't need to create and pass an event object yourself.\n\n```lua\nlocal dispatcher = Dispatcher:new()\n\ndispatcher:dispatch(\"something-happened\")\n```\n\nStill, your listeners will receive an event object, where they can stop\nthe propagation for example. The data table on such an implicit created\nevent object is empty.\n\n### Priority queues\n\nEvent listeners can be added with a specific priority.\n\n```lua\n\ndispatcher:on(\"event-name\", listener, 32)\ndispatcher:on(\"event-name\", listener, 64)\n\n-- You can add multiple listeners with the same priority\ndispatcher:on(\"event-name\", listener, 128)\ndispatcher:on(\"event-name\", listener, 128)\n```\n\nIf no priority is given, an implicit priority of `0` will be used.\nListeners with lower priorities will be executed *first*.\n\n### Stop propagation\n\nIf for some reason you want to stop the propagation of the event\nin a listener, call the `stopPropagation` method to guarantee\nthat the current listener is the last one to run.\n\n```lua\nlocal listener = function(event)\n  event:stopPropagation()\nend\n```\n\n### Executors\n\nAn executor is responsible for calling your listeners. This library provides two\ndifferent implementations.\n\n* `direct`: Listeners will be called directly. This means that any `error`\nthat is thrown inside of a listener immediately bubbles up and stops the\nexecution of other registered listeners.\n* `protected`: Listeners will be called with `pcall` which means that all of\nthe registered listeners will be called, even if a preceding one errors on the way.\n\nBy default, the `Dispatcher` uses the `direct` executor. You can easily provided\nyour own executor as a callable to a new dispatcher object.\n\n```lua\nlocal Dispatcher = require \"event-dispatcher.Dispatcher\"\n\nlocal directExecutor = require \"event-dispatcher.Executor.direct\"\nlocal protectedExecutor = require \"event-dispatcher.Executor.protected\"\n\nDispatcher:new() -- Implicit use of a direct executor\nDispatcher:new(directExecutor) -- Explicit use of a direct executor\nDispatcher:new(protectedExecutor) -- Use a protected call\n\n-- ... or create an executor yourself\nDispatcher:new(function(listener, event)\n    -- do some other work\n    listener(event)\nend)\n```\n\n### Remove event listeners\n\nTo remove event listeners from a given dispatcher, use one of the following\nmethods.\n\n```lua\ndispatcher:removeListener(\"event\", listener) -- Remove a specific listener from an event\ndispatcher:removeListeners(\"event\") -- Remove all listeners from an event\ndispatcher:removeAllListeners() -- Clear the dispatcher from all registered events\n```\n\n## Testing\n\nThis repository uses the [busted](https://olivinelabs.com/busted) framework to run its unit tests.\nInstall it through `luarocks`.\n\n```\n$ luarocks install busted\n```\n\nAfterwards, you should be able to run `busted` from the project root.\n\n## License\nThis library is licensed under the MIT license.\nSee the complete license text in the `LICENSE` file\n\n🌱\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsheeep%2Flua-event-dispatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsheeep%2Flua-event-dispatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsheeep%2Flua-event-dispatcher/lists"}