hyperactive 0.2.3 → 0.2.4

data/README

@@ -7,15 +7,21 @@ It uses archipelago for persistence, and is meaningful only in an environment wh
 Hyperactive::Record:: The base class package itself, providing you with cached selectors and rejectors, along with cached finders for any number of attributes.
 Hyperactive::Hash:: A collection class that contains any number of Hyperactive::Records in a hash like structure.
 Hyperactive::List:: A collection class that contains any number of Hyperactive::Records in a list like structure.
+Hyperactive::Index:: A module included into Hyperactive::Record that adds simple indexing capabilities of the <b>find_by_...</b> type.
+Hyperactive::Transactions:: A module included into Hyperactive::Record that adds a few simplifications in handling transactions properly.
 
 == Usage:
 
 To use Hyperactive in the simplest way, just run the script/services.rb script from the Archipelago 
 distribution to get a few services running, then subclass Hyperactive::Record::Bass and create 
-objects with <b>MyBassSubclass.get_instance</b> (not <b>new</b>!). They will be automagically 
-stored in the network, and fetchable via their <b>instance.record_id</b>.
+objects with <b>MyBassSubclass.get_instance</b>. They will be automagically stored in the network, 
+and fetchable via their <b>instance.record_id</b>.
 
-By loading Hyperactive::Record you will automatically define Hyperactive::Record::CAPTAIN which will
+You can also use <b>new</b> of course, but beware that this will not store the object persistently 
+<b>or</b> give you a proxy. Both of these things are good for you, so use get_instance unless you know
+what you are doing. 
+
+By loading Hyperactive::Record you will automatically define Hyperactive::CAPTAIN which will
 be an Archipelago::Pirate::Captain that is your interface to the distributed database.
 
 == Examples:

data/TODO

@@ -0,0 +1,4 @@
+
+ * Create a validation framework for Hyperactive::Record::Bass
+
+ * Create a sorted data structure, for example AA trees: http://www.eternallyconfuzzled.com/tuts/andersson.html

data/lib/hyperactive/hash.rb

@@ -62,6 +62,7 @@ module Hyperactive
       # NB: Remember to call create on the new instance or use Head.get_instance to get that done automatically.
       #
       def initialize
+        super
         self.list = nil
       end
 
@@ -72,11 +73,18 @@ module Hyperactive
         self.list.size
       end
 
+      #
+      # Return whether this Hash is empty.
+      #
+      def empty?
+        self.list.empty?
+      end
+
       #
       # Return the value for +key+.
       #
       def [](key)
-        element = Hyperactive::Record::CAPTAIN[my_key_for(key), @transaction]
+        element = Hyperactive::CAPTAIN[my_key_for(key), @transaction]
         if element
           return element.value
         else
@@ -88,7 +96,7 @@ module Hyperactive
       # Returns whether +key+ is included in this Hash.
       #
       def include?(key)
-        Hyperactive::Record::CAPTAIN.include?(my_key_for(key), @transaction)
+        Hyperactive::CAPTAIN.include?(my_key_for(key), @transaction)
       end
 
       #
@@ -97,13 +105,13 @@ module Hyperactive
       def []=(key, value)
         self.list = Hyperactive::List::Head.get_instance_with_transaction(@transaction) unless self.list
 
-        if (element = Hyperactive::Record::CAPTAIN[my_key_for(key), @transaction])
+        if (element = Hyperactive::CAPTAIN[my_key_for(key), @transaction])
           element.value = value
         else          
           element = Element.get_instance_with_transaction(@transaction, key, value, nil)
           self.list << element
           element.list_element = self.list.last_element
-          Hyperactive::Record::CAPTAIN[my_key_for(key), @transaction] = element
+          Hyperactive::CAPTAIN[my_key_for(key), @transaction] = element
         end
       end
 
@@ -115,9 +123,9 @@ module Hyperactive
 
         return_value = nil
 
-        element = Hyperactive::Record::CAPTAIN[my_key_for(key), @transaction]
+        element = Hyperactive::CAPTAIN[my_key_for(key), @transaction]
         if element
-          Hyperactive::Record::CAPTAIN.delete(my_key_for(key), @transaction)
+          Hyperactive::CAPTAIN.delete(my_key_for(key), @transaction)
           self.list.unlink!(element.list_element)
           return_value = element.value
           element.destroy!

data/lib/hyperactive/hooker.rb

@@ -19,61 +19,171 @@
 module Hyperactive
   
   #
-  # A utility method to simplify using around-hooks for any block.
+  # A container of utility hook methods.
   #
   module Hooker
 
     #
