genealogy 1.5.0 → 2.0.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    N2JhNjJiMTU0MmE0MGMwMmI1YTI2NjAyZWRhOGZhODRjMDlkMzUyMw==
-  data.tar.gz: !binary |-
-    ZTU5ZWM1OWI2NWE5MDc1MmNlOTM1MDhlMzg3YTFmN2YxZjJkNTIyZA==
+SHA1:
+  metadata.gz: f135505bdbf0d836cdac669c1ee684c8959cedce
+  data.tar.gz: d90f6befee994c37e2a900d7c85e37e0c7f3229c
 SHA512:
-  metadata.gz: !binary |-
-    MGIxNGE2YzUxNTA1ZmU4NzE3NGIwMTMxNzBkYjcxMWFmOGZmZGMzMGViNzg3
-    MGI5NmYwZGE1OTNlY2JhNDU0YzM2ZGUzMjNhMmU3YWFkODZjMzcwZmQwNWMz
-    YTM4MmEwN2ZmZDJmNmQ5OGMxMGFlMmJhYmMzYTM5YjMwNzIxNWU=
-  data.tar.gz: !binary |-
-    NDljNjIxODUzMDBmZjgxNzk5Y2RlMTk0ZWI3NTMxYTM3MDcxNjMwMjQxY2Qx
-    M2IxZDNiNzg5MDJlMDFhZWEzYjY2ZWY2MDc3ZmJmZWM4MjZjODU3YTkxYTJm
-    ZGU5ZDNmM2MwOWExY2E5YzgxZWYwMTlhM2M4OTllYjlmMTdkNGU=
+  metadata.gz: f1efa40c2b50b47caad8d4608157195d0a0d68f1659c08c1eb44d31381d61ec8bb738c61ada1369de74baad8f4c693aa3f0d54dd624c354897b7349eb2d0f081
+  data.tar.gz: 443d273ad5240f9a5ecad5c902f8535a421f7c3f46e5d37b5a8c363c42713c582ca498dc582748f13fd89cb64c26ee7fd616d3de332d5f0c790528706ee95554

data/lib/genealogy.rb

@@ -1,9 +1,11 @@
 require File.join(File.expand_path(File.dirname(__FILE__)), 'genealogy/constants')
 require File.join(File.expand_path(File.dirname(__FILE__)), 'genealogy/exceptions')
+require File.join(File.expand_path(File.dirname(__FILE__)), 'genealogy/util_methods')
+require File.join(File.expand_path(File.dirname(__FILE__)), 'genealogy/ineligible_methods')
 require File.join(File.expand_path(File.dirname(__FILE__)), 'genealogy/query_methods')
 require File.join(File.expand_path(File.dirname(__FILE__)), 'genealogy/alter_methods')
-require File.join(File.expand_path(File.dirname(__FILE__)), 'genealogy/spouse_methods')
+require File.join(File.expand_path(File.dirname(__FILE__)), 'genealogy/current_spouse_methods')
 require File.join(File.expand_path(File.dirname(__FILE__)), 'genealogy/genealogy')
 
-ActiveRecord::Base.send :extend, Genealogy
+ActiveRecord::Base.send :include, Genealogy
 

data/lib/genealogy/alter_methods.rb

@@ -1,39 +1,54 @@
 module Genealogy
+  # Module AlterMethods provides methods to alter genealogy. It's included by the genealogy enabled AR model
   module AlterMethods
     extend ActiveSupport::Concern
 
-    # parents 
-    [:father, :mother].each do |parent|
+    include Constants
 
-      # add method
+    # @!macro [attach] generate
+    #   @method add_$1(parent)
+    #   Add $1 
+    #   @param [Object] parent
+    #   @raise [Exception] if perform validation is enabled and self is invalid
+    #   @return [Boolean] 
+    def self.generate_method_add_parent(parent)
       define_method "add_#{parent}" do |relative|
-        unless relative.nil?
-          raise IncompatibleObjectException, "Both linked objects must be instances of class with genealogy enabled. Got classes #{relative.class} and #{self.genealogy_class}" unless relative.class.respond_to?(:genealogy_enabled)
-          incompatible_parents = self.offspring | self.siblings | [self] 
-          raise IncompatibleRelationshipException, "#{relative} can't be #{parent} of #{self}" if incompatible_parents.include? relative
-          raise WrongSexException, "Can't add a #{relative.sex} #{parent}" unless (parent == :father and relative.is_male?) or (parent == :mother and relative.is_female?)
-        end
-        if perform_validation
+        check_incompatible_relationship(parent,relative)
+        if gclass.perform_validation_enabled
           self.send("#{parent}=",relative)
           save!
         else
           self.update_attribute(parent,relative)
         end
       end
