brainguy 0.0.1

data/Rakefile

@@ -0,0 +1,21 @@
+require "bundler/gem_tasks"
+require "yard"
+
+task :build => :readme
+
+desc "Build the README"
+task :readme => "README.markdown"
+
+file "README.markdown" => "README.erb" do
+  puts "Generating README.markdown"
+  require "erb"
+  template = IO.read("README.erb")
+  IO.write("README.markdown", ERB.new(template).result)
+end
+
+YARD::Rake::YardocTask.new do |t|
+  # t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+  # t.options = ['--any', '--extra', '--opts'] # optional
+  # t.stats_options = ['--list-undoc']         # optional
+end
+task :yard => :readme

data/brainguy.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'brainguy/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "brainguy"
+  spec.version       = Brainguy::VERSION
+  spec.authors       = ["Avdi Grimm"]
+  spec.email         = ["avdi@avdi.org"]
+  spec.summary       = %q{An Observer pattern library}
+  spec.description   = %q{A somewhat fancy observer pattern library with
+features like named events and scoped subscriptions.}
+  spec.homepage      = "https://github.com/avdi/brainguy"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.2"
+  spec.add_development_dependency "benchmark-ips"
+  spec.add_development_dependency "yard", "~> 0.8.7"
+  spec.add_development_dependency "seeing_is_believing", "~> 2.2"
+end

data/examples/include_manifestly_observable.rb

@@ -0,0 +1,22 @@
+require "brainguy"
+
+class Toaster
+  include Brainguy::ManifestlyObservable.new(:start, :pop)
+
+  def make_toast
+    emit(:start)
+    emit(:lop)
+  end
+end
+
+toaster = Toaster.new
+toaster.events.unknown_event_policy = :raise_error
+toaster.on(:plop) do
+  puts "Toast is done!"
+end
+toaster.make_toast
+
+# ~> Brainguy::UnknownEvent
+# ~> #on received for unknown event type 'plop'
+# ~>
+# ~> xmptmp-in27856uxq.rb:14:in `<main>'

data/examples/include_observable.rb

@@ -0,0 +1,18 @@
+require "brainguy"
+
+class Toaster
+  include Brainguy::Observable
+
+  def make_toast
+    emit(:start)
+    emit(:pop)
+  end
+end
+
+toaster = Toaster.new
+toaster.on(:pop) do
+  puts "Toast is done!"
+end
+toaster.make_toast
+
+# >> Toast is done!

data/examples/include_observer.rb

@@ -0,0 +1,36 @@
+require "brainguy"
+
+class Poem
+  include Brainguy::Observable
+  def recite
+    emit(:title, "Jabberwocky")
+    emit(:line, "'twas brillig, and the slithy toves")
+    emit(:line, "Did gyre and gimbal in the wabe")
+  end
+end
+
+class HtmlFormatter
+  include Brainguy::Observer
+
+  attr_reader :result
+  
+  def initialize
+    @result = ""
+  end
+  
+  def on_title(event)
+    @result << "<h1>#{event.args.first}</h1>"
+  end
+
+  def on_line(event)
+    @result << "#{event.args.first}</br>"
+  end
+end
+
+p = Poem.new
+f = HtmlFormatter.new
+p.events.attach(f)
+p.recite
+
+f.result
+# => "<h1>Jabberwocky</h1>'twas brillig, and the slithy toves</br>Did gyre an...

data/examples/manual_observable.rb

@@ -0,0 +1,22 @@
+require "brainguy"
+
+class Toaster
+  attr_reader :events
+
+  def initialize
+    @events = Brainguy::Emitter.new(self)
+  end
+
+  def make_toast
+    events.emit(:start)
+    events.emit(:pop)
+  end
+end
+
+toaster = Toaster.new
+toaster.events.on(:pop) do
+  puts "Toanst is done!"
+end
+toaster.make_toast
+
+# >> Toast is done!

data/examples/open_observer.rb

@@ -0,0 +1,31 @@
+require "brainguy"
+
+class VideoRender
+  include Brainguy::Observable
+  attr_reader :name
+  def initialize(name)
+    @name = name
+  end
+  
+  def do_render
+    emit(:complete)
+  end
+end
+
+v1 = VideoRender.new("foo.mp4")
+v2 = VideoRender.new("bar.mp4")
+
+observer = Brainguy::OpenObserver.new do |o|
+  o.on_complete do |event|
+    puts "Video #{event.source.name} is done rendering!"
+  end
+end
+
+v1.events.attach(observer)
+v2.events.attach(observer)
+
+v1.do_render
+v2.do_render
+
+# >> Video foo.mp4 is done rendering!
+# >> Video bar.mp4 is done rendering!

