siftery-wisper 2.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4f6bf677ec7224bac38caa11cb49620dedb6a0e2d28095b940bc0f6e1563d54b
+  data.tar.gz: 7007c32fce8fdc5ceebb740c965210dab06cd4ba12ff6e639d671e705252d296
+SHA512:
+  metadata.gz: 0b39cec008bc8bae5b15e560a225b99afda15db75ebffdb81602642ca6734636fe8d903958ed2dd0a187926643a55c06a0ed7f2daa76180b0b4889d35fdf2401
+  data.tar.gz: 03dd49ce611320e862a6af823e8a58eaad516d8d336eae5aafedd60db7d2f96555e801c0db05f241d3dbb92125e3172b7000dc64fcee532414e34f8736949f04

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.ruby-version
+.ruby-gemspec
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+tags
+vendor

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format progress
+--require spec_helper
+--warnings

data/.travis.yml

@@ -0,0 +1,22 @@
+language: ruby
+before_install:
+  - gem update --system
+  - gem update bundler
+bundler_args: --without=extras
+script: rspec spec
+sudo: false
+rvm:
+  - '2.1.10'
+  - '2.2.6'
+  - '2.3.3'
+  - '2.4.0'
+  - jruby-9.1.6.0
+  # - rbx-2
+  ### ALLOWED FAILURES ###
+  # see how compatible we are with dev versions, but do not fail the build
+  - ruby-head
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/CHANGELOG.md

