poro 0.1.2 → 0.1.3

data/README.rdoc

@@ -160,14 +160,22 @@ mailto:jeff@paploo.net
 
 = Version History
 
-[0.1.2 - 2010-Sep-30] Feature Additions
+[0.1.3 - 2010-Oct-21] Callbacks and MongoContext Bug Fixes.
+                      * Added callbacks for common events.
+                      * MongoContext: You can actually remove records now.
+                      * MongoContext: Bignum encodes instead of throwing errors.
+                      * MongoContext: Made recognition of true/false/nil class
+                        during encoding more robust.
+[0.1.2 - 2010-Sep-30] Feature Additions.
                       * Added a module namespace factory.
-                      * HashContext: Find one is faster when the conditions restrict on the primary key.
+                      * HashContext: Find one is faster when the conditions
+                        restrict on the primary key.
                       * Many HashContext bugs fixed.
 [0.1.1 - 2010-Sep-24] Minor Additions and Bug Fixes.
                       * MongoContext now can optionally encode Symbols as hashes
                         or just leave them as strings.
-                      * MongoContext can have conversion to BSON::ObjectId turned off.
+                      * MongoContext can have conversion to BSON::ObjectId
+                        turned off.
                       * MongoContext can save Sets in various formats.
                       * MongoContext handles namespaced models better.
                       * Context doesn't error when trying to find by id.
@@ -176,7 +184,8 @@ mailto:jeff@paploo.net
                         to big changes as it is used in the real world.
                       * Only supports MongoDB and Hash Contexts.
                       * No performance testing and optimization yet done.
-                      * The documentation is rough around the edges and may contain errors.
+                      * The documentation is rough around the edges and may
+                        contain errors.
                       * Spec tests are incomplete.
 
 = TODO List
@@ -184,26 +193,17 @@ mailto:jeff@paploo.net
 The following are the primary TODO items, roughly in priority order:
 
 * YAML Connection Configuration:
-  * Make a Util module that is able to use a rails-compatible YAML
+  * Make a Util module that is able to use a rails-style YAML
     file--given by path--to get the elements needed for configuration of a
     SingleStore factory.
   * Modify SingleStore to use this file for configuration when appropriate.
 * Modelify: Break into modules for each piece of functionality.
-* Modelify: Add callback functionality to Modelify (e.g. before/after save, after initialize).
-  * Add the callbacks to the Context first.
-* Mongo Context: Add option to encode Sets as one of:
-  * A Set with the raw internal Hash.
-  * A Set with the internal Hash as an Array.
-  * An Array (which will have to be manually turned back into a Set).
 * Specs: Add specs for Context Find methods.
-  * Check that private methods are private.  (Should do on subclasses too.)
-  * Check that the two main find methods pass through to the correct underlying
-    methods or throw an argument when necessary. 
 * Specs: Add spec tests for Mongo Context.
 * Mongo Context: Split into modules in separate files.
 * Context: Split out modules into files.
 * Contexts: Add SQL Context.
-* Ruby: Verify support for ruby 1.9.x.
+* Ruby: Verify support for ruby 1.9.0 and 1.9.1.
 * Ruby: Evaluate adding support for ruby 1.8.6 and 1.8.7.
 
 = License
@@ -240,5 +240,5 @@ GPL compatible "New BSD License", given below:
 
 Poro::Util::Inflector and its submodules are adapted from ActiveSupport,
 and its source is redistributed under the MIT license it was originally
-distributed under.  Thetext of this copyright notice is supplied
+distributed under.  The text of this copyright notice is supplied
 in <tt>poro/util/inflector.rb</tt>.

data/lib/poro/context.rb

@@ -111,14 +111,16 @@ module Poro
     # Fetches the object from the store with the given id, or returns nil
     # if there are none matching.
     def fetch(id)
-      return convert_to_plain_object( clean_id(nil) )
+      obj = convert_to_plain_object( clean_id(nil) )
+      callback_event(:after_fetch, obj)
+      return obj
     end
     
     # Saves the given object to the persistent store using this context.
     #
     # Subclasses do not need to call super, but should follow the given rules:
     #
-    # Returns self so that calls may be daisy chained.
+    # Returns the saved object.
     #
     # If the object has never been saved, it should be inserted and given
     # an id.  If the object has been added before, the id is used to update
@@ -126,7 +128,9 @@ module Poro
     #
     # Raises an Error if save fails.
     def save(obj)