data/examples/proc_observer.rb

@@ -0,0 +1,10 @@
+require "brainguy"
+
+events = Brainguy::Emitter.new
+observer = proc do |event|
+  puts "Got event: #{event.name}"
+end
+events.attach(observer)
+events.emit(:ding)
+
+# >> Got event: ding

data/examples/scoped_subscription.rb

@@ -0,0 +1,39 @@
+require "brainguy"
+
+class Poem
+  include Brainguy::Observable
+  def recite(&block)
+    with_subscription_scope(block) do
+      emit(:title, "Jabberwocky")
+      emit(:line, "'twas brillig, and the slithy toves")
+      emit(:line, "Did gyre and gimbal in the wabe")
+    end
+  end
+end
+
+class HtmlFormatter
+  include Brainguy::Observer
+
+  attr_reader :result
+  
+  def initialize
+    @result = ""
+  end
+  
+  def on_title(event)
+    @result << "<h1>#{event.args.first}</h1>"
+  end
+
+  def on_line(event)
+    @result << "#{event.args.first}</br>"
+  end
+end
+
+p = Poem.new
+f = HtmlFormatter.new
+p.recite do |events|
+  events.attach(f)
+end
+
+f.result
+# => "<h1>Jabberwocky</h1>'twas brillig, and the slithy toves</br>Did gyre an...

data/examples/synopsis.rb

@@ -0,0 +1,56 @@
+require "brainguy"
+
+class SatelliteOfLove
+  include Brainguy::Observable
+
+  def intro_song
+    emit(:robot_roll_call)
+  end
+
+  def send_the_movie
+    emit(:movie_sign)
+  end
+end
+
+class Crew
+  include Brainguy::Observer
+end
+
+class TomServo < Crew
+  def on_robot_roll_call(event)
+    puts "Tom: Check me out!"
+  end
+end
+
+class CrowTRobot < Crew
+  def on_robot_roll_call(event)
+    puts "Crow: I'm different!"
+  end
+end
+
+class MikeNelson < Crew
+  def on_movie_sign(event)
+    puts "Mike: Oh no we've got movie sign!"
+  end
+end
+
+sol = SatelliteOfLove.new
+# Attach specific event handlers without a listener object
+sol.on(:robot_roll_call) do
+  puts "[Robot roll call!]"
+end
+sol.on(:movie_sign) do
+  puts "[Movie sign flashes]"
+end
+sol.events.attach TomServo.new
+sol.events.attach CrowTRobot.new
+sol.events.attach MikeNelson.new
+
+sol.intro_song
+sol.send_the_movie
+
+# >> [Robot roll call!]
+# >> Tom: Check me out!
+# >> Crow: I'm different!
+# >> [Movie sign flashes]
+# >> Mike: Oh no we've got movie sign!

data/lib/brainguy.rb

@@ -0,0 +1,34 @@
+require "brainguy/version"
+require "brainguy/event"
+require "brainguy/emitter"
+require "brainguy/idempotent_emitter"
+require "brainguy/observable"
+require "brainguy/manifestly_observable"
+
+require "brainguy/subscription_scope"
+require "brainguy/fluent_emitter"
+require "brainguy/observer"
+
+# Namespace for the `brainguy` gem. See {file:README.md} for usage instructions.
+module Brainguy
+  # Execute passed block with a temporary subscription scope. See README for
+  # examples.
+  #
+  # @param source   the object initiating the event
+  # @param listener_block [:call] an optional callable that should hook up
+  #   listeners
+  # @param subscription_set [Emitter] an existing subscription set to
+  #   layer on top of
+  def self.with_subscription_scope(
+      source,
+      listener_block   = nil,
+      subscription_set = IdempotentEmitter.new(source))
+    subscription_set.with_subscription_scope do |scope|
+      listener_block.call(scope) if listener_block
+      yield scope
+    end
+    unless listener_block
+      FluentEmitter.new(subscription_set)
+    end
+  end
+end

data/lib/brainguy/basic_notifier.rb

