brainguy 0.0.1

data/lib/brainguy/error_collecting_notifier.rb

@@ -0,0 +1,26 @@
+require "brainguy/error_handling_notifier"
+
+module Brainguy
+  # A notifier wrapper that captures exceptions and collects them into a Hash.
+  class ErrorCollectingNotifier < ErrorHandlingNotifier
+    # (see ErrorHandlingNotifier#initialize)
+    def initialize(notifier)
+      super(notifier, method(:add_error))
+      @errors = {}
+    end
+
+    # Add another error to the list
+    # @api private
+    def add_error(subscription, error)
+      @errors[subscription] = error
+    end
+
+    # Return list of errors captured while notifying subscriptions. One entry
+    # for every subscription that raised an error.
+    #
+    # @return [Hash{Subscription => Exception}]
+    def result
+      @errors
+    end
+  end
+end

data/lib/brainguy/error_handling_notifier.rb

@@ -0,0 +1,63 @@
+require "brainguy/basic_notifier"
+
+module Brainguy
+  # It is possible that errors may be raised when notifying listeners. This
+  # notifier wrapper class provides some leeway in how to handle those
+  # errors. It does this by capturing errors and applying a policy to them.
+  #
+  # Includes a selection of common error policies.
+  class ErrorHandlingNotifier < DelegateClass(BasicNotifier)
+    # The suppression strategy. Throws errors away.
+    SUPPRESS_STRATEGY = ->(_subscription, _error) do
+      # NOOP
+    end
+
+    # The warning strategy. Turns errors into warnings.
+    WARN_STRATEGY = ->(_subscription, error) do
+      warn "#{error.class}: #{error.message}"
+    end
+
+    # The raise strategy. Re-raises errors as if they had never been captured.
+    RAISE_STRATEGY = ->(_subscription, error) do
+      raise error
+    end
+
+    # @param notifier [#notify] the notifier to wrap
+    # @param error_handler [:call] a callable that determined error policy
+    #   There are some symbolic shortcuts available here:
+    #   - `:suppress`: Suppress errors completely.
+    #   - `:warn`: Convert errors to warnings.
+    #   - `:raise`: Re-raise errors.
+    def initialize(notifier, error_handler = RAISE_STRATEGY)
+      super(notifier)
+      @error_handler = resolve_error_handler(error_handler)
+    end
+
+    # Notify a `subscription` of an event, and apply the error policy to any
+    # exception that is raised.
+    #
+    # @return [@Object] whatever the underlying notifier returned
+    def notify(subscription, *)
+      super
+    rescue => error
+      @error_handler.call(subscription, error)
+    end
+
+    # @return [nil]
+    def result
+      nil
+    end
+
+    private
+
+    def resolve_error_handler(handler)
+      case handler
+      when :suppress then SUPPRESS_STRATEGY
+      when :warn     then WARN_STRATEGY
+      when :raise    then RAISE_STRATEGY
+      when Symbol    then fail ArgumentError, "Unknown mnemonic: #{handler}"
+      else handler
+      end
+    end
+  end
+end

data/lib/brainguy/event.rb

@@ -0,0 +1,13 @@
+module Brainguy
+  # An event. Bundles up a symbolic `name`, an originating object (`source`).
+  # and a list of event-defined `args`.
+  Event = Struct.new(:name, :source, :args) do
+    # @param name [Symbol] the event name
+    # @param source [Object] the originating object
+    # @param args [Array] a list of event-specific arguments
+    def initialize(*)
+      super
+      self.args ||= []
+    end
+  end
+end

data/lib/brainguy/fluent_emitter.rb

