octiron 0.1.0

data/lib/octiron.rb

@@ -0,0 +1,11 @@
+# coding: utf-8
+#
+# octiron
+# https://github.com/jfinkhaeuser/octiron
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other octiron contributors.
+# All rights reserved.
+#
+
+require 'octiron/version'
+require 'octiron/world'

data/lib/octiron/events/bus.rb

@@ -0,0 +1,161 @@
+# coding: utf-8
+#
+# octiron
+# https://github.com/jfinkhaeuser/octiron
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other octiron contributors.
+# All rights reserved.
+#
+
+require 'octiron/support/identifiers'
+
+require 'collapsium/recursive_sort'
+require 'collapsium/prototype_match'
+
+module Octiron::Events
+
+  ##
+  # Implements and in-process pub-sub events broadcaster allowing multiple
+  # observers to subscribe to different events.
+  class Bus
+    # @return (String) the default namespace to search for events
+    attr_reader :default_namespace
+
+    ##
+    # @param default_namespace (Symbol) The default namespace to look in for
+    #     Event classes.
+    def initialize(default_namespace = ::Octiron::Events)
+      @default_namespace = default_namespace.to_s
+      @handlers = {}
+    end
+
+    ##
+    # Subscribe an event handler to an event.
+    # @param event_id (Class, String, other) A class or String naming an event
+    #     class.
+    # @param handler_object (Object) Handler object that must implement a
+    #     `#call` method accepting an instance of the event class provided in
+    #     the first parameter. If nil, a block needs to be provided.
+    # @param handler_proc (Proc) Handler block that accepts an instance of the
+    #     event class provided in the first parameter. If nil, a handler object
+    #     must be provided.
+    # @return The class represented by the event_id, as a String name.
+    def subscribe(event_id, handler_object = nil, &handler_proc)
+      handler = resolve_handler(handler_object, &handler_proc)
+      event_name = identify(event_id)
+
+      handlers_for(event_name, true) << handler
+
+      return event_name
+    end
+    alias register subscribe
+
+    ##
+    # Unsubscribe an event handler from an event.
+    # @param event_id (Class, String, other) A class or String naming an event
+    #     class.
+    # @param handler_object (Object) Handler object that must implement a
+    #     `#call` method accepting an instance of the event class provided in
+    #     the first parameter. If nil, a block needs to be provided.
+    # @param handler_proc (Proc) Handler block that accepts an instance of the
+    #     event class provided in the first parameter. If nil, a handler object
+    #     must be provided.
+    # @return The class represented by the event_id, as a String name.
+    def unsubscribe(event_id, handler_object = nil, &handler_proc)
+      handler = resolve_handler(handler_object, &handler_proc)
+      event_name = identify(event_id)
+
+      handlers_for(event_name, true).delete(handler)
+
+      return event_name
+    end
+
+    ##
+    # Broadcast an event. This is an instance of a class provided to #subscribe
+    # previously.
+    # @param event (Object) the event to publish
+    def publish(event)
+      event_name = event
+      if not event.is_a?(Hash)
+        event_name = event.class.to_s
+      end
+      handlers_for(event_name, false).each do |handler|
+        handler.call(event)
+      end
+    end
+    alias broadcast publish
+    alias notify publish
+
+    private
+
+    # The first parameters is the event class or event name. The second parameter
+    # is whether this is for write or read access. We don't want to pollute
+    # @handlers with data from the #publish call.
+    def handlers_for(name, write)
+      # Use prototype matching for Hash names
+      if name.is_a?(Hash)
+        name.extend(::Collapsium::PrototypeMatch)
+
+        # The prototype hash logic is a little complex. A hash event can match
+        # multiple prototypes, e.g. { a: 42 } should match { a: nil } as well as
+        # { a: 42 }.
+        # When writing, we want to be as precise as possible and find the best
+        # match. When reading, we want to merge all matches, ideally.
+        if write
+          best_score = -1
+          best_proto = nil
+
+          # Find the best matching prototype
+          @handlers.keys.each do |proto|
+            score = name.prototype_match_score(proto)
+            if score > best_score
+              best_score = score
+              best_proto = proto
+            end
+          end
+
+          if not best_proto.nil?
+            return @handlers[best_proto]
+          end
+        else
+          merged = []
+
+          @handlers.keys.each do |proto|
+            if name.prototype_match(proto)
+              merged += @handlers[proto]
+            end
+          end
+
+          if not merged.empty?
+            return merged
+          end
+        end
+
+        # No prototype matches. That means if write is true, we need to treat
+        # name as a new prototype to regiser. Otherwise, we need to return an
+        # empty list. That happens to be the same logic as for the simple key
+        # below.
+      end
+
+      # If we're in write access, make sure to store an empty list as well as
+      # returning one (if necessary).
+      if write
+        @handlers[name] ||= []
+      end
+
+      # In read access, want to either return an empty list, or the registered
+      # handlers, but not ovewrite the registered handlers.
+      return @handlers[name] || []
+    end
+
+    def resolve_handler(handler_object = nil, &handler_proc)
+      handler = handler_proc || handler_object
+      if not handler
+        raise ArgumentError, "Please pass either an object or a handler block"
+      end
+      return handler
+    end
+
+    include ::Octiron::Support::Identifiers
+  end # class Bus
+end # module Octiron::Events

