drama_queen 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a1cb78ce2e3af6d28e68255b0505b9d704c86ed5
+  data.tar.gz: 64f553c705c27367ebc8b17cf6229c589e371b3f
+SHA512:
+  metadata.gz: 343d156ca2cbf4d87ba4846c316ce5d3c51763a870d688744ce22982940942f02f2052ae00bae6f0d03fa69b20335545ec35388e3582bd287844c64aa45e6c55
+  data.tar.gz: 220dd484df1bc26b0c438b752f5883d27a13fbe61ed14fc21d2f70e84ac2ad09748791cd3fcfe528e438418445ee2b6752792b929c3beca6d593e17bb271481d

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+.idea/

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - jruby-19mode

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in drama_queen.gemspec
+gemspec
+
+gem 'yard'
+

data/History.md

@@ -0,0 +1,3 @@
+### 0.1.0 / 11-Nov-2013
+
+    * Initial release.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Steve Loveless
+
+MIT License
+
+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.

data/README.md

@@ -0,0 +1,193 @@
+# DramaQueen
+
+A simple, synchronous pub-sub/observer library that allows objects to observe or
+publish and subscribe to topics.
+
+[![Build Status](https://travis-ci.org/turboladen/drama_queen.png?branch=master)](https://travis-ci.org/turboladen/drama_queen)
+
+## Features
+
+* Observe Ruby objects and receive updates when they change
+  ([Observer Pattern](http://en.wikipedia.org/wiki/Observer_pattern))
+* Subscribe and publish on a topic or routing key
+  ([Publish-Subscribe Pattern](http://en.wikipedia.org/wiki/Publish–subscribe_pattern))
+* Synchronous, no threading
+
+
+## Usage
+
+My initial desire for this library was to replace Ruby's built-in Observer
+module with something that allowed objects to observe specific topics, as
+opposed to simply just observing objects.  DramaQueen lets you do both.
+
+### Subscribe to an object
+
+```ruby
+class MyProducer
+  include DramaQueen::Producer
+
+  def do_stuff
+    publish(self, "I did some stuff!", [1, 2, 3])
+  end
+end
+
+class MyConsumer
+  include DramaQueen::Consumer
+
+  def initialize(topic)
+    subscribe(topic, :call_me!)
+  end
+
+  def call_me!(message, neat_array)
+    puts "He did it! -> #{message}"
+    puts "A present for me?!  #{neat_array}"
+  end
+end
+
+producer = MyProducer.new
+consumer = MyConsumer.new(producer)
+producer.do_stuff
+
+# "He did it! -> I did some stuff!"
+# "A present for me?!  [1, 2, 3]"
+#=> true
+```
+
+`consumer` subscribes to the `producer` object and `producer` publishes on the
+topic of itself, thus publishing to `consumer`.  Also notice that the consumer
+passed in `:call_me!` as the second parameter to `#subscribe`: that registers
+the `#call_me!` method to be called when the producer publishes.  We can see
+that when we call `producer.do_stuff`, `consumer.call_me!` gets called by
+the strings that get output to the console.  Also notice that `consumer.call_me!`
+gets the same parameters passed to it that are passed in to `producer`'s call
+to `#publish`.
+
+
+### Subscribe to a topic
+
+Subscribing to a topic is no different than subscribing to an object.
+
+```ruby
+class ThingsProducer
+  include DramaQueen::Producer
+
+  def do_stuff
+    publish('things', "I did some stuff!", [1, 2, 3])
+  end
+end
+
+class ThingsConsumer
+  include DramaQueen::Consumer
+
+  def initialize(topic)
+    subscribe(topic, :call_me!)
+  end
+
+  def call_me!(message, neat_array)
+    puts "He did it! -> #{message}"
+    puts "A present for me?!  #{neat_array}"
+  end
+end
+
+producer = ThingsProducer.new
+consumer = ThingsConsumer.new('things')
+producer.do_stuff
+
+# "He did it! -> I did some stuff!"
+# "A present for me?!  [1, 2, 3]"
+#=> true
+```
+
+Moral of the story: The topic that you publish/subscribe on can be any Ruby
+object--how you use this is up to you.
+
+### Routing Key Matching
+
+Thus far, we've talked about subscribing to a "topic".
+
+```ruby
+class A
+  include DramaQueen::Consumer
+
+  def initialize
+    subscribe 'root.*.children', :call_me
+  end
+
+  def call_me(*args)
+    puts "A got called with args: #{args}"
+  end
+end
+
+class B
+  include DramaQueen::Producer
+
+  def do_stuff
+    publish 'root.parent', 1, 2, 3
+  end
+end
+
+class C
+  include DramaQueen::Producer
+
+  def do_stuff
+    publish 'root.parent.children', 1, 2, 3
+  end
+end
+
+a = A.new
+b = B.new
+c = C.new
+
+b.do_stuff
+
+# (A does not get called)
+c.do_stuff
+# "A got called with args: 1, 2, 3
+#=> true
+```
+
+See {DramaQueen::Exchange} for more.
+
+### Synchronous Only!
+
+DramaQueen does not use any threading or fancy asynchronous stuff.  When your
+producer publishes, you can expect your subscribers to receive the notifications:
+
+* in the order the publishing was triggered, and
+* in the order that consumers subscribed.
+
+This is intentional.  If you want publishing to take place in a thread, you can
+thread your call to #publish in your code.
+
+### Application-wide
+
+DramaQueen stores all of its exchanges in a singleton, which is thus accessible
+throughout your app/library.  This makes it possible to subscribe to a topic in
+one object and publish to that topic in another unrelated object from anywhere
+in your code.  And while you have access to `DramaQueen`, you shouldn't ever
+need to deal with it directly--just use `#publish` and `#subscribe` and let it
+do its thing.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'drama_queen'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install drama_queen
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task default: :spec

data/drama_queen.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'drama_queen/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'drama_queen'
+  spec.version       = DramaQueen::VERSION
+  spec.author        = 'Steve Loveless'
+  spec.email         = 'steve.loveless@gmail.com'
+  spec.description   = %q{A simple, non-threaded, local-object pub-sub/observer
+with the ability to pub-sub on topics.  Topics can be any Ruby object.}
+  spec.summary       = spec.description
+  spec.homepage      = 'https://githb.com/turboladen/drama_queen'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = %w[lib]
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 3.0.0.beta1'
+end

data/lib/drama_queen.rb

@@ -0,0 +1,37 @@
+require_relative 'drama_queen/version'
+
+
+# This is the singleton that maintains the list of active exchanges.
+module DramaQueen
+
+  # The list of all exchanges that DramaQueen knows about.  This is updated
+  # by DramaQueen::Consumers as they subscribe to topics.
+  #
+  # @return [Array<DramaQueen::Exchange>]
+  def self.exchanges
+    @exchanges ||= Array.new
+  end
+
+  # Finds the DramaQueen::Exchange for the given +routing_key+.
+  #
+  # @param [Object] routing_key
+  # @return [DramaQueen::Exchange]
+  def self.exchange_for(routing_key)
+    exchanges.find do |exchange|
+      exchange.routing_key == routing_key
+    end
+  end
+
+  # @param [Object] routing_key
+  # @return [Boolean]
+  def self.routes_to?(routing_key)
+    !!exchange_for(routing_key)
+  end
+
+  # Removes all exchanges from the exchanges list.
+  #
+  # @return [Array]
+  def self.unsubscribe_all
+    @exchanges = Array.new
+  end
+end

data/lib/drama_queen/consumer.rb

@@ -0,0 +1,34 @@
+require_relative '../drama_queen'
+require_relative 'exchange'
+
+
+module DramaQueen
+
+  # A +consumer+ is simply an object that receives messages from a +producer+.
+  # In order to sign up to receive messages from a producer, the consumer
+  # subscribes to a +topic+ that they're interested in.  When the producer
+  # +publish+es something on that topic, the consumer's +callback+ will get
+  # called.
+  module Consumer
+
+    # @param [Object] routing_key The routing key that represents the Exchange
+    #   to subscribe to.
+    # @param [Symbol,Method,Proc] callback If given a Symbol, this will be
+    #   converted to a Method that gets called on the includer of Consumer.  If
+    #   +callback+ is not a Symbol, it simply must just respond to +call+.
+    def subscribe(routing_key, callback)
+      callable_callback = callback.is_a?(Symbol) ? method(callback) : callback
+
+      unless callable_callback.respond_to?(:call)
+        raise "The given callback is not a Symbol, nor responds to #call: #{callback}"
+      end
+
+      unless DramaQueen.routes_to? routing_key
+        DramaQueen.exchanges << Exchange.new(routing_key)
+      end
+
+      exchange = DramaQueen.exchange_for(routing_key)
+      exchange.subscribers << callable_callback
+    end
+  end
+end

data/lib/drama_queen/exchange.rb

@@ -0,0 +1,137 @@
+module DramaQueen
+
+  # An Exchange determines which objects will receive messages from a Producer.
+  # It is merely a wrapper around the +routing_key+ that is given on
+  # initialization, allowing to more easily determine which routing_keys are
+  # related, and thus if any subscribers to the related exchanges should get
+  # notified in addition to the subscribers to this exchange.
+  #
+  # A Exchange routing_key is what Producers and Consumers refer to when they're
+  # looking to publish or subscribe.  The Exchange +routing_key+ can be any
+  # object, but some extra semantics & functionality come along if you use
+  # DramaQueen's route_key globbing.
+  #
+  # === Ruby Objects
+  #
+  # First, the simplest case: a +routing_key+ that is any Ruby object.
+  # Producers and subscribers will use this case when observing that Ruby
+  # object.  #related_exchanges will be empty; all messages published using this
+  # routing_key will only get delivered to consumers subscribing to this
+  # Exchange's routing_key.  If you only need this approach, you might be better
+  # off just using Ruby's build-in +Observer+ library--it accomplishes this, and
+  # is much simpler than DramaQueen.
+  #
+  # === RouteKey Globbing
+  #
+  # Now, the fun stuff: routing key globbing uses period-delimited strings to
+  # infer some hierarchy of Exchanges.  Using this approach lets you tie
+  # together other Exchanges via +#related_keys+, thus letting you build
+  # some organization/structure into your whole system of routing messages.
+  # These globs (somewhat similar to using +Dir.glob+ for file systems) let your
+  # producers and consumers pub/sub to large numbers of topics, yet organize
+  # those topics.  The structure that you build is up to you.  Here's a
+  # contrived example.  You could use set up a routing key scheme like:
+  #
+  # * +"my_library.bob.pants"+
+  # * +"my_library.bob.shirts"+
+  # * +"my_library.sally.pants"+
+  # * +"my_library.sally.shirts"+
+  #
+  # When producers publish to +"my_library.bob.pants"+, only consumers of
+  # +"my_library.bob.pants"+ get notified.  If a producer publishes to
+  # +"my_library.*.pants"+, consumers of both +"my_library.bob.pants"+ _and_
+  # +"my_library.sally.pants"+ get notifications.  Going the other way, if
+  # a consumer subscribes to +"my_library.*.pants"+, then when a producer on
+  # +"my_library.bob.pants"+, _or_ +"my_library.sally.pants"+, _or_
+  # +"my_library.*.pants"+, that consumer gets all of those messages.
+  #
+  # Further, producers and consumers can use a single asterisk at multiple
+  # levels: +"\*.\*.shirts"+ would resolve to both +"my_library.bob.shirts"+ and
+  # +"my_library.sally.shirts"+; if there was a +"someone_else.vendor.shirts"+,
+  # for example, that would route as well.
+  #
+  # Lastly, you can you a double-asterisk to denote that you want everything
+  # from that level and deeper.  So, +"**"+ would match _all_ existing routing
+  # keys, including single-object (non-glob style) keys.  +"my_library.**"+
+  # would match all four of our +"my_library"+ keys above.
+  #
+  # As you're devising your routing key scheme, consider naming like you would
+  # name classes/modules in a Ruby library: use namespaces to avoid messing
+  # others up!  Notice the use of +"my_library..."+ above... that was on
+  # purpose.
+  class Exchange
+
+    # @return [Object]
+    attr_reader :routing_key
+
+    # @return [Array]
+    attr_reader :subscribers
+
+    # @param [Object] routing_key
+    def initialize(routing_key)
+      @routing_key = routing_key
+      @subscribers = []
+    end
+
+    # @param [Object] routing_key
+    # @return [Boolean]
+    def routes_to?(routing_key)
+      related_exchanges.include? routing_key
+    end
+
+    # All other DramaQueen::Exchange objects that the current Exchange routes
+    # to.
+    #
+    # @return [Array<DramaQueen::Exchange]
+    def related_exchanges
+      return DramaQueen.exchanges if self.routing_key == '**'
+
+      DramaQueen.exchanges.find_all do |exchange|
+        next if exchange.routing_key == '**'
+        next if exchange.routing_key == self.routing_key
+
+        if self.routing_key.is_a?(String) && exchange.routing_key.is_a?(String)
+          routing_key_match?(exchange.routing_key, self.routing_key) ||
+            routing_key_match?(self.routing_key, exchange.routing_key)
+        else
+          exchange == self
+        end
+      end
+    end
+
+    # Calls each subscriber's callback with the given arguments.
+    #
+    # @param args
+    def notify_with(*args)
+      @subscribers.each do |subscriber|
+        subscriber.call(*args)
+      end
+    end
+
+    private
+
+    # @return [Boolean]
+    def routing_key_match?(first, second)
+      self_matcher = make_matchable(second)
+
+      !!first.match(Regexp.new(self_matcher))
+    end
+
+    # @param [String] string
+    # @return [String]
+    def make_matchable(string)
+      matcher = if string =~ %r[\*\*]
+        string.sub(%r[\.?\*\*], '\..+')
+      elsif string =~ %r[\*]
+        string.sub(%r[\*], '[^\.]+')
+      else
+        string
+      end
+
+      matcher = matcher.gsub('.*', '\.\w+')
+      matcher = "\\A#{matcher}\\z"
+
+      matcher
+    end
+  end
+end