@@ -0,0 +1,30 @@
+require "brainguy/emitter"
+require "delegate"
+
+module Brainguy
+  # A wrapper for a {Emitter} that enables a "fluent API" by
+  # returning `self` from each method.
+  #
+  # @example Enables code like this:
+  #
+  #   kitten.on(:purr) do
+  #     # handle purr...
+  #   end.on(:mew) do
+  #     # handle mew...
+  #   end
+  class FluentEmitter < DelegateClass(Emitter)
+    # (see Emitter#on)
+    # @return `self`
+    def on(*)
+      super
+      self
+    end
+
+    # (see Emitter#attach)
+    # @return `self`
+    def attach(*)
+      super
+      self
+    end
+  end
+end

data/lib/brainguy/full_subscription.rb

@@ -0,0 +1,8 @@
+require "brainguy/subscription"
+
+module Brainguy
+  # A {Subscription} which transmits all events to the listener.
+  class FullSubscription < Subscription
+
+  end
+end

data/lib/brainguy/idempotent_emitter.rb

@@ -0,0 +1,40 @@
+require "brainguy/emitter"
+
+module Brainguy
+  # A type of {Emitter} that records and "plays back" events to new
+  # listeners. That way a listener will never miss an event, even if it
+  # subscribes late.
+  #
+  # This class is probably best used in short-lived scopes, since the log of
+  # events will continually grow.
+  class IdempotentEmitter < Emitter
+    # (see Emitter#initialize)
+    def initialize(*)
+      super
+      @event_log = []
+    end
+
+    # Emit an event and record it in the log.
+    # @event_name (see Emitter#emit)
+    # @extra_args (see Emitter#emit)
+    # @return (see Emitter#emit)
+    def emit(event_name, *extra_args)
+      @event_log.push(Event.new(event_name, @event_source, extra_args))
+      super
+    end
+
+    # Add a new subscription, and immediately play back any missed events to
+    # it.
+    #
+    # @param subscription (see Emitter#<<)
+    # @return (see Emitter#<<)
+    def <<(subscription)
+      super
+      @event_log.each do |event|
+        subscription.handle(event)
+      end
+    end
+
+    alias_method :add, :<<
+  end
+end

data/lib/brainguy/manifest_emitter.rb

@@ -0,0 +1,78 @@
+require "brainguy/emitter"
+require "delegate"
+
+module Brainguy
+  # Raised for an event that is not listed in the manifest.
+  class UnknownEvent < StandardError
+  end
+
+  # A {Emitter} wrapper which "locks down" a subscription set to a
+  # known list of event names. Useful for preventing typos in event names.
+  class ManifestEmitter < DelegateClass(Emitter)
+
+    # A policy which outputs a warning on unrecognized event names
+    WARN_POLICY        = Kernel.method(:warn)
+
+    # A policy which raises an exception on unrecognized evend names.
+    RAISE_ERROR_POLICY = ->(message) do
+      fail UnknownEvent, message, caller.drop_while{|l| l.include?(__FILE__)}
+    end
+
+    # The list of known event names
+    # @return [Array<Symbol>]
+    attr_reader :known_types
+
+    # @param subscription_set [Emitter] the set to be wrapped
+    # @param options [Hash] a hash of options
+    # @option options [:call, Symbol] :policy the policy for what to do on
+    #   unknown event names. A callable or a mnemonic symbol.
+    #   The following mnemonics are supported:
+    #
+    #     - `:warn`: Output a warning
+    #     - `:raise_error`: Raise an exception
+    def initialize(subscription_set, options = {})
+      super(subscription_set)
+      @known_types = []
+      policy = options.fetch(:policy) { :warn }
+      @policy      = resolve_policy(policy)
+    end
+
+
+    def unknown_event_policy=(new_policy)
+      @policy = resolve_policy(new_policy)
+    end
+
+    # (see Emitter#on)
+    def on(event_name, &block)
+      check_event_name(event_name, __callee__)
+      super
+    end
+
+    # (see Emitter#emit)
+    def emit(event_name, *)
+      check_event_name(event_name, __callee__)
+      super
+    end
+
+    private
+
+    def check_event_name(event_name, method_name)
+      unless @known_types.include?(event_name)
+        message =
+            "##{method_name} received for unknown event type '#{event_name}'"
+        @policy.call(message)
+      end
+    end
+
+    def resolve_policy(policy)
+      case policy
+      when :warn
+        WARN_POLICY
+      when :raise_error
+        RAISE_ERROR_POLICY
+      else
+        fail ArgumentError, "Invalid policy: #{policy}"
+      end
+    end
+  end
+end