data/lib/octiron/support/camel_case.rb

@@ -0,0 +1,27 @@
+# coding: utf-8
+#
+# octiron
+# https://github.com/jfinkhaeuser/octiron
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other octiron contributors.
+# All rights reserved.
+#
+
+module Octiron::Support
+  ##
+  # @see CamelCase::camel_case
+  module CamelCase
+
+    ##
+    # Takes an underscored name and turns it into a CamelCase String
+    # @param underscored_name (String, Symbol) the underscored name to turn
+    #     into camel case.
+    # @return (String) CamelCased version of the underscored_name
+    def camel_case(underscored_name)
+      return underscored_name.to_s.split("_").map do |word|
+        word.upcase[0] + word[1..-1]
+      end.join
+    end
+
+  end # module CamelCase
+end # module Octiron::Support

data/lib/octiron/support/constantize.rb

@@ -0,0 +1,43 @@
+# coding: utf-8
+#
+# octiron
+# https://github.com/jfinkhaeuser/octiron
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other octiron contributors.
+# All rights reserved.
+#
+
+module Octiron::Support
+  ##
+  # @see Constantize::constantize
+  module Constantize
+
+    ##
+    # Takes a String containing a constant name, and returns the canonical path
+    # of the constant (i.e. where it's defined, even if it's accessed
+    # differently.). If the constant does not exist, a NameError is thrown.
+    # @param constant_name (String) the constant name
+    # @return (Object) the actual named constant.
+    def constantize(constant_name)
+      names = constant_name.split('::')
+
+      # Trigger a built-in NameError exception including the ill-formed
+      # constant in the message.
+      if names.empty?
+        Object.const_get(constant_name, false)
+      end
+
+      # Remove the first blank element in case of '::ClassName' notation.
+      if names.size > 1 && names.first.empty?
+        names.shift
+      end
+
+      # Note: this would be much more complex in Ruby < 1.9.3, so yay for not
+      # bothering to support these!
+      return names.inject(Object) do |constant, name|
+        next constant.const_get(name)
+      end
+    end
+
+  end # module Constantize
+end # module Octiron::Support

data/lib/octiron/support/identifiers.rb