-    # Will call each hook in +hooks+ with a block that
-    # calls the rest of the +hooks+ with +argument+ as argument
-    # and after that yields to the given +block+.
+    # Something that uses hooks a lot, include if you want support for various types of hooks.
     #
-    # This will allow you wrap any method call in a dynamic set
-    # of other methods.
-    #
-    # For more examples, see Hyperactive::Record.
-    #
-    # Example:
-    #   class ImportantStuff
-    #     attr_accessor :timestamp
-    #     def is_valid?
-    #       # do nifty stuff
-    #     end
-    #     def notify_someone_that_i_am_changed!(message)
-    #       # do even more nifty stuff
-    #     end
-    #     def validate_and_notify(message)
-    #       raise "i am invalid!" unless is_valid?
-    #       yield
-    #       notify_someone_that_i_am_changed!(message)
-    #     end
-    #     def do_save
-    #       # save me in persistent storage
-    #     end
-    #   end
-    #   class ImportantHandler
-    #     def update_timestamp(important_stuff_instance)
-    #       important_stuff_instance.timestamp = Time.now
-    #       Hyperactive::Hooker.call_with_hooks("changed at #{Time.now}", 
-    #                                           important_stuff_instance.method(:validate_and_notify)) do
-    #         important_stuff_instance.do_save
-    #       end
-    #     end
-    #   end
-    #
-    def call_with_hooks(argument, *hooks, &block)
-      if hooks.empty?
-        yield
-      else
-        first = hooks.first
-        rest = hooks[1..-1]
-        first.call(argument) do
-          call_with_hooks(argument, *rest, &block)
+    module Pimp
+
+      #
+      # Upon inclusion, our +base+ class will be given a set of hook
+      # arrays, and then get extended by ClassMethods.
+      #
+      def self.append_features(base)
+        super
+        base.instance_variable_set(:@create_hooks, [])
+        base.instance_variable_set(:@destroy_hooks, [])
+        base.instance_variable_set(:@save_hooks, [])
+        base.instance_variable_set(:@load_hooks, [])
+        base.extend(ClassMethods)
+      end
+
+      #
+      # This will allow us to wrap any write of us to persistent storage
+      # in the @save_hooks as long as the Archipelago::Hashish provider
+      # supports it. See Archipelago::Hashish::BerkeleyHashish for an example
+      # of Hashish providers that do this.
+      #
+      def save_hook(old_value, &block)
+        self.class.with_hooks(:instance => self, :arguments => [old_value], :hooks => self.class.save_hooks) do
+          yield
         end
       end
-    end
+      
+      #
+      # This will allow us to wrap any load of us from persistent storage
+      # in the @@load_hooks as long as the Archipelago::Hashish provider
+      # supports it. See Archipelago::Hashish::BerkeleyHashish for an example
+      # of Hashish providers that do this.
+      #
+      def load_hook(&block)
+        self.class.with_hooks(:instance => self, :hooks => self.class.load_hooks) do
+          yield
+        end
+      end
+      
 
