README.md in emittance-0.0.1 vs README.md in emittance-0.0.2
- old
+ new
@@ -1,11 +1,14 @@
# Emittance
+[](https://travis-ci.org/aastronautss/emittance)
+[](https://codeclimate.com/github/aastronautss/emittance/maintainability)
+
Emittance is a flexible eventing library that provides a clean interface for both emitting and capturing events. It follows the following workflow:
1. Objects (and therefore, classes) can emit events, identified by a symbol.
-2. Events are objects that know who emitted them. Their
+2. Events are objects that know who emitted them, what time the event was emitted, and any additional information.
3. 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.
@@ -26,16 +29,101 @@
$ gem install emittance
## Usage
-Coming soon!
+If you want a class and its instances to be able to emit events, have it extend `Emittance::Emitter`.
+```ruby
+class Foo
+ extend Emittance::Emitter
+end
+```
+
+Emitters can emit events like so:
+
+```ruby
+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:
+
+```ruby
+my_foo.emit :something_happened, "Here's a payload!"
+```
+
+The above examples are cool, but it's generally a better idea to have an object emit its own events:
+
+```ruby
+class Foo
+ extend Emittance::Emitter
+
+ def make_something_happen
+ emit :something_happened, "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 `Emittance::Watcher`:
+
+```ruby
+class Bar
+ extend Emittance::Watcher
+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:
+
+```ruby
+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:
+
+```ruby
+class Bar
+ extend Emittance::Watcher
+
+ 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!
+
## Development
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](https://rubygems.org).
## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/aastronauts/emittance.
+Bug reports and pull requests are welcome on GitHub at https://github.com/aastronautss/emittance.