+      callback_event(:before_save, obj)
       obj.id = obj.object_id if obj.respond_to?(:id) && obj.id.nil? && obj.respond_to?(:id=)
+      callback_event(:after_save, obj)
       return obj
     end
     
@@ -134,13 +138,15 @@ module Poro
     #
     # Subclasses do not need to call super, but should follow the given rules:
     #
-    # Returns self so that calls may be daisy chained.
+    # Returns the removed object.
     #
     # If the object is successfully removed, the id is set to nil.
     #
     # Raises an Error is the remove fails.
     def remove(obj)
+      callback_event(:before_remove, obj)
       obj.id = nil if obj.respond_to?(:id=)
+      callback_event(:after_remove, obj)
       return obj
     end
     
@@ -157,7 +163,10 @@ module Poro
     # Any root object returned from a "find" in the data store needs to be
     # able to be converted
     def convert_to_plain_object(data, state_info={})
-      return data
+      transformed_data = callback_transform(:before_convert_to_plain_object, data)
+      obj = transformed_data
+      callback_event(:after_convert_to_plain_object, obj)
+      return obj
     end
     
     # Convert a plain ol' ruby object into the data store data format this
@@ -173,7 +182,10 @@ module Poro
     # Any root object returned from a "find" in the data store needs to be
     # able to be converted
     def convert_to_data(obj, state_info={})
-      return obj
+      transformed_obj = callback_transform(:before_convert_to_data, obj)
+      data = transformed_obj
+      callback_event(:after_convert_to_data, data)
+      return data
     end
     
     private 
@@ -457,8 +469,135 @@ module Poro
   end
 end
 
+module Poro
+  class Context
+    # A mixin to support callbacks.  There are three kinds of callbacks:
+    # [Events] Events are callbacks that are passed a handle to the object when
+    #          a particular kind of event has occured.  These may destructively
+    #          edit objects.
+    # [Transform] Transforms are callbacks where each handler is passed the
+    #             result of the previous transform, and may return any value.
+    #             The issuing object then uses the final value in some way.
+    # [Filters] Calls each callback in sequence, pasing in the issuing object.
+    #           Terminates execution on the first callback that is "false" (as
+    #           determined by an if statement), or when there are no callbacks
+    #           left. Gives the issuing object the result of the last block.
+    #
+    # Contexts issue the following event callbacks:
+    # [:before_save] Called before save; passes the object that is going to be saved.
+    # [:after_save] Called after save; passes the object that was saved.
+    # [:before_remove] Called before removing an object from persistent storage; passes the object that will be removed.
+    # [:after_remove] Called after removing an object from persistent storage; passes the object that was removed.
+    # [:after_fech] Called after an object is fetched from the persistent store; passes the object that was fetched.
+    # [:after_convert_to_plain_object] Called after an object is converted to a plain object from the persistent store but before it is used; passes the plain object.
+    # [:after_convert_to_data] Called after an object is converted to the persistent store's data structure but before it is used; passes the data store's data structure.
+    #
+    # Contexts issue the following transform callbacks:
+    #
+    # [:before_convert_to_plain_object] Called just before a context converts
+    #                                   persistent store data to a plain ruby object;
+    #                                   is passed the persistent store data object;
+    #                                   the result is what is converted.
+    #                                   
+    #                                   In most cases it is better to use the
+    #                                   +after_convert_to_plain_object+ callback event.
+    # [:before_convert_to_data] Called just before a context converts
+    #                           a plain ruby object to persistent store data;
+    #                           is passed the plain ruby object;
+    #                           the result is what is converted.
+    #                           
+    #                           In most cases it is better to use the
+    #                           +before_convert_to_plain_object+ callback event.
+    module CallbackMethods
+      
+      # Return the raw array of callbacks.  This can be manipulated if more
+      # straightforward methods don't do the trick, but usually this is
+      # a consequence of trying to solve the problem wrong.
+      #
+      # While usually a kind of Proc, callbacks may be any object that responds
+      # to call.
+      def callbacks(event)
+        @event_callbacks ||= {}
+        key = event.to_sym
+        @event_callbacks[key] ||= []
+        return @event_callbacks[key]
+      end
+      
+      # Register a callback for a given event.
+      def register_callback(event, &block)
+        callbacks(event) << block
+      end
+      
+      # Clear all callbacks for a given event.
+      #
+      # This can be dangerous because
+      def clear_callbacks(event)
+        callbacks(event).clear
+      end
+      
+      private
+      
+      # Fires the callbacks for the given event; returns the object supplied
+      # for calling.
+      #
+      # * Each registered callback is given the object issued with the call.
+      # * Depending on your uses, the callback may be destructive of the passed object.
+      # * The callback returns are ignored.
+      #
+      # Registration of no callbacks results in no callbacks being called.
+      def callback_event(event, obj)
+        callbacks(event).each {|callback| callback.call(obj)}
+        return obj
+      end
+      
+      # Transforms an object through a callback chain; returns the transformed
+      # object.
+      #
+      # * Each registered callback is given the result of the previous callback.
+      # * Callbacks may return the original object (modified or unmodified), a
+      #   copy of the original object (modified or unmodified), or an entirely
+      #   new object, depending on how the result is used.
+      # * The callback return is passed into the next callback, with the last
+      #   return being called to the initial caller.
+      #
+      # Registration of no callbacks results in the return of the original object.
+      def callback_transform(event, initial_obj)
+        return callbacks(event).inject(initial_obj) {|obj, callback| callback.call(obj)}
+      end
+      
+      # Executes callbacks until the last true-valued filter; returns the last
+      # true valued object.
+      #
+      # By convention, filter events should end in a question mark to make it
+      # clear that the true/false value is important.
+      #
+      # * Each registered callback is given the original object, making this
+      #   behave more like an event than a transform.
+      # * Filters are expected to be non-destructive, as they are used to
+      #   determine if an action should take place, rather than to take an
+      #   action.
+      # * If the return of a callback is false-values (as determined by an +if+
+      #   expression), then the filter chain is halted and the value is returned;
+      #   otherwise, the value returned from the last callback is returned.
+      #
+      # Registration of no callbacks results in the return of the +default_value+
+      # argument, which--if not provided--is set to true.
+      def callback_filter?(event, obj, default_result=true)
+        result = default_result
+        callbacks(event).each do |callback|
+          result = callback.call(obj)
+          break unless result
+        end
+        return result
+      end
+      
+    end
+  end
+end
+
 module Poro
   class Context
     include FindMethods
