activerecord_authorails 1.0.0

data/lib/active_record/acts/nested_set.rb

@@ -0,0 +1,211 @@
+module ActiveRecord
+  module Acts #:nodoc:
+    module NestedSet #:nodoc:
+      def self.included(base)
+        base.extend(ClassMethods)              
+      end  
+
+      # This acts provides Nested Set functionality.  Nested Set is similiar to Tree, but with
+      # the added feature that you can select the children and all of their descendents with
+      # a single query.  A good use case for this is a threaded post system, where you want
+      # to display every reply to a comment without multiple selects.
+      #
+      # A google search for "Nested Set" should point you in the direction to explain the
+      # database theory.  I figured out a bunch of this from
+      # http://threebit.net/tutorials/nestedset/tutorial1.html
+      #
+      # Instead of picturing a leaf node structure with children pointing back to their parent,
+      # the best way to imagine how this works is to think of the parent entity surrounding all
+      # of its children, and its parent surrounding it, etc.  Assuming that they are lined up
+      # horizontally, we store the left and right boundries in the database.
+      #
+      # Imagine:
+      #   root
+      #     |_ Child 1
+      #       |_ Child 1.1
+      #       |_ Child 1.2
+      #     |_ Child 2
+      #       |_ Child 2.1
+      #       |_ Child 2.2
+      #
+      # If my cirlces in circles description didn't make sense, check out this sweet
+      # ASCII art:
+      #
+      #     ___________________________________________________________________
+      #    |  Root                                                             |
+      #    |    ____________________________    ____________________________   |
+      #    |   |  Child 1                  |   |  Child 2                  |   |
+      #    |   |   __________   _________  |   |   __________   _________  |   |
+      #    |   |  |  C 1.1  |  |  C 1.2 |  |   |  |  C 2.1  |  |  C 2.2 |  |   |
+      #    1   2  3_________4  5________6  7   8  9_________10 11_______12 13  14
+      #    |   |___________________________|   |___________________________|   |
+      #    |___________________________________________________________________| 
+      #
+      # The numbers represent the left and right boundries.  The table then might
+      # look like this:
+      #    ID | PARENT | LEFT | RIGHT | DATA
+      #     1 |      0 |    1 |    14 | root
+      #     2 |      1 |    2 |     7 | Child 1
+      #     3 |      2 |    3 |     4 | Child 1.1
+      #     4 |      2 |    5 |     6 | Child 1.2
+      #     5 |      1 |    8 |    13 | Child 2
+      #     6 |      5 |    9 |    10 | Child 2.1
+      #     7 |      5 |   11 |    12 | Child 2.2
+      #
+      # So, to get all children of an entry, you
+      #     SELECT * WHERE CHILD.LEFT IS BETWEEN PARENT.LEFT AND PARENT.RIGHT
+      #
+      # To get the count, it's (LEFT - RIGHT + 1)/2, etc.
+      #
+      # To get the direct parent, it falls back to using the PARENT_ID field.   
+      #
+      # There are instance methods for all of these.
+      #
+      # The structure is good if you need to group things together; the downside is that
+      # keeping data integrity is a pain, and both adding and removing an entry
+      # require a full table write.        
+      #
+      # This sets up a before_destroy trigger to prune the tree correctly if one of its
+      # elements gets deleted.
+      #
+      module ClassMethods                      
+        # Configuration options are:
+        #
+        # * +parent_column+ - specifies the column name to use for keeping the position integer (default: parent_id)
+        # * +left_column+ - column name for left boundry data, default "lft"
+        # * +right_column+ - column name for right boundry data, default "rgt"
+        # * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach "_id" 
+        #   (if that hasn't been already) and use that as the foreign key restriction. It's also possible 
+        #   to give it an entire string that is interpolated if you need a tighter scope than just a foreign key.
+        #   Example: <tt>acts_as_list :scope => 'todo_list_id = #{todo_list_id} AND completed = 0'</tt>
+        def acts_as_nested_set(options = {})
+          configuration = { :parent_column => "parent_id", :left_column => "lft", :right_column => "rgt", :scope => "1 = 1" }
+          
+          configuration.update(options) if options.is_a?(Hash)
+          
+          configuration[:scope] = "#{configuration[:scope]}_id".intern if configuration[:scope].is_a?(Symbol) && configuration[:scope].to_s !~ /_id$/
+          
+          if configuration[:scope].is_a?(Symbol)
+            scope_condition_method = %(
+              def scope_condition
+                if #{configuration[:scope].to_s}.nil?
+                  "#{configuration[:scope].to_s} IS NULL"
+                else
+                  "#{configuration[:scope].to_s} = \#{#{configuration[:scope].to_s}}"
+                end
+              end
+            )
+          else
+            scope_condition_method = "def scope_condition() \"#{configuration[:scope]}\" end"
+          end
+        
+          class_eval <<-EOV
+            include ActiveRecord::Acts::NestedSet::InstanceMethods
+
+            #{scope_condition_method}
+            
+            def left_col_name() "#{configuration[:left_column]}" end
+
+            def right_col_name() "#{configuration[:right_column]}" end
+              
+            def parent_column() "#{configuration[:parent_column]}" end
+
+          EOV
+        end
+      end
+      
+      module InstanceMethods
+        # Returns true is this is a root node.  
+        def root?
+          parent_id = self[parent_column]
+          (parent_id == 0 || parent_id.nil?) && (self[left_col_name] == 1) && (self[right_col_name] > self[left_col_name])
+        end                                                                                             
+                                    
+        # Returns true is this is a child node
+        def child?                          
+          parent_id = self[parent_column]
+          !(parent_id == 0 || parent_id.nil?) && (self[left_col_name] > 1) && (self[right_col_name] > self[left_col_name])
+        end     
+        
+        # Returns true if we have no idea what this is
+        def unknown?
+          !root? && !child?
+        end
+
+                     
+        # Adds a child to this object in the tree.  If this object hasn't been initialized,
+        # it gets set up as a root node.  Otherwise, this method will update all of the
+        # other elements in the tree and shift them to the right, keeping everything
+        # balanced. 
+        def add_child( child )     
+          self.reload
+          child.reload
+
+          if child.root?
+            raise "Adding sub-tree isn\'t currently supported"
+          else
+            if ( (self[left_col_name] == nil) || (self[right_col_name] == nil) )
+              # Looks like we're now the root node!  Woo
+              self[left_col_name] = 1
+              self[right_col_name] = 4
+              
+              # What do to do about validation?
+              return nil unless self.save
+              
+              child[parent_column] = self.id
+              child[left_col_name] = 2
+              child[right_col_name]= 3
+              return child.save
+            else
+              # OK, we need to add and shift everything else to the right
+              child[parent_column] = self.id
+              right_bound = self[right_col_name]
+              child[left_col_name] = right_bound
+              child[right_col_name] = right_bound + 1
+              self[right_col_name] += 2
+              self.class.base_class.transaction {
+                self.class.base_class.update_all( "#{left_col_name} = (#{left_col_name} + 2)",  "#{scope_condition} AND #{left_col_name} >= #{right_bound}" )
+                self.class.base_class.update_all( "#{right_col_name} = (#{right_col_name} + 2)",  "#{scope_condition} AND #{right_col_name} >= #{right_bound}" )
+                self.save
+                child.save
+              }
+            end
+          end                                   
+        end
+                                   
+        # Returns the number of nested children of this object.
+        def children_count
+          return (self[right_col_name] - self[left_col_name] - 1)/2
+        end
+                                                               
+        # Returns a set of itself and all of its nested children
+        def full_set
+          self.class.base_class.find(:all, :conditions => "#{scope_condition} AND (#{left_col_name} BETWEEN #{self[left_col_name]} and #{self[right_col_name]})" )
+        end
+                  
+        # Returns a set of all of its children and nested children
+        def all_children
+          self.class.base_class.find(:all, :conditions => "#{scope_condition} AND (#{left_col_name} > #{self[left_col_name]}) and (#{right_col_name} < #{self[right_col_name]})" )
+        end
+                                  
+        # Returns a set of only this entry's immediate children
+        def direct_children
+          self.class.base_class.find(:all, :conditions => "#{scope_condition} and #{parent_column} = #{self.id}")
+        end
+                                      
+        # Prunes a branch off of the tree, shifting all of the elements on the right
+        # back to the left so the counts still work.
+        def before_destroy
+          return if self[right_col_name].nil? || self[left_col_name].nil?
+          dif = self[right_col_name] - self[left_col_name] + 1
+
+          self.class.base_class.transaction {
+            self.class.base_class.delete_all( "#{scope_condition} and #{left_col_name} > #{self[left_col_name]} and #{right_col_name} < #{self[right_col_name]}" )
+            self.class.base_class.update_all( "#{left_col_name} = (#{left_col_name} - #{dif})",  "#{scope_condition} AND #{left_col_name} >= #{self[right_col_name]}" )
+            self.class.base_class.update_all( "#{right_col_name} = (#{right_col_name} - #{dif} )",  "#{scope_condition} AND #{right_col_name} >= #{self[right_col_name]}" )
+          }
+        end
+      end
+    end
+  end
+end

