dynamic_registrar 0.0.1

data/.gitignore

@@ -0,0 +1,7 @@
+.yardoc
+doc
+coverage.data
+coverage
+*~
+pkg
+.bundle

data/.rvmrc

@@ -0,0 +1,2 @@
+rvm use 1.9.2
+rvm gemset use dynamic_registrar

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,34 @@
+PATH
+  remote: .
+  specs:
+    dynamic_registrar (0.0.developer)
+      ZenTest (~> 4.4.2)
+      cover_me (~> 1.0.0.rc4)
+      parallel_tests (~> 0.4.9)
+      yard (~> 0.6.3)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ZenTest (4.4.2)
+    configatron (2.6.4)
+      yamler (>= 0.1.0)
+    cover_me (1.0.0.rc4)
+      configatron
+      hashie
+    hashie (0.4.0)
+    parallel (0.5.1)
+    parallel_tests (0.4.9)
+      parallel
+    yamler (0.1.0)
+    yard (0.6.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ZenTest (~> 4.4.2)
+  cover_me (~> 1.0.0.rc4)
+  dynamic_registrar!
+  parallel_tests (~> 0.4.9)
+  yard (~> 0.6.3)

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2010 3Crowd Technologies, Inc.
+
+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,44 @@
+The capability registrar allows modules to register versioned callbacks. Callbacks may only be
+registered once per registration namespace. If multiple callback registration is attempted a
+RegistrationConflictError will be raised.
+
+Example
+=======
+
+    master_registrar = Registrar.new
+
+    master_registrar.default_registration_namespace = :test
+
+callback procs should avoid side effects
+The register call will throw an exception if you don't pass in a second argument containing the registration namespace,
+unless the default_registration_namespace attribute is set
+
+    master_registrar.register :awesome_called do | awesome_data |
+      awesome_data
+    end
+
+    master_registrar.register :awesome_called, :something_else do | awesome_data |
+      "And now for something completely different"
+    end
+
+dispatches to all registration namespaces in undefined order for all :awesome_called registered callbacks
+returns a Hash with the registration_namespace of the callback as the key, and the value is the value returned by
+the callback function.
+
+calling
+
+    master_registrar.dispatch :awesome_called, :with_data => { :some_lol_data => :wow_cool }
+
+returns
+
+    { :test => { :some_lol_data => :wow_cool }, :something_else => "And now for something completely different" }
+
+
+dispatches to named registration namespaces return a Hash with the registration_namespace as the key, and the value is the
+value returned by the callback function, or an empty hash if the callback function is not registered
+
+    master_registrar.dispatch :awesome_called, :in_registration_namespace => :test, :with_data => { :some_lol_data => :omg_specific_cool }
+
+returns
+
+    { :test => { :some_lol_data => :omg_specific_cool } }

data/Rakefile

@@ -0,0 +1,64 @@
+require 'rake'
+require 'rake/testtask'
+require 'yard'
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+task :default => [ 'build' ]
+
+namespace :test do
+  desc 'execute tests in parallel in separate Ruby VM instances using parallel_test'
+  task :parallel do
+    test_files = FileList['test/**/test_*.rb'].sort.reverse
+    executable = 'parallel_test'
+    command = "#{executable} --type test -n #{test_files.size} -o '-I\'.:lib:test\'' #{test_files.join(' ')}"
+    abort unless system(command) # allow to chain tasks e.g. rake parallel:spec parallel:features
+  end
+
+  Rake::TestTask.new :serial do |task|
+    task.libs << "test"
+    task.test_files = FileList['test/**/test_*.rb'].sort.reverse
+    task.verbose = true
+  end
+end
+
+desc 'execute all tests both in serial and in parallel'
+task :test => [ 'test:parallel', 'test:serial' ]
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files   = ['lib/**/*.rb']
+end
+
+task 'build' => [ 'coverage:clobber', 'test', 'coverage:report', 'doc' ]
+
+namespace 'coverage' do
+
+  desc 'generate code coverage report from unit tests'
+  task :report => [ 'test:serial' ] do
+
+    puts 'Generating code coverage report...'
+
+    require 'cover_me'
+
+    CoverMe.config do |c|
+      c.project.root = File.expand_path(File.dirname(__FILE__))
+
+      c.file_pattern = /(#{CoverMe.config.project.root}\/app\/.+\.rb|#{CoverMe.config.project.root}\/lib\/.+\.rb)/ix
+    end
+
+    CoverMe.complete!
+
+    puts 'Done generating code coverage report'
+
+  end
+
+  desc 'remove code coverage report'
+  task :clobber do
+    puts 'Removing coverage report and data...'
+    rm_rf 'coverage'
+    rm_f 'coverage.data'
+    puts 'Done removing coverage report and data'
+  end
+
+end

data/dynamic_registrar.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "dynamic_registrar/version"
+
+Gem::Specification.new do |s|
+  s.name        = "dynamic_registrar"
+  s.version     = DynamicRegistrar::Version.inspect
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Justin Lynn (justinlynn)","3Crowd Technologies, Inc. (Sponsor)"]
+  s.email       = ["ops@3crowd.com"]
+  s.homepage    = "https://github.com/3Crowd/dynamic_registrar"
+  s.summary     = %q{Registration for dynamic invocation}
+  s.description = %q{Namespaced and versioned registration of callbacks for dynamic invocation by clients}
+
+  s.rubyforge_project = "dynamic_registrar"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'yard', '~> 0.6.3'
+  s.add_dependency 'cover_me', '~> 1.0.0.rc4'
+  s.add_dependency 'parallel_tests', '~> 0.4.9'
+  s.add_dependency 'ZenTest', '~> 4.4.2'
+end

data/lib/dynamic_registrar.rb

@@ -0,0 +1,6 @@
+require 'dynamic_registrar/version'
+require 'dynamic_registrar/registrar'
+
+# Provides namespaced and versioned dynamic binding by name for callbacks within an application.
+module DynamicRegistrar
+end

data/lib/dynamic_registrar/errors/registration_conflict_error.rb

@@ -0,0 +1,10 @@
+module DynamicRegistrar
+  # Encapsulates errors thrown by DynamicRegistrar
+  module Errors
+    # Defines a registration conflict error. This typically occurs when an attempt
+    # has been made to register a callback with the name of an existing callback
+    # in the scoped namespace.
+    class RegistrationConflictError < StandardError
+    end
+  end
+end

data/lib/dynamic_registrar/registrar.rb

@@ -0,0 +1,80 @@
+require 'thread'
+
+require 'dynamic_registrar/errors/registration_conflict_error'
+
+module DynamicRegistrar
+  # Controls the registration and dispatching of callbacks
+  class Registrar
+    
+    # Mutex to provide for no double or overwritten registration guarantee even in multithreaded environments
+    # @private
+    @@registration_guard = Mutex.new
+
+    # The default namespace used when calling Registrar#register! without specifying a namespace
+    attr_reader :default_registration_namespace
+    
+    # The collection of callbacks currently registered within the Registrar
+    def registered_callbacks
+      @@registration_guard.synchronize do
+        @registered_callbacks
+      end
+    end
+    
+    # Create a new DynamicRegistrar::Registrar
+    # @param [ Symbol ] default_registration_namespace The default namespace in which to register callbacks. Should not be set to nil.
+    def initialize default_registration_namespace
+      @default_registration_namespace = default_registration_namespace
+      @registered_callbacks = Hash.new
+    end
+    
+    # Register a new callback procedure. This method is thread-safe.
+    # @param [ Symbol ] name The name of the callback to register
+    # @param [ Symbol ] namespace The namespace in which to register the callback
+    def register! name, namespace = @default_registration_namespace, &callback_proc
+      @@registration_guard.synchronize do
+        raise Errors::RegistrationConflictError if registered_in_namespace? name, namespace
+        @registered_callbacks[namespace] ||= Hash.new
+        @registered_callbacks[namespace][name] = callback_proc
+      end
+    end
+    
+    # Dispatch message to given callback. All named callbacks matching the name will 
+    # be run in all namespaces in indeterminate order
+    # @param [ Symbol ] name The name of the callback 
+    # @param [ Symbol ] namespace The namespace in which the named callback should be found. Optional, if omitted then all matching named callbacks in all namespaces will be executed
+    # @return [ Hash ] A hash whose keys are the namespaces in which callbacks were executed, and whose values are the results of those executions. If empty, then no callbacks were executed.
+    def dispatch name, namespace = nil
+      responses = Hash.new
+      namespaces_to_search = namespace ? [namespace] : namespaces
+      namespaces_to_search.each do |namespace|
+        responses[namespace] ||= Hash.new
+        responses[namespace][name] = @registered_callbacks[namespace][name].call if @registered_callbacks[namespace].has_key?(name)
+      end
+      responses
+    end
+    
+    # Query if a callback of given name is registered in any namespace
+    # @param [ Symbol ] name The name of the callback to check
+    def registered? name
+      registration_map = namespaces.map do |namespace|
+        registered_in_namespace? name, namespace
+      end
+      registration_map.any?
+    end
+    
+    # Query if a callback of given name is registered in given namespace
+    # @param [ Symbol ] name The name of the callback to check
+    # @param [ Symbol ] namespace The name of the namespace in which to check
+    def registered_in_namespace? name, namespace
+      @registered_callbacks.has_key?(namespace) && @registered_callbacks[namespace].has_key?(name)
+    end
+    
+    private
+    
+    def namespaces
+      @registered_callbacks.keys
+    end
+    
+    
+  end
+end

data/lib/dynamic_registrar/version.rb

@@ -0,0 +1,22 @@
+module DynamicRegistrar
+  # Release version, set on revision control release branches as a separate commit
+  # after branching so that trunk patches can be easily backported.
+  #
+  # This is always 0.0.developer on master/mainline, refer to the HEAD commit for
+  # the version number instead.
+  module Version
+    # Incremented on breaking changes (breaks serialized data and/or removes deprecated APIs, for example)
+    MAJOR = "0"
+    # Incremented for major feature releases that do not break backwards compatibility
+    MINOR = "0"
+    # Incremented for minor fixes and updates
+    PATCH = "1"
+
+    # Converts the version number held in this module to a human readable string
+    # @return [ String ] The BinData version release
+    def self.inspect
+      [MAJOR,MINOR,PATCH].join('.')
+    end
+
+  end
+end

data/test/abstract_unit.rb

@@ -0,0 +1,2 @@
+require 'cover_me' unless ENV['TEST_ENV_NUMBER'] # don't require coverage tracer when running in parallel
+require 'minitest/autorun'

data/test/dynamic_registrar/errors/test_registration_conflict_error.rb

@@ -0,0 +1,10 @@
+require 'abstract_unit'
+require 'dynamic_registrar/errors/registration_conflict_error'
+
+class DynamicRegistrarErrorsRegistrationConflictErrorTest < MiniTest::Unit::TestCase
+  
+  def test_ensure_defines_registration_conflict_error_on_inclusion
+    refute DynamicRegistrar::Errors::RegistrationConflictError.nil?, 'Including file did not define RegistrationConflictError'
+  end
+  
+end

data/test/dynamic_registrar/test_registrar.rb

@@ -0,0 +1,112 @@
+require 'abstract_unit'
+require 'dynamic_registrar/registrar'
+
+class DynamicRegistrarRegistrarTest < MiniTest::Unit::TestCase
+
+  def test_ensure_includes_errors
+    refute DynamicRegistrar::Errors::RegistrationConflictError.nil?, 'Including file did not define RegistrationConflictError'  
+  end
+  
+  def test_has_default_registration_namespace_reader
+    assert_includes DynamicRegistrar::Registrar.instance_methods, :default_registration_namespace
+  end
+
+  def test_has_register_bang_method
+    assert_includes DynamicRegistrar::Registrar.instance_methods, 'register!'.to_sym
+  end
+  
+  def test_has_registered_callbacks_reader
+    assert_includes DynamicRegistrar::Registrar.instance_methods, :registered_callbacks
+    refute_includes DynamicRegistrar::Registrar.instance_methods, 'registered_callbacks='.to_sym
+  end
+  
+  def test_has_registration_query_method
+    assert_includes DynamicRegistrar::Registrar.instance_methods, 'registered?'.to_sym
+    assert_includes DynamicRegistrar::Registrar.instance_methods, 'registered_in_namespace?'.to_sym
+  end
+  
+  def test_has_dispatch_method
+    assert_includes DynamicRegistrar::Registrar.instance_methods, :dispatch
+  end
+  
+  def test_register_method_adds_given_parameters_to_registered_callbacks
+    registrar = DynamicRegistrar::Registrar.new :test_namespace
+    assert_empty registrar.registered_callbacks
+    registrar.register! :test_callback do
+      # empty block to match interface
+    end
+    assert registrar.registered?(:test_callback), 'Test callback was not registered in registrar even though we attempted to do so'
+    assert registrar.registered_in_namespace?(:test_callback, :test_namespace), 'Test callback in namespace test_namespace was not registered in the registrar even though we attempted to do so'
+  end
+  
+  def test_registered_method_does_not_report_registered_callback_when_no_callback_is_registered
+    registrar = DynamicRegistrar::Registrar.new(:default_namespace)
+    refute registrar.registered?(:nonexistent_callback), 'Registrar#registered? returned true for a non-registered callback in any namespace'
+    refute registrar.registered_in_namespace?(:nonexistent_callback, :nonexistant_namespace), 'Registrar#registered_in_namespace? returned true for non-registered callback in non-existant namespace'
+  end
+  
+  def test_attempting_to_double_register_in_same_namespace_results_in_exception
+    registrar = DynamicRegistrar::Registrar.new(:default)
+    registrar.register! :test_callback do # in :default namespace
+      #empty block to match interface
+    end
+    assert_raises DynamicRegistrar::Errors::RegistrationConflictError do
+      registrar.register! :test_callback do # in :default namespace
+        #empty block to match interface
+      end
+    end
+  end
+  
+  def test_dispatching_call_to_one_named_callback_dispatches_to_all_registered_namespaces
+    registrar = DynamicRegistrar::Registrar.new(:default)
+    test_callback_namespace_one_called = false
+    registrar.register! :test_callback, :test_namespace_one do
+      test_callback_namespace_one_called = true
+    end
+    test_callback_namespace_two_called = false
+    registrar.register! :test_callback, :test_namespace_two do
+      test_callback_namespace_two_called = true
+    end
+    registrar.dispatch :test_callback
+    assert test_callback_namespace_one_called, 'Dispatching to test_callback with all namespaces did not run callback for namespace_one'
+    assert test_callback_namespace_two_called, 'Dispatching to test_callback with all namespaces did not run callback for namespace_two'
+  end
+  
+  def test_dispatching_call_to_one_named_callback_in_named_namespace_dispatches_to_only_that_callback
+    registrar = DynamicRegistrar::Registrar.new(:default)
+    test_callback_namespace_one_called = false
+    registrar.register! :test_callback, :test_namespace_one do
+      test_callback_namespace_one_called = true
+    end
+    
+    test_callback_namespace_two_called = false
+    registrar.register! :test_callback, :test_namespace_two do
+      test_callback_namespace_two_called = true
+    end
+    
+    registrar.dispatch :test_callback, :test_namespace_one
+    
+    assert test_callback_namespace_one_called, 'Dispatching to test_callback with test_namespace_one namespace did not run callback for namespace_one'
+    refute test_callback_namespace_two_called, 'Dispatching to test_callback with test_namespace_one namespace called callback for namespace_two'
+  end
+  
+  def test_callbacks_return_output_in_known_format
+    registrar = DynamicRegistrar::Registrar.new(:default)
+    registrar.register! :test_callback, :test_namespace_one do
+      :aishgaoirhvoi43
+    end
+    registrar.register! :test_callback, :test_namespace_two do
+      :sdo8ivh90r8h034c
+    end
+    
+    responses = registrar.dispatch :test_callback
+    
+    assert_includes responses.keys, :test_namespace_one
+    assert_includes responses.keys, :test_namespace_two
+    assert_includes responses[:test_namespace_one].keys, :test_callback
+    assert_includes responses[:test_namespace_two].keys, :test_callback
+    assert_equal responses[:test_namespace_one][:test_callback], :aishgaoirhvoi43
+    assert_equal responses[:test_namespace_two][:test_callback], :sdo8ivh90r8h034c
+  end
+
+end

data/test/dynamic_registrar/test_version.rb

@@ -0,0 +1,22 @@
+require 'abstract_unit'
+require 'dynamic_registrar/version'
+
+class DynamicRegistrarVersionTest < MiniTest::Unit::TestCase
+  
+  def test_inspect_is_not_dynamic_registrar_version
+    refute DynamicRegistrar::Version.inspect == 'DynamicRegistrar::Version', 'DynamicRegistrar Version is DynamicRegistrar::Version, inspect is probably not defined properly'
+  end
+  
+  def test_inspect_return_value_is_not_same_as_to_s
+    refute DynamicRegistrar::Version.inspect == DynamicRegistrar::Version.to_s, 'DynamicRegistrar Version to_s equaled DynamicRegistrar Version inspect!'
+  end
+  
+  def test_to_s_returns_dynamic_registrar_version_module_name
+    assert DynamicRegistrar::Version.to_s == 'DynamicRegistrar::Version', 'DynamicRegistrar::Version.to_s did not return DynamicRegistrar::Version, someone probably adjusted it to display the version string.'
+  end
+  
+  def test_inspect_converts_version_properly
+    assert [DynamicRegistrar::Version::MAJOR, DynamicRegistrar::Version::MINOR, DynamicRegistrar::Version::PATCH].join('.') == DynamicRegistrar::Version.inspect, 'DynamicRegistrar::Version does not inspect properly'
+  end
+
+end

data/test/test_dynamic_registrar.rb

@@ -0,0 +1,15 @@
+require 'abstract_unit'
+require 'dynamic_registrar'
+
+class DynamicRegistrarTest < MiniTest::Unit::TestCase
+
+  def test_inclusion_of_version
+    refute DynamicRegistrar::Version.nil?, 'DynamicRegistrar does not include version module'
+  end
+  
+  def test_inclusion_of_registrar
+    refute DynamicRegistrar::Registrar.nil?, 'DynamicRegistrar does not include registrar module'
+  end
+  
+end
+

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification 
+name: dynamic_registrar
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Justin Lynn (justinlynn)
+- 3Crowd Technologies, Inc. (Sponsor)
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-26 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 6
+        - 3
+        version: 0.6.3
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: cover_me
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 0
+        - rc4
+        version: 1.0.0.rc4
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: parallel_tests
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 4
+        - 9
+        version: 0.4.9
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: ZenTest
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 4
+        - 4
+        - 2
+        version: 4.4.2
+  type: :runtime
+  version_requirements: *id004
+description: Namespaced and versioned registration of callbacks for dynamic invocation by clients
+email: 
+- ops@3crowd.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rvmrc
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- dynamic_registrar.gemspec
+- lib/dynamic_registrar.rb
+- lib/dynamic_registrar/errors/registration_conflict_error.rb
+- lib/dynamic_registrar/registrar.rb
+- lib/dynamic_registrar/version.rb
+- test/abstract_unit.rb
+- test/dynamic_registrar/errors/test_registration_conflict_error.rb
+- test/dynamic_registrar/test_registrar.rb
+- test/dynamic_registrar/test_version.rb
+- test/test_dynamic_registrar.rb
+has_rdoc: true
+homepage: https://github.com/3Crowd/dynamic_registrar
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: dynamic_registrar
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Registration for dynamic invocation
+test_files: 
+- test/abstract_unit.rb
+- test/dynamic_registrar/errors/test_registration_conflict_error.rb
+- test/dynamic_registrar/test_registrar.rb
+- test/dynamic_registrar/test_version.rb
+- test/test_dynamic_registrar.rb