@@ -0,0 +1,129 @@
+## HEAD (unreleased)
+
+## 2.0.0 (7th Mar 2017)
+
+Authors: Sergey Mostovoy, Andrew Kozin, Kyle Tolle, Martin, Rob Miller, Mike
+Dalto, orthographic-pedant, Drew Ulmer, Mikey Hogarth, Attila Domokos, Josh
+Miltz, Pascal Betz, Vasily Kolesnikov, Julien Letessier, Kris Leech
+
+* Fix: logger raises exception if hash is passed as an argument to a listener #133, #136
+* Fix: deprecation warnings #120
+* Doc improvements: #106, #111, #116, #122, #128, #130, #147, #149, #150, #151
+* Adds: Allow configuration of default prefix when using `prefix: true`. #105
+* Adds: Allow unsubscribing of global listeners #118
+* Adds: Helpful error message when passing a block to `#subscribe` of `#on` #125
+* Adds: raise an error message when `#on` is not passed a block #146
+* Adds: Support for JRuby 9.x #148
+* Adds: Support for MRI 2.4.0 #155
+* Refactor specs #126, #131
+
+## 2.0.0.rc1 (17 Dec 2014)
+
+Authors: Kris Leech
+
+* remove: deprecated methods
+* remove: rspec matcher and stubbing (moved to [wisper-rspec](https://github.com/krisleech/wisper-rspec))
+* feature: add regexp support to `on` argument
+* remove: announce alias for broadcasting
+* docs: add Code of Conduct
+* drop support for Ruby 1.9
+
+## 1.6.0 (25 Oct 2014)
+
+Authors: Kris Leech
+
+* deprecate: add_listener, add_block_listener and respond_to
+* internal: make method naming more consistent
+
+## 1.5.0 (6th Oct 2014)
+
+Authors: Kris Leech
+
+* feature: allow events to be published asynchronously
+* feature: broadcasting of events is plugable and configurable
+* feature: broadcasters can be aliased via a symbol
+* feature: logging broadcaster
+
+## 1.4.0 (8th Sept 2014)
+
+Authors: Kris Leech, Marc Ignacio, Ahmed Abdel Razzak, kmehkeri, Jake Hoffner
+
+* feature: matcher for rspec 3
+* fix: temporary global listeners are cleared if an exception is raised
+* refactor: update all specs to rspec 3 expect syntax
+* docs: update README to rspec 3 expect syntax
+* feature: combine global and temporary listener methods as `Wisper.subscribe`
+* deprecate: `Wisper.add_listener` and `Wisper.with_listeners,` use `Wisper.subscribe` instead
+
+## 1.3.0 (18th Jan 2014)
+
+Authors: Kris Leech, Yan Pritzker, Charlie Tran
+
+* feature: global subscriptions can be scoped to a class (and sub-classes)
+* upgrade: use rspec 3
+* feature: allow prefixing of events with 'on'
+* feature: Allow stubbed publisher method to accept arbitrary args
+
+## 1.2.1 (7th Oct 2013)
+
+Authors: Kris Leech, Tomasz Szymczyszyn, Alex Heeton
+
+* feature: global subscriptions can be passed options
+* docs: improve README examples
+* docs: add license to gemspec
+
+## 1.2.0 (21st July 2013)
+
+Authors: Kris Leech, Darren Coxall
+
+* feature: support for multiple events at once
+* fix: clear global listeners after each spec
+
+## 1.1.0 (7th June 2013)
+
+Authors: Kris Leech, chatgris
+
+* feature: add temporary global listeners
+* docs: improve ActiveRecord example
+* refactor: improve specs
+* upgrade: add Ruby 2.0 support
+* fix: make listener collection immutable
+* remove: async publishing and Celluloid dependency
+* fix: Make global listeners getter and setter threadsafe [9]
+
+## 1.0.1 (2nd May 2013)
+
+Authors: Kris Leech, Yan Pritzker
+
+* feature: add async publishing using Celluloid
+* docs: improve README examples
+* feature: `stub_wisper_publisher` rspec helper
+* feature: global listeners
+* refactor: improve specs
+
+## 1.0.0 (7th April 2013)
+
+Authors: Kris Leech
+
+* refactor: specs
+* refactor: registrations
+* feature: Add `with` argument to `subscribe`
+* docs: improve README examples
+* feature: Allow subscriptions to be chainable
+* feature: Add `on` syntax for block subscription
+* remove: Remove support for Ruby 1.8.7
+* docs: Add badges to README
+
+## 0.0.2 (30th March 2013)
+
+Authors: Kris Leech
+
+* remove: ActiveSupport dependency
+* docs: fix syntax highlighting in README
+
+## 0.0.1 (30th March 2013)
+
+Authors: Kris Leech
+
+* docs: add README
+* feature: registration of objects and blocks

data/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# How to Contribute
+
+We very much welcome contributions to Wisper.
+
+This project is intended to be a safe, welcoming space for collaboration,
+and contributors are expected to adhere to the
+[Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## Getting started
+
+Please first check the existing [Issues](https://github.com/krisleech/wisper/issues) 
+and [Pull Requests](https://github.com/krisleech/wisper/pulls) to ensure your
+issue has not already been discused.
+
+## Bugs
+
+Please submit a bug report to the issue tracker, with the version of Wisper
+and Ruby you are using and a small code sample (or better yet a failing test).
+
+## Features
+
+Please open an issue with your proposed feature. We can discuss the feature and
+if it is acceptable we can also discuss implimentation details. You will in
+most cases have to submit a PR which adds the feature. 
+
+Wisper is a micro library and will remain lean. Some features would be most
+appropriate as an extension to Wisper.
+
+We also have a [Gitter channel](https://gitter.im/krisleech/wisper) if you wish to discuss your ideas.
+
+## Backlog /  Roadmap
+
+The backlog for Wisper and related gems is on [Waffle](https://waffle.io/krisleech/wisper).
+
+## Questions
+
+Try the [Wiki](https://github.com/krisleech/wisper/wiki) first, the examples
+and how to sections have lots of information.
+
+Please ask questions on StackOverflow, [tagged wisper](https://stackoverflow.com/questions/tagged/wisper).
+
+Feel free to ping me the URL on [Twitter](https://twitter.com/krisleech).
+
+## Pull requests
+
+* Fork the project, create a new branch from `v1` or `master`.
+* Squash commits which are related.
+* Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+* Documentation only changes should have `[skip ci]` in the commit message
+* Follow existing code style in terms of syntax, indentation etc.
+* Add an entry to the CHANGELOG
+* Do not bump the VERSION, but do indicate in the CHANGELOG if the change is
+not backwards compatible.
+* Issue a Pull Request
+
+## Versions
+
+The `v1` branch is a long lived branch and you should
+branch from this if you wish to fix an issue in version `~> 1.0`.
+
+The `master` branch will target the next version of Wisper.

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'
+gem 'rspec'
+gem 'coveralls', require: false
+
+group :extras do
+  gem 'flay'
+  gem 'pry'
+  gem 'yard'
+end

data/README.md

@@ -0,0 +1,373 @@
+# Wisper
+
+*A micro library providing Ruby objects with Publish-Subscribe capabilities*
+
+[![Gem Version](https://badge.fury.io/rb/wisper.svg)](http://badge.fury.io/rb/wisper)
+[![Code Climate](https://codeclimate.com/github/krisleech/wisper.svg)](https://codeclimate.com/github/krisleech/wisper)
+[![Build Status](https://travis-ci.org/krisleech/wisper.svg?branch=master)](https://travis-ci.org/krisleech/wisper)
+[![Coverage Status](https://coveralls.io/repos/krisleech/wisper/badge.svg?branch=master)](https://coveralls.io/r/krisleech/wisper?branch=master)
+
+* Decouple core business logic from external concerns in Hexagonal style architectures
+* Use as an alternative to ActiveRecord callbacks and Observers in Rails apps
+* Connect objects based on context without permanence
+* React to events synchronously or asynchronously
+
+Note: Wisper was originally extracted from a Rails codebase but is not dependant on Rails.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'wisper', '2.0.0'
+```
+
+## Usage
+
+Any class with the `Wisper::Publisher` module included can broadcast events
+to subscribed listeners. Listeners subscribe, at runtime, to the publisher.
+
+### Publishing
+
+```ruby
+class CancelOrder
+  include Wisper::Publisher
+
+  def call(order_id)
+    order = Order.find_by_id(order_id)
+
+    # business logic...
+
+    if order.cancelled?
+      broadcast(:cancel_order_successful, order.id)
+    else
+      broadcast(:cancel_order_failed, order.id)
+    end
+  end
+end
+```
+
+When a publisher broadcasts an event it can include any number of arguments.
+
+The `broadcast` method is also aliased as `publish`.
+
+You can also include `Wisper.publisher` instead of `Wisper::Publisher`.
+
+### Subscribing
+
+#### Objects
+
+Any object can be subscribed as a listener.
+
+```ruby
+cancel_order = CancelOrder.new
+
+cancel_order.subscribe(OrderNotifier.new)
+
+cancel_order.call(order_id)
+```
+
+The listener would need to implement a method for every event it wishes to receive.
+
+```ruby
+class OrderNotifier
+  def cancel_order_successful(order_id)
+    order = Order.find_by_id(order_id)
+
+    # notify someone ...
+  end
+end
+```
+
+#### Blocks
+
+Blocks can be subscribed to single events and can be chained.
+
+```ruby
+cancel_order = CancelOrder.new
+
+cancel_order.on(:cancel_order_successful) { |order_id| ... }
+            .on(:cancel_order_failed)     { |order_id| ... }
+
+cancel_order.call(order_id)
+```
+
+You can also subscribe to multiple events using `on` by passing
+additional events as arguments.
+
+```ruby
+cancel_order = CancelOrder.new
+
+cancel_order.on(:cancel_order_successful) { |order_id| ... }
+            .on(:cancel_order_failed,
+                :cancel_order_invalid)    { |order_id| ... }
+
+cancel_order.call(order_id)
+```
+
+Do not `return` from inside a subscribed block, due to the way
+[Ruby treats blocks](http://product.reverb.com/2015/02/28/the-strange-case-of-wisper-and-ruby-blocks-behaving-like-procs/)
+this will prevent any subsequent listeners having their events delivered.
+
+### Handling Events Asynchronously
+
+```ruby
+cancel_order.subscribe(OrderNotifier.new, async: true)
+```
+
+You can also pass additional configuration options to the job using the following syntax:
+
+```ruby
+cancel_order.subscribe(OrderNotifier.new, async: { queue: 'custom', retry: false })
+```
+
+The list of supported handler options is determined by adapter
+
+Wisper has various adapters for asynchronous event handling, please refer to
+[wisper-celluloid](https://github.com/krisleech/wisper-celluloid),
+[wisper-sidekiq](https://github.com/krisleech/wisper-sidekiq),
+[wisper-activejob](https://github.com/krisleech/wisper-activejob), or
+[wisper-que](https://github.com/joevandyk/wisper-que).
+
+Depending on the adapter used the listener may need to be a class instead of an object. In this situation, every method corresponding to events should be declared as a class method, too. For example:
+
+```ruby
+class OrderNotifier
+  # declare a class method if you are subscribing the listener class instead of its instance like:
+  #   cancel_order.subscribe(OrderNotifier)
+  #
+  def self.cancel_order_successful(order_id)
+    order = Order.find_by_id(order_id)
+
+    # notify someone ...
+  end
+end
+```
+
+### ActionController
+
+```ruby
+class CancelOrderController < ApplicationController
+
+  def create
+    cancel_order = CancelOrder.new
+
+    cancel_order.subscribe(OrderMailer,        async: true)
+    cancel_order.subscribe(ActivityRecorder,   async: true)
+    cancel_order.subscribe(StatisticsRecorder, async: true)
+
+    cancel_order.on(:cancel_order_successful) { |order_id| redirect_to order_path(order_id) }
+    cancel_order.on(:cancel_order_failed)     { |order_id| render action: :new }
+
+    cancel_order.call(order_id)
+  end
+end
+```
+
+### ActiveRecord
+
+If you wish to publish directly from ActiveRecord models you can broadcast events from callbacks:
+
+```ruby
+class Order < ActiveRecord::Base
+  include Wisper::Publisher
+
+  after_commit     :publish_creation_successful, on: :create
+  after_validation :publish_creation_failed,     on: :create
+
+  private
+
+  def publish_creation_successful
+    broadcast(:order_creation_successful, self)
+  end
+
+  def publish_creation_failed
+    broadcast(:order_creation_failed, self) if errors.any?
+  end
+end
+```
+
+There are more examples in the [Wiki](https://github.com/krisleech/wisper/wiki).
+
+## Global Listeners
+
+Global listeners receive all broadcast events which they can respond to.
+
+This is useful for cross cutting concerns such as recording statistics, indexing, caching and logging.
+
+```ruby
+Wisper.subscribe(MyListener.new)
+```
+
+In a Rails app you might want to add your global listeners in an initalizer.
+
+Global listeners are threadsafe.
+
+### Scoping by publisher class
+
+You might want to globally subscribe a listener to publishers with a certain
+class.
+
+```ruby
+Wisper.subscribe(MyListener.new, scope: :MyPublisher)
+Wisper.subscribe(MyListener.new, scope: MyPublisher)
+Wisper.subscribe(MyListener.new, scope: "MyPublisher")
+Wisper.subscribe(MyListener.new, scope: [:MyPublisher, :MyOtherPublisher])
+```
+
+This will subscribe the listener to all instances of the specified class(es) and their
+subclasses.
+
+Alternatively you can also do exactly the same with a publisher class itself:
+
+```ruby
+MyPublisher.subscribe(MyListener.new)
+```
+
+## Temporary Global Listeners
+
+You can also globally subscribe listeners for the duration of a block.
+
+```ruby
+Wisper.subscribe(MyListener.new, OtherListener.new) do
+  # do stuff
+end
+```
+
+Any events broadcast within the block by any publisher will be sent to the
+listeners.
+
+This is useful for capturing events published by objects to which you do not have access in a given context.
+
+Temporary Global Listeners are threadsafe.
+
+## Subscribing to selected events
+
+By default a listener will get notified of all events it can respond to. You
+can limit which events a listener is notified of by passing a string, symbol,
+array or regular expression to `on`:
+
+```ruby
+post_creator.subscribe(PusherListener.new, on: :create_post_successful)
+```
+
+## Prefixing broadcast events
+
+If you would prefer listeners to receive events with a prefix, for example
+`on`, you can do so by passing a string or symbol to `prefix:`.
+
+```ruby
+post_creator.subscribe(PusherListener.new, prefix: :on)
+```
+
+If `post_creator` were to broadcast the event `post_created` the subscribed
+listeners would receive `on_post_created`. You can also pass `true` which will
+use the default prefix, "on".
+
+## Mapping an event to a different method
+
+By default the method called on the listener is the same as the event
+broadcast. However it can be mapped to a different method using `with:`.
+
+```ruby
+report_creator.subscribe(MailResponder.new, with: :successful)
+```
+
+This is pretty useless unless used in conjunction with `on:`, since all events
+will get mapped to `:successful`. Instead you might do something like this:
+
+```ruby
+report_creator.subscribe(MailResponder.new, on:   :create_report_successful,
+                                            with: :successful)
+```
+
+If you pass an array of events to `on:` each event will be mapped to the same
+method when `with:` is specified. If you need to listen for select events
+_and_ map each one to a different method subscribe the listener once for
+each mapping:
+
+```ruby
+report_creator.subscribe(MailResponder.new, on:   :create_report_successful,
+                                            with: :successful)
+
+report_creator.subscribe(MailResponder.new, on:   :create_report_failed,
+                                            with: :failed)
+```
+
+You could also alias the method within your listener, as such
+`alias successful create_report_successful`.
+
+## Testing
+
+Testing matchers and stubs are in seperate gems.
+
+* [wisper-rspec](https://github.com/krisleech/wisper-rspec)
+* [wisper-minitest](https://github.com/digitalcuisine/wisper-minitest)
+
+### Clearing Global Listeners
+
+If you use global listeners in non-feature tests you _might_ want to clear them
+in a hook to prevent global subscriptions persisting between tests.
+
+```ruby
+after { Wisper.clear }
+```
+
+## Need help?
+
+The [Wiki](https://github.com/krisleech/wisper/wiki) has more examples,
+articles and talks.
+
+Got a specific question, try the
+[Wisper tag on StackOverflow](http://stackoverflow.com/questions/tagged/wisper).
+
+## Compatibility
+
+Tested with MRI 2.x, JRuby and Rubinius.
+
+See the [build status](https://travis-ci.org/krisleech/wisper) for details.
+
+## Running Specs
+
+```
+bundle exec rspec
+```
+
+To run the specs on code changes try [entr](http://entrproject.org/):
+
+```
+ls **/*.rb | entr bundle exec rspec
+```
+
+## Contributing
+
+Please read the [Contributing Guidelines](https://github.com/krisleech/wisper/blob/master/CONTRIBUTING.md).
+
+## Security
+
+* gem releases are [signed](http://guides.rubygems.org/security/) ([public key](https://github.com/krisleech/wisper/blob/master/gem-public_cert.pem))
+* commits are GPG signed ([public key](https://pgp.mit.edu/pks/lookup?op=get&search=0x3ABC74851F7CCC88))
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2013 Kris Leech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the 'Software'), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.