data/lib/active_record/acts/tree.rb

@@ -0,0 +1,89 @@
+module ActiveRecord
+  module Acts #:nodoc:
+    module Tree #:nodoc:
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Specify this act if you want to model a tree structure by providing a parent association and a children
+      # association. This act requires that you have a foreign key column, which by default is called parent_id.
+      #
+      #   class Category < ActiveRecord::Base
+      #     acts_as_tree :order => "name"
+      #   end
+      #
+      #   Example:
+      #   root
+      #    \_ child1
+      #         \_ subchild1
+      #         \_ subchild2
+      #
+      #   root      = Category.create("name" => "root")
+      #   child1    = root.children.create("name" => "child1")
+      #   subchild1 = child1.children.create("name" => "subchild1")
+      #
+      #   root.parent   # => nil
+      #   child1.parent # => root
+      #   root.children # => [child1]
+      #   root.children.first.children.first # => subchild1
+      #
+      # In addition to the parent and children associations, the following instance methods are added to the class
+      # after specifying the act:
+      # * siblings          : Returns all the children of the parent, excluding the current node ([ subchild2 ] when called from subchild1)
+      # * self_and_siblings : Returns all the children of the parent, including the current node ([ subchild1, subchild2 ] when called from subchild1)
+      # * ancestors         : Returns all the ancestors of the current node ([child1, root] when called from subchild2)
+      # * root              : Returns the root of the current node (root when called from subchild2)
+      module ClassMethods
+        # Configuration options are:
+        #
+        # * <tt>foreign_key</tt> - specifies the column name to use for tracking of the tree (default: parent_id)
+        # * <tt>order</tt> - makes it possible to sort the children according to this SQL snippet.
+        # * <tt>counter_cache</tt> - keeps a count in a children_count column if set to true (default: false).
+        def acts_as_tree(options = {})
+          configuration = { :foreign_key => "parent_id", :order => nil, :counter_cache => nil }
+          configuration.update(options) if options.is_a?(Hash)
+
+          belongs_to :parent, :class_name => name, :foreign_key => configuration[:foreign_key], :counter_cache => configuration[:counter_cache]
+          has_many :children, :class_name => name, :foreign_key => configuration[:foreign_key], :order => configuration[:order], :dependent => :destroy
+
+          class_eval <<-EOV
+            include ActiveRecord::Acts::Tree::InstanceMethods
+
+            def self.roots
+              find(:all, :conditions => "#{configuration[:foreign_key]} IS NULL", :order => #{configuration[:order].nil? ? "nil" : %Q{"#{configuration[:order]}"}})
+            end
+
+            def self.root
+              find(:first, :conditions => "#{configuration[:foreign_key]} IS NULL", :order => #{configuration[:order].nil? ? "nil" : %Q{"#{configuration[:order]}"}})
+            end
+          EOV
+        end
+      end
+
+      module InstanceMethods
+        # Returns list of ancestors, starting from parent until root.
+        #
+        #   subchild1.ancestors # => [child1, root]
+        def ancestors
+          node, nodes = self, []
+          nodes << node = node.parent while node.parent
+          nodes
+        end
+
+        def root
+          node = self
+          node = node.parent while node.parent
+          node
+        end
+
+        def siblings
+          self_and_siblings - [self]
+        end
+
+        def self_and_siblings
+          parent ? parent.children : self.class.roots
+        end
+      end
+    end
+  end
+end

data/lib/active_record/aggregations.rb

@@ -0,0 +1,191 @@
+module ActiveRecord
+  module Aggregations # :nodoc:
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def clear_aggregation_cache #:nodoc:
+      self.class.reflect_on_all_aggregations.to_a.each do |assoc|
+        instance_variable_set "@#{assoc.name}", nil
+      end unless self.new_record?
+    end
+
+    # Active Record implements aggregation through a macro-like class method called +composed_of+ for representing attributes 
+    # as value objects. It expresses relationships like "Account [is] composed of Money [among other things]" or "Person [is]
+    # composed of [an] address". Each call to the macro adds a description of how the value objects are created from the 
+    # attributes of the entity object (when the entity is initialized either as a new object or from finding an existing object) 
+    # and how it can be turned back into attributes (when the entity is saved to the database). Example:
+    #
+    #   class Customer < ActiveRecord::Base
+    #     composed_of :balance, :class_name => "Money", :mapping => %w(balance amount)
+    #     composed_of :address, :mapping => [ %w(address_street street), %w(address_city city) ]
+    #   end
+    #
+    # The customer class now has the following methods to manipulate the value objects:
+    # * <tt>Customer#balance, Customer#balance=(money)</tt>
+    # * <tt>Customer#address, Customer#address=(address)</tt>
+    #
+    # These methods will operate with value objects like the ones described below:
+    #
+    #  class Money
+    #    include Comparable
+    #    attr_reader :amount, :currency
+    #    EXCHANGE_RATES = { "USD_TO_DKK" => 6 }  
+    # 
+    #    def initialize(amount, currency = "USD") 
+    #      @amount, @currency = amount, currency 
+    #    end
+    #
+    #    def exchange_to(other_currency)
+    #      exchanged_amount = (amount * EXCHANGE_RATES["#{currency}_TO_#{other_currency}"]).floor
+    #      Money.new(exchanged_amount, other_currency)
+    #    end
+    #
+    #    def ==(other_money)
+    #      amount == other_money.amount && currency == other_money.currency
+    #    end
+    #
+    #    def <=>(other_money)
+    #      if currency == other_money.currency
+    #        amount <=> amount
+    #      else
+    #        amount <=> other_money.exchange_to(currency).amount
+    #      end
+    #    end
+    #  end
+    #
+    #  class Address
+    #    attr_reader :street, :city
+    #    def initialize(street, city) 
+    #      @street, @city = street, city 
+    #    end
+    #
+    #    def close_to?(other_address) 
+    #      city == other_address.city 
+    #    end
+    #
+    #    def ==(other_address)
+    #      city == other_address.city && street == other_address.street
+    #    end
+    #  end
+    #  
+    # Now it's possible to access attributes from the database through the value objects instead. If you choose to name the
+    # composition the same as the attributes name, it will be the only way to access that attribute. That's the case with our
+    # +balance+ attribute. You interact with the value objects just like you would any other attribute, though:
+    #
+    #   customer.balance = Money.new(20)     # sets the Money value object and the attribute
+    #   customer.balance                     # => Money value object
+    #   customer.balance.exchanged_to("DKK") # => Money.new(120, "DKK")
+    #   customer.balance > Money.new(10)     # => true
+    #   customer.balance == Money.new(20)    # => true
+    #   customer.balance < Money.new(5)      # => false
+    #
+    # Value objects can also be composed of multiple attributes, such as the case of Address. The order of the mappings will
+    # determine the order of the parameters. Example:
+    #
+    #   customer.address_street = "Hyancintvej"
+    #   customer.address_city   = "Copenhagen"
+    #   customer.address        # => Address.new("Hyancintvej", "Copenhagen")
+    #   customer.address = Address.new("May Street", "Chicago")
+    #   customer.address_street # => "May Street" 
+    #   customer.address_city   # => "Chicago" 
+    #
+    # == Writing value objects
+    #
+    # Value objects are immutable and interchangeable objects that represent a given value, such as a Money object representing
+    # $5. Two Money objects both representing $5 should be equal (through methods such as == and <=> from Comparable if ranking
+    # makes sense). This is unlike entity objects where equality is determined by identity. An entity class such as Customer can
+    # easily have two different objects that both have an address on Hyancintvej. Entity identity is determined by object or
+    # relational unique identifiers (such as primary keys). Normal ActiveRecord::Base classes are entity objects.
+    #
+    # It's also important to treat the value objects as immutable. Don't allow the Money object to have its amount changed after
+    # creation. Create a new money object with the new value instead. This is exemplified by the Money#exchanged_to method that
+    # returns a new value object instead of changing its own values. Active Record won't persist value objects that have been
+    # changed through other means than the writer method.
+    #
+    # The immutable requirement is enforced by Active Record by freezing any object assigned as a value object. Attempting to 
+    # change it afterwards will result in a TypeError.
+    # 
+    # Read more about value objects on http://c2.com/cgi/wiki?ValueObject and on the dangers of not keeping value objects
+    # immutable on http://c2.com/cgi/wiki?ValueObjectsShouldBeImmutable
+    module ClassMethods
+      # Adds reader and writer methods for manipulating a value object:
+      # <tt>composed_of :address</tt> adds <tt>address</tt> and <tt>address=(new_address)</tt> methods.
+      #
+      # Options are:
+      # * <tt>:class_name</tt>  - specify the class name of the association. Use it only if that name can't be inferred
+      #   from the part id. So <tt>composed_of :address</tt> will by default be linked to the +Address+ class, but
+      #   if the real class name is +CompanyAddress+, you'll have to specify it with this option.
+      # * <tt>:mapping</tt> - specifies a number of mapping arrays (attribute, parameter) that bind an attribute name
+      #   to a constructor parameter on the value class.
+      # * <tt>:allow_nil</tt> - specifies that the aggregate object will not be instantiated when all mapped
+      #   attributes are nil.  Setting the aggregate class to nil has the effect of writing nil to all mapped attributes.
+      #   This defaults to false.
+      #
+      # Option examples:
+      #   composed_of :temperature, :mapping => %w(reading celsius)
+      #   composed_of :balance, :class_name => "Money", :mapping => %w(balance amount)
+      #   composed_of :address, :mapping => [ %w(address_street street), %w(address_city city) ]
+      #   composed_of :gps_location
+      #   composed_of :gps_location, :allow_nil => true
+      #
+      def composed_of(part_id, options = {})
+        options.assert_valid_keys(:class_name, :mapping, :allow_nil)
+
+        name        = part_id.id2name
+        class_name  = options[:class_name] || name.camelize
+        mapping     = options[:mapping]    || [ name, name ]
+        allow_nil   = options[:allow_nil]  || false
+
+        reader_method(name, class_name, mapping, allow_nil)
+        writer_method(name, class_name, mapping, allow_nil)
+        
+        create_reflection(:composed_of, part_id, options, self)
+      end
+
+      private
+        def reader_method(name, class_name, mapping, allow_nil)
+          mapping = (Array === mapping.first ? mapping : [ mapping ])
+
+          allow_nil_condition = if allow_nil
+            mapping.collect { |pair| "!read_attribute(\"#{pair.first}\").nil?"}.join(" && ")
+          else
+            "true"
+          end
+
+          module_eval <<-end_eval
+            def #{name}(force_reload = false)
+              if (@#{name}.nil? || force_reload) && #{allow_nil_condition}
+                @#{name} = #{class_name}.new(#{mapping.collect { |pair| "read_attribute(\"#{pair.first}\")"}.join(", ")})
+              end
+              return @#{name}
+            end
+          end_eval
+        end        
+        
+        def writer_method(name, class_name, mapping, allow_nil)
+          mapping = (Array === mapping.first ? mapping : [ mapping ])
+
+          if allow_nil
+            module_eval <<-end_eval
+              def #{name}=(part)
+                if part.nil?
+                  #{mapping.collect { |pair| "@attributes[\"#{pair.first}\"] = nil" }.join("\n")}
+                else
+                  @#{name} = part.freeze
+                  #{mapping.collect { |pair| "@attributes[\"#{pair.first}\"] = part.#{pair.last}" }.join("\n")}
+                end
+              end
+            end_eval
+          else
+            module_eval <<-end_eval
+              def #{name}=(part)
+                @#{name} = part.freeze
+                #{mapping.collect{ |pair| "@attributes[\"#{pair.first}\"] = part.#{pair.last}" }.join("\n")}
+              end
+            end_eval
+          end
+        end
+    end
+  end
+end