+    include CallbackMethods
   end
 end

data/lib/poro/contexts/hash_context.rb

@@ -12,11 +12,15 @@ module Poro
       end
       
       def fetch(id)
-        return convert_to_plain_object( data_store[clean_id(id)] )
+        obj = convert_to_plain_object( data_store[clean_id(id)] )
+        callback_event(:after_fetch, obj)
+        return obj
       end
       
       # Save the object in the underlying hash, using the object id as the key.
       def save(obj)
+        callback_event(:before_save, obj)
+        
         pk_id = self.primary_key_value(obj)
         if(pk_id.nil?)
           pk_id = obj.object_id
@@ -24,25 +28,37 @@ module Poro
         end
         
         data_store[pk_id] = convert_to_data(obj)
-        return self
+        
+        callback_event(:after_save, obj)
+        return obj
       end
       
       # Remove the object from the underlying hash.
       def remove(obj)
+        callback_event(:before_remove, obj)
+        
         pk_id = self.primary_key_value(obj)
         if( pk_id != nil )
           data_store.delete(pk_id)
           self.set_primary_key_value(obj, nil)
         end
-        return self
+        
+        callback_event(:after_remove, obj)
+        return obj
       end
       
       def convert_to_plain_object(data)
-        return data
+        transformed_data = callback_transform(:before_convert_to_plain_object, data)
+        obj = transformed_data
+        callback_event(:after_convert_to_plain_object, obj)
+        return obj
       end
       
       def convert_to_data(obj)
-        return obj
+        transformed_obj = callback_transform(:before_convert_to_data, obj)
+        data = transformed_obj
+        callback_event(:after_convert_to_data, data)
+        return data
       end
       
       private

data/lib/poro/contexts/mongo_context.rb

@@ -91,29 +91,44 @@ module Poro
       
       def fetch(id)
         data = data_store.find_one( clean_id(id) )
-        return convert_to_plain_object(data)
+        obj convert_to_plain_object(data)
+        callback_event(:before_fetch, obj)
+        return obj
       end
       
       def save(obj)
+        callback_event(:before_save, obj)
         data = convert_to_data(obj)
         data_store.save(data)
         set_primary_key_value(obj, (data['_id'] || data[:_id])) # The pk generator uses a symbol, while everything else uses a string!
+        callback_event(:after_save, obj)
         return obj
       end
       
       def remove(obj)
+        callback_event(:before_remove, obj)
+        data_store.remove( {'_id' => primary_key_value(obj)} )
+        callback_event(:after_remove, obj)
         return obj
       end
       
       def convert_to_plain_object(data, state_info={})
