Emittance is a flexible eventing library that provides a clean interface for both emitting and capturing events. It follows the following workflow:
- Objects (and therefore, classes) can emit events, identified by a symbol.
- Events are objects that know who emitted them, what time the event was emitted, and any additional information.
- Objects (and therefore, classes) can watch for events that get emitted.
Per this pattern, objects are responsible for knowing what events they want to listen to. While this is pragmatically the same as a "push"-style message system (watchers don't need to go check a topic themselves), the semantics are a little different.
I created this library because I was dissatisfied with the options currently available, and I wanted to see if I could make something that I would enjoy using.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install emittance
If you want a class and its instances to be able to emit events, have it extend
class Foo extend :: end
Emitters can emit events like so:
my_foo = Foo.new my_foo.emit :something_happened Foo.emit :something_else_happened # Classes who extended Emitter can also emit events!
As you can see, event types are identified by a symbol. More on that later. You can also pass in an optional payload, which can be any object:
my_foo.emit :something_happened, payload: "Here's a payload!"
The above examples are cool, but it's generally a better idea to have an object emit its own events:
class Foo extend :: def make_something_happen emit :something_happened, payload: "Here's a payload!" end end my_foo = Foo.new my_foo.make_something_happen
What happens with these events? Watchers are objects that capture these event emissions. You can set up a watcher by including or extending
class Bar extend :: end
To watch for these events, you can just call the
watch method, which takes the symbol identifier and a block that serves as a callback:
Bar.watch :something_happened do |event| puts 'Something definitely happened!' puts event.identifier.inspect puts event.payload end my_foo.make_something_happen # prints: # Something definitely happened! # :something_happened # Here's a payload!
Note that the block gets passed an "event" object, which has some attributes. See the docs for more details.
You can also make
watch call a method:
class Bar extend :: def self.greet(event) puts 'Hello, something must have happened!' puts event.identifier.inspect puts event.payload end end Bar.watch :something_happened, :greet my_foo.make_something_happen # prints: # Hello, something must have happened! # :something_happened # Here's a payload!
Those are the basics--for more info, check the docs!
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake spec to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/aastronautss/emittance.