-
-      # remove method
+    end
+    generate_method_add_parent(:father)
+    generate_method_add_parent(:mother)
+
+    # @!macro [attach] generate
+    #   @method remove_$1
+    #   remove $1. Foreign_key set to nil
+    #   @raise [Exception] if perform validation is enabled and self is invalid
+    #   @return [Boolean] 
+    def self.generate_method_remove_parent(parent)
       define_method "remove_#{parent}" do
-        if perform_validation
+        if gclass.perform_validation_enabled
           self.send("#{parent}=",nil)
           save!
         else
           self.update_attribute(parent,nil)
         end
       end
-
     end
-
-    # add both
+    generate_method_remove_parent(:father)
+    generate_method_remove_parent(:mother)
+
+    # add both parents calling #add_father and #add_mother in a transaction
+    # @param [Object] father
+    # @param [Object] mother
+    # @see #add_father
+    # @see #add_mother
+    # @return [Boolean] 
     def add_parents(father,mother)
       transaction do
         add_father(father)
@@ -41,7 +56,10 @@ module Genealogy
       end
     end
 
-    # remove both
+    # remove both parents calling #remove_father and #remove_mother in a transaction
+    # @see #remove_father
+    # @see #remove_mother
+    # @return [Boolean] 
     def remove_parents
       transaction do
         remove_father
@@ -49,37 +67,87 @@ module Genealogy
       end
     end
 
-    # grandparents
-    [:father, :mother].each do |parent|
-      [:father, :mother].each do |grandparent|
-        # add one 
-        define_method "add_#{Genealogy::PARENT2LINEAGE[parent]}_grand#{grandparent}" do |relative|
-          raise IncompatibleRelationshipException, "#{self} can't be grand#{grandparent} of itself" if relative == self
-          raise_if_gap_on(parent)
-          send(parent).send("add_#{grandparent}",relative)
-        end
-        # remove one
-        define_method "remove_#{Genealogy::PARENT2LINEAGE[parent]}_grand#{grandparent}" do
-          raise_if_gap_on(parent)
-          send(parent).send("remove_#{grandparent}")
-        end
+    # @!macro [attach] generate
+    #   @method add_$1_grand$2(grandparent)
+    #   Add $1 grand$2 
+    #   @param [Object] gp grandparent
+    #   @raise [Exception] if perform validation is enabled and self is invalid
+    #   @return [Boolean] 
+    def self.generate_method_add_grandparent(lineage,grandparent)
+      relationship = "#{lineage}_grand#{grandparent}"
+      define_method "add_#{relationship}" do |gp|
+        parent = LINEAGE2PARENT[lineage]
+        raise_if_gap_on(parent)
+        check_incompatible_relationship(relationship,gp)
+        send(parent).send("add_#{grandparent}",gp)
       end
     end
-
-    [:father, :mother].each do |parent|
-      # add two by lineage
-      define_method "add_#{Genealogy::PARENT2LINEAGE[parent]}_grandparents" do |grandfather,grandmother|
+    generate_method_add_grandparent(:paternal,:father)
+    generate_method_add_grandparent(:paternal,:mother)
+    generate_method_add_grandparent(:maternal,:father)
+    generate_method_add_grandparent(:maternal,:mother)
+
+    # @!macro [attach] generate
+    #   @method remove_$1_grand$2
+    #   remove $1 grand$2 
+    #   @raise [Exception] if perform validation is enabled and self is invalid
+    #   @return [Boolean] 
+    def self.generate_method_remove_grandparent(lineage,grandparent)
+      relationship = "#{lineage}_grand#{grandparent}"
+      define_method "remove_#{relationship}" do
+        parent = LINEAGE2PARENT[lineage]
         raise_if_gap_on(parent)
-        send(parent).send("add_parents",grandfather,grandmother)
+        send(parent).send("remove_#{grandparent}")
       end
-      # remove two by lineage
-      define_method "remove_#{Genealogy::PARENT2LINEAGE[parent]}_grandparents" do
+    end
+    generate_method_remove_grandparent(:paternal,:father)
+    generate_method_remove_grandparent(:paternal,:mother)
+    generate_method_remove_grandparent(:maternal,:father)
+    generate_method_remove_grandparent(:maternal,:mother)
+
+    # @!macro [attach] generate
+    #   @method add_$1_grandparents
+    #   Add $1 grandparents 
+    #   @param [Object] gf grandfather
+    #   @param [Object] gm grandmother
+    #   @raise [Exception] if perform validation is enabled and self is invalid
+    #   @return [Boolean] 
+    def self.generate_method_add_grandparents_by_lineage(lineage)
+      relationship = "#{lineage}_grandparents"
+      define_method "add_#{relationship}" do |gf,gm|
+        parent = LINEAGE2PARENT[lineage]
+        raise_if_gap_on(parent)
+        send(parent).send("add_parents",gf,gm)
+      end
+    end
+    generate_method_add_grandparents_by_lineage(:paternal)
+    generate_method_add_grandparents_by_lineage(:maternal)
+
+    # @!macro [attach] generate
+    #   @method remove_$1_grandparents
+    #   remove $1 grandparents 
+    #   @raise [Exception] if perform validation is enabled and self is invalid
+    #   @return [Boolean] 
+    def self.generate_method_remove_grandparents_by_lineage(lineage)
+      relationship = "#{lineage}_grandparents"
+      define_method "remove_#{relationship}" do 
+        parent = LINEAGE2PARENT[lineage]
         raise_if_gap_on(parent)
         send(parent).send("remove_parents")
       end
     end