@@ -0,0 +1,45 @@
+# coding: utf-8
+#
+# octiron
+# https://github.com/jfinkhaeuser/octiron
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other octiron contributors.
+# All rights reserved.
+#
+
+require_relative 'camel_case'
+require_relative 'constantize'
+
+module Octiron::Support
+  ##
+  # @see Identifiers::identify
+  module Identifiers
+    include ::Octiron::Support::CamelCase
+    include ::Octiron::Support::Constantize
+
+    ##
+    # This function "identifies" an object, i.e. returns a unique ID according
+    # to the octiron logic. That means that:
+    # - For classes, a stringified version is returned
+    # - For hashes, the hash itself is returned
+    # - Strings are interpreted as constant names, and are returned fully
+    #   qualified.
+    # - Everything else is considered to be a constant name in the default
+    #   namespace. This requires access to a @default_namespace variable in
+    #   the including class.
+    def identify(name)
+      case name
+      when Class
+        return name.to_s
+      when Hash
+        return name
+      when String
+        return constantize(name).to_s
+      when nil
+        raise NameError, "Can't identify 'nil'!"
+      else
+        return constantize("#{@default_namespace}::#{camel_case(name)}").to_s
+      end
+    end
+  end # module Identifiers
+end # module Octiron::Support

data/lib/octiron/transmogrifiers/registry.rb