data/lib/brainguy/manifestly_observable.rb

@@ -0,0 +1,62 @@
+require "brainguy/observable"
+require "brainguy/manifest_emitter"
+
+module Brainguy
+  # A custom {Module} subclass which acts like {Observable}, except with an
+  # event type manifest. This is a way to define an observable cladd with a
+  # known list of possible event types.
+  #
+  # @example
+  #   class MyApiRequest
+  #     include ManifestlyObservable.new(:success, :unauthorized, :error)
+  #     # ...
+  #   end
+  #
+  class ManifestlyObservable < Module
+
+    # Generate a new mixin module with a custom list of known event types.
+    def initialize(*known_events)
+      # Look out, this gets a bit gnarly...
+      @known_events = known_events
+      # Define the module body
+      super() do
+        # First off, let's make sure we have basic Observable functionality
+        include Observable
+
+        # Now, we override #events to wrap it in some extra goodness
+        define_method :events do
+
+          # Let's see what the current subscription set object is
+          subscription_set = super()
+
+          # If there is already another ManifestlyObservable included further
+          # up the chain...
+          if subscription_set.is_a?(ManifestEmitter)
+            # just add our event types to its subscription set
+            subscription_set.known_types.concat(known_events)
+            # But if this is the first ManifestlyObservable included...
+          else
+            # Wrap the subscription set in a ManifestEmitter
+            @brainguy_events = ManifestEmitter.new(subscription_set)
+            # Set up the known event types
+            @brainguy_events.known_types.concat(known_events)
+          end
+
+          # No need to do all this every time. Once we've set everything up,
+          # redefine the method on a per-instance level to be a simple getter.
+          define_singleton_method :events do
+            @brainguy_events
+          end
+          # Don't forget to return a value the first time around
+          @brainguy_events
+        end
+      end
+    end
+
+    # Return a meaningful description of the generated module.
+    # @return [String]
+    def to_s
+      "ManifestlyObservable(#{@known_events.map(&:inspect).join(', ')})"
+    end
+  end
+end

data/lib/brainguy/observable.rb

@@ -0,0 +1,33 @@
+require "forwardable"
+require "brainguy/emitter"
+
+module Brainguy
+  # A convenience module for making client classes observable.
+  module Observable
+    extend Forwardable
+
+    # @return [Emitter] the {Emitter} managing all
+    #   subscriptions to this object's events.
+    def events
+      @brainguy_subscriptions ||= Emitter.new(self)
+    end
+
+    # Create a temporary scope for transient subscriptions. Useful for
+    # making a single method listenable. See {file:README.md} for usage
+    # examples.
+    #
+    # @param listener_block (see Brainguy.with_subscription_scope)
+    def with_subscription_scope(listener_block, &block)
+      Brainguy.with_subscription_scope(self, listener_block, events, &block)
+    end
+
+    # @!method on(name_or_handlers, &block)
+    # (see {Emitter#on})
+    def_delegator :events, :on
+
+    # @!method emit
+    # (see {Emitter#emit})
+    def_delegator :events, :emit
+    private :emit
+  end
+end

data/lib/brainguy/observer.rb