-
-    # add all
+    generate_method_remove_grandparents_by_lineage(:paternal)
+    generate_method_remove_grandparents_by_lineage(:maternal)
+
+
+    # add all grandparents calling #add_paternal_grandparents and #add_maternal_grandparents in a transaction
+    # @param [Object] pgf paternal grandfather
+    # @param [Object] pgm paternal grandmother
+    # @param [Object] mgf maternal grandfather
+    # @param [Object] mgm maternal grandmother
+    # @see #add_paternal_grandparents
+    # @see #add_maternal_grandparents
+    # @return [Boolean] 
     def add_grandparents(pgf,pgm,mgf,mgm)
       transaction do
         add_paternal_grandparents(pgf,pgm)
@@ -87,160 +155,152 @@ module Genealogy
       end
     end
 
-    # remove all
-    def remove_grandparents
+    # remove all grandparents calling #remove_paternal_grandparents and #remove_maternal_grandparents in a transaction
+    # @see #remove_paternal_grandparents
+    # @see #remove_maternal_grandparents
+    # @return [Boolean] 
+   def remove_grandparents
       transaction do
         remove_paternal_grandparents
         remove_maternal_grandparents
       end
     end
 
-    ## siblings
+    # add siblings by assigning same parents to individuals passed as arguments
+    # @overload add_siblings(*siblings,options={})
+    #   @param [Object] siblings list of siblings
+    #   @param [Hash] options
+    #   @option options [Symbol] half :father for paternal half siblings and :mother for maternal half siblings
+    #   @option options [Object] spouse if specified, passed individual will be used as mother in case of half sibling
+    # @return [Boolean] 
     def add_siblings(*args)
       options = args.extract_options!
-      raise IncompatibleRelationshipException, "Can't add an ancestor as sibling" unless (ancestors.to_a & args).empty?
+      check_incompatible_relationship(:sibling, *args)
       transaction do
         args.inject(true) do |res,sib|
           res &= case options[:half]
           when :father
             raise LineageGapException, "Can't add paternal halfsiblings without a father" unless father
-            sib.add_father(self.father)
             sib.add_mother(options[:spouse]) if options[:spouse]
+            sib.add_father(father)
           when :mother
             raise LineageGapException, "Can't add maternal halfsiblings without a mother" unless mother
             sib.add_father(options[:spouse]) if options[:spouse]
-            sib.add_mother(self.mother)
+            sib.add_mother(mother)
           when nil
             raise LineageGapException, "Can't add siblings without parents" unless father and mother
-            sib.add_father(self.father)
-            sib.add_mother(self.mother)
+            sib.add_father(father)
+            sib.add_mother(mother)
           else
-            raise WrongOptionValueException, "Admitted values for :half options are: :father, :mother or nil"
+            raise ArgumentError, "Admitted values for :half options are: :father, :mother or nil"
           end
         end
       end
     end
 
-    def add_sibling(sib,options={})
-      add_siblings(sib,options)
+    # @see #add_siblings
+    def add_sibling(sibling,options={})
+      add_siblings(sibling,options)
     end
 
+    
+    # remove siblings by nullifying parents of passed individuals 
+    # @overload remove_siblings(*siblings,options={})
+    #   @param [Object] siblings list of siblings
+    #   @param [Hash] options
+    #   @option options [Symbol] half :father for paternal half siblings and :mother for maternal half siblings
+    #   @option options [Boolean] remove_other_parent if specified, passed individuals' mother will also be nullified
+    # @return [Boolean] true if at least one sibling was affected, false otherwise
     def remove_siblings(*args)
       options = args.extract_options!
-
-      raise WrongOptionException.new("Unknown option value: :half => #{options[:half]}.") if (options[:half] and ![:father,:mother].include?(options[:half]))
-
+      raise ArgumentError.new("Unknown option value: half: #{options[:half]}.") if (options[:half] and ![:father,:mother].include?(options[:half]))
       resulting_indivs = if args.blank?
         siblings(options)
       else
         args & siblings(options)
       end
