gluer 0.0.4 → 0.0.5

data/README.md

@@ -1,6 +1,9 @@
 # Gluer
 
-A configuration reloader lib.
+A configuration reload tool.  Useful when you want to keep registration code
+next to the objects being registered, in an enviroment where another library is
+already doing code reload for you.  Gluer provides you a way to unregister and
+re-register configuration code as the code's file is reloaded.
 
 ## Installation
 
@@ -16,9 +19,140 @@ Or install it yourself as:
 
     $ gem install gluer
 
-## Usage
+## The problem this gem tries to solve
 
-TODO: Write usage instructions here
+Let's suppose you are using a library which holds registrations in a global
+registry and its usage is something along these lines:
+
+```ruby
+require 'foo_registry'
+
+class MyFoo
+  # MyFoo code...
+end
+
+FooRegistry.add_foo(MyFoo, as: 'bar') { MyBaz.init! }
+```
+
+This is simple and harmless, until you start to use some tool or lib to reload
+code for you, like ActiveSupport.  If that code is put in a file which is
+reloaded in every request in your app (as in development mode) you'll end up
+with many registrations of `MyFoo` in `FooRegistry`.  After two requests:
+
+```ruby
+FooRegistry.get_all_foos
+#=> [[MyFoo, 'bar', #<Proc:0x...>], [MyFoo, 'bar', #<Proc:0x...>]]
+```
+
+And this sometimes is not good even when developing.
+
+## A solution
+
+The way Gluer allows you to escape from this is by enclosing the registration
+code in a block:
+
+```ruby
+class MyFoo
+  # MyFoo code...
+end
+
+Gluer.setup(MyFoo) do
+  foo 'bar' { MyBaz.init! }
+end
+```
+
+That way that registration happens once even after many requests.  Well, it
+actually happens in every request, but gets properly removed before being
+added again.  So, after many requests you'll get this:
+
+```ruby
+FooRegistry.get_all_foos
+#=> [[MyFoo, 'bar', #<Proc:0x...>]]
+```
+
+But firstly, you must configure Gluer in order to make it recognize that
+`foo` call.  If you are using Rails, this goes well in an initializer file, or
+in a place where you are sure that `MyFoo`'s file was not loaded yet.  Assuming
+that the class `MyFoo`, its configuration and every other code we want Gluer to
+look at are defined in `app/` folder:
+
+```ruby
+require 'foo_registry'
+require 'gluer'
+
+# Basic configuration
+Gluer.configure do |config|
+  # The base path is the root to start searchin files which contain
+  # registration code to be reloaded.  In this example we'll lookup files only
+  # in 'app/' folder in a Rails app.
+  config.base_path = File.join(Rails.root, 'app')
+
+  # The file loader is a Proc that will be called to load each file found.
+  # In a Rails app you probably want to use ActiveSupport.
+  # Defaults to ->(f) { load(f) }.
+  config.file_loader = ->(f) { ActiveSupport::Dependencies.depend_on(f) }
+end
+
+# Registration definitions.  Here we define the `foo` method.
+Gluer.define_registration :foo do |registration|
+  registration.on_commit do |registry, context, arg, &block|
+    registry.add_foo(context, as: arg, &block)
+  end
+
+  registration.on_rollback do |registry, context, arg, &block|
+    registry.remove_foo(context, as: arg, &block)
+  end
+
+  registration.registry { FooRegistry }
+end
+
+# Put other registration definitions here.
+```
+
+The commit hook is called when the registration is to be performed.  `registry`
+is, as you may guess, is the `FooRegistry` object.  `context` is the argument
+given to `Gluer.setup`, in this case the `MyFoo` class object.  All remaining
+arguments and block are forwarded from the call to `foo` in `Gluer.setup`'s
+block.
+
+The rollback hook receives the same arguments as the commit hook.
+
+Next, add some code to do a first load.  This could go in your environment.rb
+file if you are using Rails:
+
+```ruby
+config.after_initialize do
+  Gluer.reload # initial loading
+end
+```
+
+Lastly, in a place that runs early in every request (like a ``before_filter``
+in `ApplicationController`, if you're using Rails):
+
+```ruby
+before_filter do
+  unless Rails.configuration.cache_classes
+    # If classes were cached, our initializer already has loaded everything
+    # Gluer is interested in, and we don't need the overhead of loading stuff
+    # in every request.
+    Gluer.reload
+  end
+end
+```
+
+When the file containing `MyFoo` is reloaded, the previous registration is
+rolled back, and a new registration is done.  This keeps the registry
+`FooRegistry` free of repetitions.  In fact, you must know that `Gluer.reload`
+will load that file eagerly, instead of letting your reloader lib do that for
+you lazily (even if you customize the file loader, as in the example given).
+
+## Caveats
+
+1. `FooRegistry` must provide a way to unregister.
+2. It uses `grep` to get the files with `Gluer.setup`. Probably a problem in
+   Windows. Tested only in Linux.
+3. Loads the found files eagerly. So, you should account for the side effects
+   of this.
 
 ## Contributing
 

data/lib/gluer/api.rb

@@ -5,7 +5,7 @@ module Gluer
   class << self
     def setup(context=nil, &block)
       path = block.binding.eval('__FILE__')
-      file = file_pool.get(path)
+      return unless file = file_pool.get(path)
       collect_registrations(context, block) do |registration|
         file.add_registration(registration)
       end

data/lib/gluer/configuration.rb

@@ -28,7 +28,7 @@ module Gluer
 
     def default_file_filter
       Proc.new do |base_path, magic_signature|
-        output = %x{cd '#{base_path}' && grep -IlFr '#{magic_signature}' --exclude-dir 'spec' .}
+        output = %x{cd '#{base_path}' && grep -IlFr '#{magic_signature}' --include=*.rb --exclude-dir 'spec' .}
         output.lines.map do |line|
           ::File.expand_path(line.chomp, base_path)
         end

data/lib/gluer/dsl.rb

@@ -2,9 +2,13 @@ require "gluer/registration"
 require "gluer/registration_definition"
 
 module Gluer
-  def self.define_registration(name)
+  def self.define_registration(name, &block)
     definition = RegistrationDefinition.new(name)
-    yield definition
+    if block.arity == 1
+      block.call(definition)
+    else
+      definition.instance_exec(&block)
+    end
     DSL.add_registration_definition(name, definition)
   end
 
@@ -24,6 +28,10 @@ module Gluer
         defined_registrations.fetch(name)
       end
 
+      def clear
+        @defined_registrations = nil
+      end
+
     private
 
       def defined_registrations

data/lib/gluer/file_pool.rb

@@ -9,7 +9,7 @@ module Gluer
     end
 
     def get(path)
-      files.fetch(path)
+      files[path]
     end
 
     def clear

data/lib/gluer/registration_pool.rb

@@ -1,5 +1,3 @@
-require 'gluer/ordered_set'
-
 module Gluer
   class RegistrationPool
     def initialize
@@ -15,7 +13,7 @@ module Gluer
     end
 
     def add(registration)
-      registrations.add(registration)
+      registrations.push(registration)
     end
 
     def replace(registration_pool)
@@ -23,7 +21,7 @@ module Gluer
     end
 
     def clear
-      @registrations = OrderedSet.new
+      @registrations = []
     end
 
   protected

data/lib/gluer/version.rb

@@ -1,3 +1,3 @@
 module Gluer
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/spec/gluer/dsl_spec.rb

@@ -0,0 +1,74 @@
+require 'spec_helper'
+require 'gluer/dsl'
+
+describe Gluer::DSL do
+  describe "Gluer.define_registration" do
+    let(:commit_block)   { Proc.new { |_, _| commit_called } }
+    let(:rollback_block) { Proc.new { |_, _| rollback_called } }
+    let(:registry_block) { Proc.new { registry_called } }
+
+    before do
+      Gluer.define_registration(:foo, &block)
+    end
+
+    after do
+      Gluer::DSL.clear
+    end
+
+    context "when block given doesn't accept an argument" do
+      let(:block) do
+        # Just adding these to the current scope.  The block will be
+        # instance-eval'ed.
+        commit_block   = commit_block()
+        rollback_block = rollback_block()
+        registry_block = registry_block()
+
+        lambda do
+          on_commit(&commit_block)
+          on_rollback(&rollback_block)
+          registry(&registry_block)
+        end
+      end
+
+      it "adds the registration" do
+        should_receive(:commit_called)
+        should_receive(:rollback_called)
+        should_receive(:registry_called)
+
+        reg_def = Gluer::DSL.get_registration_definition(:foo)
+
+        reg_def.commit_hook.call(stub('registry'), stub('context'))
+        reg_def.rollback_hook.call(stub('registry'), stub('context'))
+        reg_def.registry_factory.call
+      end
+    end
+
+    context "when block given accepts a single argument" do
+      let(:block) do
+        # Just adding these to the current scope.  The block will be
+        # instance-eval'ed.
+        commit_block   = commit_block()
+        rollback_block = rollback_block()
+        registry_block = registry_block()
+
+        lambda do |registration|
+          registration.on_commit(&commit_block)
+          registration.on_rollback(&rollback_block)
+          registration.registry(&registry_block)
+        end
+      end
+
+      it "adds the registration" do
+        should_receive(:commit_called)
+        should_receive(:rollback_called)
+        should_receive(:registry_called)
+
+        reg_def = Gluer::DSL.get_registration_definition(:foo)
+
+        reg_def.commit_hook.call(stub('registry'), stub('context'))
+        reg_def.rollback_hook.call(stub('registry'), stub('context'))
+        reg_def.registry_factory.call
+      end
+    end
+  end
+end

data/spec/{file_pool_spec.rb → gluer/file_pool_spec.rb}

@@ -1,3 +1,4 @@
+require 'spec_helper'
 require 'gluer/file_pool'
 require 'set'
 
@@ -35,9 +36,9 @@ describe Gluer::FilePool do
     end
 
     it "makes them available from #get" do
-      expect { subject.get('path1') }.to_not raise_error
-      expect { subject.get('path2') }.to_not raise_error
-      expect { subject.get('path3') }.to_not raise_error
+      expect(subject.get('path1')).to_not be_nil
+      expect(subject.get('path2')).to_not be_nil
+      expect(subject.get('path3')).to_not be_nil
     end
 
     context "when filtering doesn't change in next call" do
@@ -59,7 +60,7 @@ describe Gluer::FilePool do
 
       it "keeps existing files available from #get" do
         subject.update
-        expect { subject.get('path1') }.to_not raise_error
+        expect(subject.get('path1')).to_not be_nil
       end
 
       it "reloads existing files" do
@@ -95,9 +96,9 @@ describe Gluer::FilePool do
         subject.update
       end
 
-      specify "getting the unloaded file results in key error" do
+      specify "getting the unloaded file results in nil" do
         subject.update
-        expect { subject.get('path1') }.to raise_error(KeyError)
+        expect(subject.get('path1')).to be_nil
       end
 
       it "reloads existing files" do
@@ -114,7 +115,7 @@ describe Gluer::FilePool do
 
       it "makes the new file available from #get" do
         subject.update
-        expect { subject.get('path4') }.to_not raise_error
+        expect(subject.get('path4')).to_not be_nil
       end
     end
   end

data/spec/{registration_spec.rb → gluer/registration_spec.rb}

@@ -1,3 +1,4 @@
+require 'spec_helper'
 require 'gluer/registration'
 
 describe Gluer::Registration do

data/spec/integration/default_usage_spec.rb

@@ -52,8 +52,10 @@ describe "Default usage" do
       end
       registration.registry { Registry }
     end
+  end
 
-    f = File.open("temp_code.rb", "w")
+  before do
+    f = File.new("temp_code.rb", "w")
     f.write(<<-CODE)
       require 'gluer'
       Context = Object.new
@@ -86,7 +88,7 @@ describe "Default usage" do
     before do
       Gluer.reload
 
-      f = File.open("temp_code.rb", "w")
+      f = File.new("temp_code.rb", "w")
       f.write(<<-CODE)
         require 'gluer'
         Context = Object.new
@@ -115,7 +117,7 @@ describe "Default usage" do
     before do
       Gluer.reload
 
-      f = File.open("temp_code.rb", "w")
+      f = File.new("temp_code.rb", "w")
       f.write(<<-CODE)
         require 'gluer'
       CODE

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gluer
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-08 00:00:00.000000000 Z
+date: 2013-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -112,16 +112,16 @@ files:
 - lib/gluer/dsl.rb
 - lib/gluer/file.rb
 - lib/gluer/file_pool.rb
-- lib/gluer/ordered_set.rb
 - lib/gluer/registration.rb
 - lib/gluer/registration_collection.rb
 - lib/gluer/registration_definition.rb
 - lib/gluer/registration_hook.rb
 - lib/gluer/registration_pool.rb
 - lib/gluer/version.rb
-- spec/file_pool_spec.rb
+- spec/gluer/dsl_spec.rb
+- spec/gluer/file_pool_spec.rb
+- spec/gluer/registration_spec.rb
 - spec/integration/default_usage_spec.rb
-- spec/registration_spec.rb
 - spec/spec_helper.rb
 homepage: ''
 licenses:
@@ -138,7 +138,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2018170584366941344
+      hash: 2279684241105677342
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -147,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2018170584366941344
+      hash: 2279684241105677342
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25
@@ -155,7 +155,8 @@ signing_key:
 specification_version: 3
 summary: Configuration reloader
 test_files:
-- spec/file_pool_spec.rb
+- spec/gluer/dsl_spec.rb
+- spec/gluer/file_pool_spec.rb
+- spec/gluer/registration_spec.rb
 - spec/integration/default_usage_spec.rb
-- spec/registration_spec.rb
 - spec/spec_helper.rb

data/lib/gluer/ordered_set.rb

@@ -1,23 +0,0 @@
-module Gluer
-  class OrderedSet
-    include Enumerable
-
-    def initialize(initial=[])
-      @collection = initial
-    end
-
-    def each
-      @collection.each { |item| yield(item) }
-    end
-
-    def add(new)
-      @collection.delete_if { |existing| existing == new }
-      @collection << new
-    end
-
-    def -(other)
-      raise ArgumentError unless other.is_a?(OrderedSet)
-      self.class.new(@collection - other.instance_eval { @collection })
-    end
-  end
-end