+        transformed_data = callback_transform(:before_convert_to_plain_object, data)
+        
         # If it is a root record, and it has no class name, assume this context's class name.
-        data['_class_name'] = self.klass if( data && data.kind_of?(Hash) && !state_info[:embedded] )
-        obj = route_decode(data, state_info)
+        transformed_data['_class_name'] = self.klass if( transformed_data && transformed_data.kind_of?(Hash) && !state_info[:embedded] )
+        obj = route_decode(transformed_data, state_info)
+        
+        callback_event(:after_convert_to_plain_object, obj)
         return obj
       end
       
       def convert_to_data(obj, state_info={})
-        data = route_encode(obj, state_info)
+        transformed_obj = callback_transform(:before_convert_to_data, obj)
+        
+        data = route_encode(transformed_obj, state_info)
+        
+        callback_event(:after_convert_to_data, data)
         return data
       end
       
@@ -150,9 +165,9 @@ module Poro
           obj.kind_of?(String) ||
           obj.kind_of?(Time) ||
           (!self.encode_symbols && obj.kind_of?(Symbol)) ||
-          obj==true ||
-          obj==false ||
-          obj.nil? ||
+          obj.kind_of?(TrueClass) ||
+          obj.kind_of?(FalseClass) ||
+          obj.kind_of?(NilClass) ||
           obj.kind_of?(BSON::ObjectId) ||
           obj.kind_of?(BSON::DBRef)
         )
@@ -205,6 +220,8 @@ module Poro
           return encode_array(obj)
         elsif( obj.kind_of?(Class) )
           return encode_class(obj)
+        elsif( obj.kind_of?(Bignum) )
+          return encode_bigint(obj)
         elsif( obj.kind_of?(Set) )
           return encode_set(obj)
         elsif( self.encode_symbols && obj.kind_of?(Symbol) )
@@ -243,6 +260,11 @@ module Poro
         return {'_class_name' => 'Symbol', 'value' => sym.to_s}
       end
       
+      # Encodes a big-int, which is too big to be natively encoded in BSON.
+      def encode_bigint(bigint)
+        return {'_class_name' => 'Bignum', 'value' => bigint.to_s}
+      end
+      
       # Encodes a Set as either :raw, :embedded_array, :array.
       def encode_set(set)
         method = @set_encoding_method
@@ -344,6 +366,8 @@ module Poro
           return decode_class(data)
         elsif( class_name == 'Symbol' )
           return decode_symbol(data)
+        elsif( class_name == 'Bignum' )
+          return decode_bigint(data)
         elsif( class_name == 'Set' )
           return decode_set(data)
         elsif( class_name == self.klass.to_s )
@@ -384,6 +408,11 @@ module Poro
         end
       end
       
+      # Decode an encoded bigint.
+      def decode_bigint(bigint_data)
+        return bigint_data['value'].to_i
+      end
+      
       # Decode the set depending on if it was encoded as an array or as a raw
       # object.
       def decode_set(set_data)

data/lib/poro/version.rb

@@ -3,5 +3,5 @@
 # existing plain ol' ruby objects as little as possible.  For more information
 # see README.rdoc.
 module Poro
-  VERSION = '0.1.2'
+  VERSION = '0.1.3'
 end

data/spec/context_spec.rb

@@ -107,4 +107,129 @@ describe "Context" do
     Poro::Context.fetch(@klass_one.new).should == "#{@klass_one}, #{x}"
   end
   