-
       transaction do
-
         resulting_indivs.each do |sib|
           case options[:half]
           when :father
             sib.remove_father
-            sib.remove_mother if options[:affect_spouse] == true
+            sib.remove_mother if options[:remove_other_parent] == true
           when :mother
-            sib.remove_father if options[:affect_spouse] == true
+            sib.remove_father if options[:remove_other_parent] == true
             sib.remove_mother
           when nil
             sib.remove_parents
           end  
         end
-
       end
-
       !resulting_indivs.empty? #returned value must be true if self has at least a siblings to affect
-
     end
 
+    # @see #remove_siblings
     def remove_sibling(sib,options={})
       remove_siblings(sib,options)
     end
 
-    [:father, :mother].each do |parent|
-
-      # add paternal/maternal half_siblings
-      define_method "add_#{Genealogy::PARENT2LINEAGE[parent]}_half_siblings" do | *args |
-        options = args.extract_options!
-        options[:half] = parent
-        args << options
-        send("add_siblings",*args)
-      end
-
-      # add paternal/maternal half_sibling
-      define_method "add_#{Genealogy::PARENT2LINEAGE[parent]}_half_sibling" do | sib,options={} |
-        options[:half] = parent
-        send("add_sibling",sib,options)
-      end
-
-      # remove paternal/maternal half_siblings
-      define_method "remove_#{Genealogy::PARENT2LINEAGE[parent]}_half_siblings" do | *args |
-        options = args.extract_options!
-        options[:half] = parent
-        args << options
-        send("remove_siblings",*args)
-      end
-
-      # remove paternal/maternal half_sibling
-      define_method "remove_#{Genealogy::PARENT2LINEAGE[parent]}_half_sibling" do | sib,options={} |
-        options[:half] = parent
-        send("remove_sibling",sib,options)
-      end
-    end
-
-    # offspring
-    def add_offspring(*args)
+    # add children by assigning self as parent
+    # @overload add_children(*children,options={})
+    #   @param [Object] children list of children
+    #   @param [Hash] options
+    #   @option options [Object] spouse if specified, children will have that spouse
+    # @return [Boolean] 
+    def add_children(*args)
       options = args.extract_options!
-
       raise_if_sex_undefined
-
+      check_incompatible_relationship(:children, *args)
       transaction do
-        args.each do |child|
-          case sex
-          when sex_male_value
-            child.add_father(self)
+        args.inject(true) do |res,child|
+          res &= case sex
+          when gclass.sex_male_value
             child.add_mother(options[:spouse]) if options[:spouse]
-          when sex_female_value
+            child.add_father(self)
+          when gclass.sex_female_value
             child.add_father(options[:spouse]) if options[:spouse]
             child.add_mother(self)
           else 
-            raise WrongSexException, "Sex value not valid for #{self}"
+            raise SexError, "Sex value not valid for #{self}"
           end
         end
       end
     end
 
+    # see #add_children
     def add_child(child,options={})
-      add_offspring(child,options)
+      add_children(child,options)
     end
 
-    def remove_offspring(*args)
+    # remove children by nullifying the parent corresponding to self
+    # @overload remove_children(*children,options={})
+    #   @param [Object] children list of children
+    #   @param [Hash] options
+    #   @option options [Boolean] remove_other_parent if specified, passed individuals' mother will also be nullified
+    # @return [Boolean] true if at least one child was affected, false otherwise
+    def remove_children(*args)
       options = args.extract_options!
 
       raise_if_sex_undefined
 
       resulting_indivs = if args.blank?
-        offspring(options)
+        children(options)
       else
-        args & offspring(options)
+        args & children(options)
       end
 
       transaction do
         resulting_indivs.each do |child|
-          if options[:affect_spouse] == true
+          if options[:remove_other_parent] == true
             child.remove_parents
           else
             case sex
-            when sex_male_value
+            when gclass.sex_male_value
               child.remove_father
-            when sex_female_value
+            when gclass.sex_female_value
               child.remove_mother
             else 
-              raise WrongSexException, "Sex value not valid for #{self}"
+              raise SexError, "Sex value not valid for #{self}"
             end  
           end
         end
@@ -248,8 +308,9 @@ module Genealogy
       !resulting_indivs.empty? #returned value must be true if self has at least a siblings to affect
     end
 
+    # see #remove_children
     def remove_child(child,options={})
-      remove_offspring(child,options)
+      remove_children(child,options)
     end
 
     private
@@ -259,7 +320,7 @@ module Genealogy
     end
 
     def raise_if_sex_undefined
-      raise WrongSexException, "Can't proceed if sex undefined for #{self}" unless is_male? or is_female?
+      raise SexError, "Can't proceed if sex undefined for #{self}" unless is_male? or is_female?
     end
 
   end