@@ -0,0 +1,71 @@
+require "brainguy/event"
+
+module Brainguy
+
+  # A mixin for formal "listener" classes. Events received by the including
+  # class will be dispatched to `#on_<EVENT_NAME>` methods, if they exist. If
+  # no event-specific handler method is found, it will be sent to
+  # {#event_handler_missing}.
+  module Observer
+    module ClassMethods
+      HANDLER_METHOD_PATTERN = /\Aon_(.+)\z/
+
+      def method_added(method_name)
+        if method_name.to_s =~ HANDLER_METHOD_PATTERN
+          regenerate_dispatch_method
+        end
+        super
+      end
+
+      # [Re]generate a #call method containing a fast dispatch table from
+      # event names to handler method names. The code generation strategy here
+      # has been benchmarked as equivalent to hand-written dispatch code
+      # on Ruby 2.2. See {file:scripts/benchmark_listener_dispatch.rb} for
+      # the relevant benchmark.
+      def regenerate_dispatch_method
+        dispatch_table = instance_methods
+                             .map(&:to_s)
+                             .grep(HANDLER_METHOD_PATTERN) { |method_name|
+          event_name = $1
+          "when :#{event_name} then #{method_name}(event)"
+        }.join("\n")
+        code = %{
+          def call(event)
+            case event.name
+            #{dispatch_table}
+            # Note: following case is mainly here to keep the parser happy
+            # when there are no other cases (i.e. no handler methods defined
+            # yet).
+            when nil then fail ArgumentError, "Event cannot be nil"
+            else event_handler_missing(event)
+            end
+          end
+        }
+        class_eval code
+      rescue SyntaxError => error
+        # SyntaxErrors suck when you can't look at the syntax
+        error.message << "\n\nGenerated code:\n\n#{code}"
+        raise error
+      end
+    end
+
+    def self.included(klass)
+      klass.extend(ClassMethods)
+      klass.regenerate_dispatch_method
+    end
+
+
+    # Empty placeholder in case the client class doesn't supply a custom
+    # `#event_handler_missing`
+    def event_handler_missing(event)
+      # just a placeholder
+    end
+
+    # @!method call(event)
+    # Dispatch events to handler methods.
+    #
+    # This method is automatically [re]generated by
+    # {ClassMethods#regenerate_dispatch_method} every time a new
+    # `#on_*` method is defined.
+  end
+end

data/lib/brainguy/open_observer.rb

@@ -0,0 +1,65 @@
+module Brainguy
+  # A quick and dirty way to set up a reusable listener object. Like an
+  # OpenObject, only for event listening!
+  class OpenObserver
+    # @param handlers [Hash{Symbol => [:call]}] a Hash of event names to
+    #   callable handlers
+    # @yield [self] if a block is given
+    # @example Initializing and then adding handlers dynamically
+    #   ol = OpenObserver.new
+    #   ol.on_foo do
+    #     # ...
+    #   end
+    #   ol.on_bar do
+    #     # ...
+    #   end
+    # @example Initializing with a block
+    #   listener = OpenObserver.new do |ol|
+    #     ol.on_foo do
+    #       # ...
+    #     end
+    #     ol.on_bar do
+    #       # ...
+    #     end
+    #  end
+    # @example Initializing from a hash
+    #   listener = OpenObserver.new(foo: ->{...}, bar: ->{...})
+    def initialize(handlers = {})
+      @handlers = handlers
+      yield self if block_given?
+    end
+
+    # Dispatch the event to the appropriate handler, if one has been set.
+    # Events without handlers are ignored.
+    # @param event [Event] the event to be handled
+    def call(event)
+      if (handler = @handlers[event.name])
+        handler.call(event)
+      end
+    end
+
+    # Enable setting up event handlers dynamically using `on_*` message sends.
+    # @example
+    #   ol = OpenObserver.new
+    #   ol.on_foo do
+    #     # ...
+    #   end
+    #   ol.on_bar do
+    #     # ...
+    #   end
+    def method_missing(method_name, *_args, &block)
+      if method_name.to_s =~ /\Aon_(.+)/
+        @handlers[$1.to_sym] = block
+        self
+      else
+        super
+      end
+    end
+
+    # true if the method starts with `on_`
+    # @return [Boolean]
+    def respond_to_missing?(method_name, _include_private)
+      method_name.to_s =~ /\Aon_./
+    end
+  end
+end