@@ -0,0 +1,201 @@
+# coding: utf-8
+#
+# octiron
+# https://github.com/jfinkhaeuser/octiron
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other octiron contributors.
+# All rights reserved.
+#
+
+require 'rgl/adjacency'
+require 'rgl/dijkstra'
+
+require 'octiron/support/identifiers'
+
+# require 'collapsium/recursive_sort'
+require 'collapsium/prototype_match'
+
+module Octiron::Transmogrifiers
+
+  ##
+  # Registers transmogrifiers between one (event) class and another.
+  #
+  # A transmogrifier is an object with a call method or a block that accepts
+  # an instance of one (event) class and produces an instance of another
+  # (event) class.
+  #
+  # The registry also exposes a #transmogrify function which uses any
+  # registered transmogrifier, or raises an error if there is no
+  # transmogrification possible.
+  #
+  # One piece of magic makes this particularly powerful: the registry creates
+  # a graph of how to transmogrify an object to another by chaining
+  # transmogrifiers. That is, if there is a transmogrifier that turns A into B,
+  # and one that turns B into C, then by chaining both the registry can also
+  # turn A into C directly. (This is done via the 'rgl' gem).
+  class Registry
+    # @return (String) the default namespace to search for transmogrifiers
+    attr_reader :default_namespace
+
+    ##
+    # @param default_namespace (Symbol) The default namespace to look in for
+    #     Transmogrifier classes.
+    def initialize(default_namespace = ::Octiron::Transmogrifiers)
+      @default_namespace = default_namespace.to_s
+      @graph = RGL::DirectedAdjacencyGraph.new
+      @visitor = RGL::DijkstraVisitor.new(@graph)
+      @map_data = {}
+      @map = nil
+      @transmogrifiers = {}
+    end
+
+    ##
+    # Register transmogrifier
+    #
+    # @param from (Class, String, other) A class or String nameing a
+    #     transmogrifier source. With prototype Hash matching, this would be
+    #     a prototype.
+    # @param to (Class, String, other) Transmogrifier target.
+    # @param overwrite (Boolean) The registry can only hold one transmogrifier
+    #     per from -> to pair. If overwrite is true, registering a
+    #     transmogrifier where one already exists overwrites the old one,
+    #     otherwise an exception is raised.
+    # @param transmogrifier_object (Object) Transmogrifier object that must
+    #     implement a `#call` method accepting an instance of the event class
+    #     provided in the first parameter. If nil, a block needs to be provided.
+    # @param transmogrifier_proc (Proc) Transmogrifier block that accepts an
+    #     instance of the event class provided in the first parameter. If nil, a
+    #     transmogrifier object must be provided.
+    def register(from, to, overwrite = false, transmogrifier_object = nil,
+                 &transmogrifier_proc)
+      transmogrifier = transmogrifier_proc || transmogrifier_object
+      if not transmogrifier
+        raise ArgumentError, "Please pass either an object or a transmogrifier "\
+            "block"
+      end
+
+      # Convert to canonical names
+      from_name = identify(from)
+      to_name = identify(to)
+      key = [from_name, to_name]
+
+      # We treat the graph as authoritative for what transmogrifiers exist.
+      if @graph.has_edge?(from_name, to_name)
+        if not overwrite
+          raise ArgumentError, "Registry already knows a transmogrifier for "\
+              "#{key}, aborting!"
+        end
+      end
+
+      # Add edges and map data for the shortest path search. We treat all paths
+      # as equally weighted.
+      @graph.add_edge(from_name, to_name)
+      @map_data[key] = 1
+      @map = RGL::EdgePropertiesMap.new(@map_data, true)
+
+      # Finally, register transmogrifier
+      @transmogrifiers[key] = transmogrifier
+    end
+
+    ##
+    # Deregister transmogrifier
+    #
+    # @param from (Class, String, other) A class or String nameing a
+    #     transmogrifier source. With prototype Hash matching, this would be
+    #     a prototype.
+    # @param to (Class, String, other) Transmogrifier target.
+    def deregister(from, to)
+      # Convert to canonical names
+      from_name = identify(from)
+      to_name = identify(to)
+      key = [from_name, to_name]
+
+      # Graph, map data and transmogrifiers need to be modified
+      @graph.remove_edge(from_name, to_name)
+      @map_data.delete(key)
+      @map = RGL::EdgePropertiesMap.new(@map_data, true)
+
+      @transmogrifiers.delete(key)
+    end
+
+    alias unregister deregister
+
+    ##
+    # Transmogrify an object of one class into another class.
+    def transmogrify(from, to)
+      # Get lookup keys
+      from_name = from.class.to_s
+      if from.is_a?(Hash)
+        # Finding the correct from_name is tricky, because from is not a
+        # prototype, but the graph and all intermediate
+        from_name = best_matching_hash_prototype(from)
+      end
+      to_name = identify(to)
+
+      # We'll ask the graph for the shortest path. If there is none, we can't
+      # transmogrify. (Note: the @map changes with each registration/
+      # deregistration, so we instanciate the algorithm here).
+      algo = RGL::DijkstraAlgorithm.new(@graph, @map, @visitor)
+      path = algo.shortest_path(from_name, to_name)
+
+      if path.nil?
+        raise ArgumentError, "No transmogrifiers for #{[from_name, to_name]} "\
+            "found, aborting!"
+      end
+
+      # Transmogrify for each part of the path
+      input = from
+      result = nil
+      path.inject do |step_from, step_to|
+        # Call transmogrifier
+        key = [step_from, step_to]
+        result = @transmogrifiers[key].call(input)
+
+        # Verify result
+        if step_to.is_a?(Hash)
+          result.extend(::Collapsium::PrototypeMatch)
+          if not result.prototype_match(step_to)
+            raise "Transmogrifier returned Hash that did not match prototype "\
+                  "#{step_to}, aborting!"
+          end
+        elsif result.class.to_s != step_to
+          raise "Transmogrifier returned result of invalid class "\
+              "#{result.class}, aborting!"
+        end
+
+        # Result is input for the next transmogrifier in the chain
+        input = result
+
+        # Make step_to the next step_from
+        next step_to
+      end
+      return result
+    end
+
+    private
+
+    include ::Octiron::Support::Identifiers
+
+    def best_matching_hash_prototype(value)
+      value.extend(::Collapsium::PrototypeMatch)
+      best_score = -1
+      best_proto = nil
+
+      @transmogrifiers.each do |key, _|
+        proto = key[0]
+
+        if not proto.is_a?(Hash)
+          next
+        end
+
+        score = value.prototype_match_score(proto)
+        if score > best_score
+          best_score = score
+          best_proto = proto
+        end
+      end
+
+      return best_proto
+    end
+  end # class Registry
+end # module Octiron::Transmogrifiers