+  describe 'Callbakcs' do
+    
+    before(:each) do
+      @context = @context_klass.new(@klass_one)
+    end
+    
+    it 'should allow direct inspection of callbacks' do
+      bs_callbacks = @context.callbacks(:before_save)
+      bs_callbacks.should be_kind_of(Array)
+      
+      as_callbacks = @context.callbacks(:after_save)
+      as_callbacks.should be_kind_of(Array)
+      
+      as_callbacks.object_id.should_not == bs_callbacks.object_id
+      @context.callbacks(:before_save).object_id.should == bs_callbacks.object_id
+    end
+    
+    it 'should allow callback registration' do
+      @context.callbacks(:before_save).should be_empty
+      @context.register_callback(:before_save) {|obj| obj}
+      @context.callbacks(:before_save).length.should == 1
+      
+      @context.register_callback(:after_save) {|obj| obj}
+      @context.callbacks(:after_save).length.should == 1
+      
+      @context.callbacks(:before_save).length.should == 1
+    end
+    
+    it 'should clear callbacks' do
+      @context.register_callback(:before_save) {|obj| obj}
+      @context.callbacks(:before_save).length.should == 1
+      @context.clear_callbacks(:before_save)
+      @context.callbacks(:before_save).should be_empty
+    end
+    
+    it 'should have private firing methods' do
+      @context.private_methods.should include(:callback_event)
+      @context.private_methods.should include(:callback_transform)
+      @context.private_methods.should include(:callback_filter?)
+    end
+    
+    it 'should call event callbacks' do
+      @context.register_callback(:before_save) {|obj| obj[:foo] = 'bar'}
+      @context.register_callback(:before_save) {|obj| obj[:alpha] = 'beta'}
+      @context.register_callback(:after_save) {|obj| obj[:p] = 'q'}
+      
+      some_object = {:foo => 'untouched', :value => 12345}
+      result = @context.send(:callback_event, :before_save, some_object)
+      result.object_id.should == some_object.object_id
+      some_object.should == {:foo => 'bar', :value => 12345, :alpha => 'beta'}
+    end
+    
+    it 'should handle transform callbacks' do
+      @context.register_callback(:before_save) {|obj| obj.merge(:foo => 'bar')}
+      @context.register_callback(:before_save) {|obj| obj.merge(:alpha => 'beta').to_a}
+      @context.register_callback(:after_save) {|obj| 'q'}
+      
+      some_object = {:foo => 'untouched', :value => 12345}
+      result = @context.send(:callback_transform, :before_save, some_object)
+      result.should == [[:foo, 'bar'], [:value, 12345], [:alpha, 'beta']]
+      some_object.should == {:foo => 'untouched', :value => 12345}
+    end
+    
+    it 'should handle no transform callbacks' do
+      @context.callbacks(:before_save).should be_empty
+      
+      some_object = {:foo => 'untouched', :value => 12345}
+      result = @context.send(:callback_transform, :before_save, some_object)
+      result.object_id.should == some_object.object_id
+    end
+    
+    it 'should handle filter callbacks' do
+      @context.register_callback(:should_save?) {|obj| obj[:foo] = 'bar'; nil}
+      @context.register_callback(:should_save?) {|obj| obj[:alpha] = 'beta'; obj}
+      @context.register_callback(:should_remove?) {|obj| obj[:p] = 'q'; :done}
+      
+      # Make sure it cancels properly.
+      some_object = {:foo => 'untouched', :value => 12345}
+      result = @context.send(:callback_filter?, :should_save?, some_object)
+      result.should be_nil
+      some_object.should == {:foo => 'bar', :value => 12345}
+      
+      # Make sure it still runs properly, even if the default is false.
+      some_object = {:foo => 'untouched', :value => 12345}
+      result = @context.send(:callback_filter?, :should_save?, some_object, false)
+      result.should be_nil
+      some_object.should == {:foo => 'bar', :value => 12345}
+      
+      # Make sure it falls off the end correctly.
+      some_object = {:foo => 'untouched', :value => 12345}
+      result = @context.send(:callback_filter?, :should_remove?, some_object)
+      result.should == :done
+      some_object.should == {:foo => 'untouched', :value => 12345, :p => 'q'}
+    end
+    
+    it 'should handle no filter callbacks' do
+      @context.callbacks(:save_should?).should be_empty
+       
+       # Make sure it defaults to true when there are no callbacks.
+      some_object = {:foo => 'untouched', :value => 12345}
+      result = @context.send(:callback_filter?, :should_save?, some_object)
+      result.should == true
+      some_object.should == {:foo => 'untouched', :value => 12345}
+      
+      # Make sure it uses the passed default when there are no callbacks.
+      some_object = {:foo => 'untouched', :value => 12345}
+      result = @context.send(:callback_filter?, :should_save?, some_object, :some_default)
+      result.should == :some_default
+      some_object.should == {:foo => 'untouched', :value => 12345}
+    end
+    
+  end
+  
+  describe 'FindHelpers' do
+    
+   it 'should have base methods private' do
+     pending
+   end
+   
+   it 'should pass calls from the main two public methods to their underlying private methods based on argument' do
+     pending
+   end
+    
+  end
+  
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 2
-  version: 0.1.2
+  - 3
+  version: 0.1.3
 platform: ruby
 authors: 
 - Jeff Reinecke
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-30 00:00:00 -07:00
+date: 2010-10-21 00:00:00 -07:00
 default_executable: 
 dependencies: []