-    module_function :call_with_hooks
+      #
+      # The class methods of a Pimp.
+      #
+      module ClassMethods
+
+        #
+        # Will wrap a block within nested calls to given hooks.
+        #
+        # Parameters:
+        # * <i>:instance</i>: An instance to send methods to, defaults to self
+        # * <i>:arguments</i>: Extra arguments to send to whatever we call, defaults to self
+        # * <i>:hooks</i>: An Array of hook objects. They can be either Strings or Symbols, or
+        #   whatever else can be given to <b>respond_to?</b>, <b>or</b> they can be anything
+        #   that <b>respond_to?(:call)</b>. If the hook is something that 
+        #   <i>respond_to?(:call)</i> it will be <i>call</i>ed and given 
+        #   the the <i>:instance</i> and *<i>:arguments</i> and the provided +block+. 
+        #   Else the <i>:instance</i>.respond_to?(<i>the given hook</i>)
+        #   must be true, and that <i>:instance</i> will be sent the <i>given hook</i> along with the <i>:arguments</i> and 
+        #   a block that does the rest of the hooks.
+        #
+        def with_hooks(options = {}, &block)
+          instance = options[:instance] || self
+          arguments = options[:arguments] || []
+          hooks = options[:hooks] || []
+
+          if hooks.empty?
+            yield
+          else
+            first = hooks.first
+            rest = hooks[1..-1]
+            if first.respond_to?(:call)
+              first.call(instance, *arguments) do
+                with_hooks(:instance => instance, :hooks => rest, :arguments => arguments, &block)
+              end
+            elsif instance.respond_to?(first)
+              instance.send(first, *arguments) do
+                with_hooks(:instance => instance, :hooks => rest, :arguments => arguments, &block)
+              end
+            else
+              raise "You can only send in hooks that are Symbols in the given instance or call'able objects"
+            end
+          end
+        end
+
+        #
+        # Upon inheritance, our +subclass+ will be given copies of our hooks.
+        #
+        def inherited(subclass)
+          subclass.instance_variable_set(:@create_hooks, @create_hooks.clone)
+          subclass.instance_variable_set(:@destroy_hooks, @destroy_hooks.clone)
+          subclass.instance_variable_set(:@save_hooks, @save_hooks.clone)
+          subclass.instance_variable_set(:@load_hooks, @load_hooks.clone)
+        end
+        
+        #
+        # Return our create_hooks, which can then be treated as any old Array.
+        #
+        # These must be <b>call</b>able objects with an arity of 1
+        # that will be sent the instance about to be created (initial
+        # insertion into the database system) that take a block argument.
+        # 
+        # The block argument will be a Proc that actually injects the
+        # instance into the database system.
+        #
+        # Use this to preprocess, validate and/or postprocess your
+        # instances upon creation.
+        #
+        attr_reader :create_hooks
+
+        #
+        # Return our destroy_hooks, which can then be treated as any old Array.
+        #
+        # These must be <b>call</b>able objects with an arity of 1
+        # that will be sent the instance about to be destroyed (removal
+        # from the database system) that take a block argument.
+        # 
+        # The block argument will be a Proc that actually removes the
+        # instance from the database system.
+        #
+        # Use this to preprocess, validate and/or postprocess your
+        # instances upon destruction.
+        #
+        attr_reader :destroy_hooks
+        
+        #
+        # Return our load_hooks, which can then be treated as any old Array.
+        #
+        # These must be <b>call</b>able objects with an arity of 1
+        # that will be sent the instance about to be loaded (insertion
+        # into the live hash of the database in question) that take a block argument.
+        # 
+        # The block argument will be a Proc that actually puts the
+        # instance into the live hash.
+        #
+        # Use this to preprocess, validate and/or postprocess your
+        # instances upon loading.
+        #
+        attr_reader :load_hooks
+        
+        #
+        # Return our save_hooks, which can then be treated as any old Array.
+        #
+        # These must be <b>call</b>able objects with an arity of 1
+        # that will be sent [the old version, the new version] of the 
+        # instance about to be saved (storage into the database system) 
+        # along with a block argument.
+        # 
+        # The block argument will be a Proc that actually saves the
+        # instance into the database system.
+        #
+        # Use this to preprocess, validate and/or postprocess your
+        # instances upon saving.
+        #
+        attr_reader :save_hooks
+        
+      end
+      
+    end
 
   end
 

data/lib/hyperactive/index.rb