@@ -0,0 +1,19 @@
+module Brainguy
+  # A notifier encapsulates various strategies for notifying subscriptions of
+  # events. This is the most basic form of notifier. It just passes the event
+  # on with no extra logic.
+  class BasicNotifier
+    # Notify a subscription of an event
+    #
+    # @return (see Subscription#handle)
+    def notify(subscription, event)
+      subscription.handle(event)
+    end
+
+    # Some notifiers have interesting results. This one just returns nil.
+    # @return nil
+    def result
+      nil
+    end
+  end
+end

data/lib/brainguy/emitter.rb

@@ -0,0 +1,110 @@
+require "delegate"
+require "set"
+require "brainguy/full_subscription"
+require "brainguy/single_event_subscription"
+require "brainguy/event"
+require "brainguy/basic_notifier"
+require "brainguy/open_observer"
+
+module Brainguy
+  # This object keeps track of all the listeners (observers) subscribed to a
+  # particular event source object.
+  class Emitter < DelegateClass(Set)
+    DEFAULT_NOTIFIER = BasicNotifier.new
+
+    # Create a new {Emitter} that shares its inner dataset with an
+    # existing one. This exists so that it's possible to generate temporary
+    # copies of a {Emitter} with different, specialized semantics;
+    # for instance, an {IdempotentEmitter} that shares the same
+    # set of subscriptions as an existing {Emitter}.
+    # @param event_source [Object] the event-originating object
+    # @param subscription_set [Emitter] the existing set to share
+    #   subscriptions with
+    # @return [Emitter]
+    def self.new_from_existing(event_source, subscription_set)
+      new(event_source, subscriptions: subscription_set.subscriptions)
+    end
+
+    # @param event_source [Object] the event-originating object
+    # @option options [Set<Subscription>] :subscriptions (Set.new) the
+    #   underlying set of subscriptions
+    # @option options [:call] :notifier_maker a factory for notifiers.
+    def initialize(event_source = self, options = {})
+      super(options[:subscriptions] || Set.new)
+      @event_source   = event_source
+      @notifier_maker = options.fetch(:notifier_maker) {
+        ->() { DEFAULT_NOTIFIER }
+      }
+    end
+
+    # @return [Set<Subscription>] the underlying set of subscription objects
+    def subscriptions
+      __getobj__
+    end
+
+    # Attach a new object to listen for events. A listener is expected to be
+    # call-able, and it will receive the `#call` message with an {Event} each
+    # time one is emitted.
+    # @param new_listener [:call]
+    # @return [Subscription] a subscription object which can be used to
+    #   cancel the subscription.
+    def attach(new_listener)
+      FullSubscription.new(self, new_listener).tap do |subscription|
+        self << subscription
+      end
+    end
+
+    # Detach a listener. This locates the subscription corresponding to the
+    # given listener (if any), and removes it.
+    # @param [:call] listener a listener to be unsubscribed
+    # @return [void]
+    def detach(listener)
+      delete(FullSubscription.new(self, listener))
+    end
+
+    # Attach blocks of code to handle specific named events.
+    # @overload on(name, &block)
+    #   Attach a block to be called for a specific event. The block will be
+    #   called with the event arguments (not the event object).
+    #   @param name [Symbol]
+    #   @param block [Proc] what to do when the event is emitted
+    # @overload on(handlers)
+    #   Attach multiple event-specific handlers at once.
+    #   @param handlers [Hash{Symbol => [:call]}] a map of event names to
+    #     callable handlers.
+    # @return (see #attach)
+    def on(name_or_handlers, &block)
+      case name_or_handlers
+      when Symbol
+        attach_to_single_event(name_or_handlers, block)
+      when Hash
+        attach(OpenObserver.new(name_or_handlers))
+      else
+        fail ArgumentError, "Event name or Hash required"
+      end
+    end
+
+    # Emit an event to be distributed to all interested listeners.
+    # @param event_name [Symbol] the name of the event
+    # @param extra_args [Array] any extra arguments that should accompany the
+    #   event
+    # @return the notifier's result value
+    def emit(event_name, *extra_args)
+      notifier = @notifier_maker.call
+      each do |subscription|
+        event = Event.new(event_name, @event_source, extra_args)
+        notifier.notify(subscription, event)
+      end
+      notifier.result
+    end
+
+    private
+
+    def attach_to_single_event(event_name, block)
+      SingleEventSubscription.new(self, block, event_name).tap do
+      |subscription|
+        self << subscription
+      end
+    end
+  end
+end