@@ -0,0 +1,210 @@
+# Archipelago - a distributed computing toolkit for ruby
+# Copyright (C) 2006  Martin Kihlgren <zond at troja dot ath dot cx>
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+
+module Hyperactive
+
+  module Index
+    
+    #
+    # A tiny <b>call</b>able class that saves stuff in
+    # indexes depending on certain attributes.
+    #
+    class IndexBuilder
+      #
+      # Get the key for the given attributes and values.
+      #
+      def self.get_key(klass, attributes, values)
+        "Hyperactive::IndexBuilder::#{klass}::#{attributes.join(",")}::#{values.join(",")}"
+      end
+      #
+      # Initialize an IndexBuilder giving it an array of +attributes+
+      # that will be indexed.
+      #
+      def initialize(klass, attributes)
+        @klass = klass
+        @attributes = attributes
+      end
+      #
+      # Get the key for the given +record+.
+      #
+      def get_key_for(record)
+        values = @attributes.collect do |att|
+          if record.respond_to?(att)
+            record.send(att)
+          else
+            nil
+          end
+        end
+        key = self.class.get_key(@klass, @attributes, values)
+      end
+      #
+      # Call this IndexBuilder and pass it a +block+.
+      #
+      # If the +argument+ is an Array then we know we are a save hook, 
+      # otherwise we are a destroy hook.
+      #
+      def call(*arguments, &block)
+        yield
+
+        #
+        # If the argument is an Array (of old value, new value)
+        # then we are a save hook, otherwise a destroy hook.
+        #
+        if arguments.size > 1
+          record = arguments.first
+          old_record = arguments.last
+          old_key = get_key_for(old_record)
+          new_key = get_key_for(record)
+          if old_key != new_key
+            (CAPTAIN[old_key] ||= Hyperactive::Hash::Head.get_instance_with_transaction(record.transaction)).delete(record.record_id)
+            (CAPTAIN[new_key] ||= Hyperactive::Hash::Head.get_instance_with_transaction(record.transaction))[record.record_id] = record
+          end
+        else
+          record = arguments.first
+          (CAPTAIN[get_key_for(record)] ||= Hyperactive::Hash::Head.get_instance_with_transaction(record.transaction)).delete(record.record_id)
+        end
+      end
+    end
+
+    #
+    # A tiny <b>call</b>able class that saves stuff inside containers
+    # if they match certain criteria.
+    #
+    class MatchSaver
+      #
+      # Initialize this MatchSaver with a +key+, a <b>call</b>able +matcher+
+      # and a +mode+ (:select, :reject, :delete_if_match or :delete_unless_match).
+      #
+      def initialize(key, matcher, mode)
+        @key = key
+        @matcher = matcher
+        @mode = mode
+      end
+      #
+      # Depending on <i>@mode</i> and return value of <i>@matcher</i>.call
+      # may save record in the Hash-like container named <i>@key</i> in
+      # the main database after having yielded to +block+.
+      #
+      def call(*arguments, &block)
+        yield
+
+        record = arguments.first
+
+        case @mode
+        when :select
+          if @matcher.call(record)
+            CAPTAIN[@key, record.transaction][record.record_id] = record
+          else
+            CAPTAIN[@key, record.transaction].delete(record.record_id)
+          end
+        when :reject
+          if @matcher.call(record)
+            CAPTAIN[@key, record.transaction].delete(record.record_id)
+          else
+            CAPTAIN[@key, record.transaction][record.record_id] = record
+          end
+        when :delete_if_match
+          if @matcher.call(record)
+            CAPTAIN[@key, record.transaction].delete(record.record_id)
+          end
+        when :delete_unless_match
+          unless @matcher.call(record)
+            CAPTAIN[@key, record.transaction].delete(record.record_id)
+          end
+        end
+      end
+    end
+
+    module Indexable
+      
+      def self.append_features(base)
+        super
+        base.extend(ClassMethods)
+      end
+      
+      module ClassMethods
+        #
+        # Create an index for this class.
+        #
+        # Will create a method find_by_#{attributes.join("_and_")} for this
+        # class that will return what you expect.
+        #
+        def index_by(*attributes)
+          klass = self
+          self.class.class_eval do
+            define_method("find_by_#{attributes.join("_and_")}") do |*args|
+              CAPTAIN[IndexBuilder.get_key(klass, attributes, args)]
+            end
+          end
+          index_builder = IndexBuilder.new(self, attributes)
+          self.save_hooks << index_builder
+          self.destroy_hooks << index_builder
+        end
+    
+        #
+        # Will define a method called +name+ that will include all
+        # existing instances of this class that when yielded to the +block+
+        # returns true. Will only return instances saved after this selector
+        # is defined.
+        #
+        def select(name, &block) #:yields: instance
+          key = collection_key(name)
+          CAPTAIN[key] ||= Hyperactive::Hash::Head.get_instance
+          self.class.class_eval do
+            define_method(name) do
+              CAPTAIN[key]
+            end
+          end
+          self.save_hooks << MatchSaver.new(key, block, :select)
+          self.destroy_hooks << MatchSaver.new(key, block, :delete_if_match)
+        end
+        
+        #
+        # Will define a method called +name+ that will include all
+        # existing instances of this class that when yielded to +block+
+        # does not return true. Will only return instances saved after this
+        # rejector is defined.
+        #
+        def reject(name, &block) #:yields: instance
+          key = collection_key(name)
+          CAPTAIN[key] ||= Hyperactive::Hash::Head.get_instance
+          self.class.class_eval do
+            define_method(name) do
+              CAPTAIN[key]
+            end
+          end
+          self.save_hooks << MatchSaver.new(key, block, :reject)
+          self.destroy_hooks << MatchSaver.new(key, block, :delete_unless_match)
+        end
+
+        private
+
+        #
+        # The key used to store the collection with the given +sym+ as name.
+        #
+        def collection_key(sym)
+          "Hyperactive::Index::Indexable::collection_key::#{sym}"
+        end
+
+        
+      end
+
+    end
+
+  end
+
+end

data/lib/hyperactive/list.rb

@@ -70,6 +70,7 @@ module Hyperactive
       # NB: Remember to call create on the new instance or use Head.get_instance to get that done automatically.
       #
       def initialize
+        super
         self.size = 0
         self.first_element = self.last_element = nil
       end
@@ -102,6 +103,13 @@ module Hyperactive
         element.destroy!
       end
 
+      #
+      # Return whether this List is empty.
+      #
+      def empty?
+        return self.size == 0
+      end
+
       #
       # Remove all elements from this List::Head.
       #