genealogy 1.5.0 → 2.0.0

data/lib/genealogy/query_methods.rb

@@ -1,180 +1,174 @@
 module Genealogy
+  # Module QueryMethods provides methods to run genealogy queries to retrive relatives by role. It's included by the genealogy enabled AR model
   module QueryMethods
     extend ActiveSupport::Concern
 
-    # parents
+    include Constants
+
+    # @return [2-elements Array] father and mother 
     def parents
       [father,mother]
     end
-
-    # eligible
-    [:father, :mother].each do |parent|
-      define_method "eligible_#{parent}s" do
-        if send(parent)
-          []
-        else
-          self.genealogy_class.send("#{Genealogy::PARENT2SEX[parent]}s") - descendants - [self]
-        end
-      end
+    # @return [ActiveRecord] 
+    def paternal_grandfather
+      father && father.father
+    end
+    # @return [ActiveRecord] 
+    def paternal_grandmother
+      father && father.mother
+    end
+    # @return [ActiveRecord] 
+    def maternal_grandfather
+      mother && mother.father
+    end
+    # @return [ActiveRecord] 
+    def maternal_grandmother
+      mother && mother.mother
     end
 
-    # grandparents
-    [:father, :mother].each do |parent|
-      [:father, :mother].each do |grandparent|
-
-        # get one
-        define_method "#{Genealogy::PARENT2LINEAGE[parent]}_grand#{grandparent}" do
-          send(parent) && send(parent).send(grandparent)
-        end
-
-        # eligible
-        define_method "eligible_#{Genealogy::PARENT2LINEAGE[parent]}_grand#{grandparent}s" do
-          if send(parent) and send("#{Genealogy::PARENT2LINEAGE[parent]}_grand#{grandparent}").nil?
-            send(parent).send("eligible_#{grandparent}s") - [self]
-          else
-            []
-          end
-        end
-
-      end
-
-      # get two by lineage
-      define_method "#{Genealogy::PARENT2LINEAGE[parent]}_grandparents" do
-        (send(parent) && send(parent).parents) || [nil,nil]
-      end
+    # @return [2-elements Array] paternal_grandfather and paternal_grandmother 
+    def paternal_grandparents
+      father && father.parents
+    end
 
+    # @return [2-elements Array] maternal_grandfather and maternal_grandmother
+    def maternal_grandparents
+      mother && mother.parents
     end
 
+    # @return [4-elements Array] paternal_grandfather, paternal_grandmother, maternal_grandfather, maternal_grandmother
     def grandparents
-      result = []
-      [:father, :mother].each do |parent|
-        [:father, :mother].each do |grandparent|
-          result << send("#{Genealogy::PARENT2LINEAGE[parent]}_grand#{grandparent}")
-        end
-      end
-      # result.compact! if result.all?{|gp| gp.nil? }
-      result
+      [paternal_grandfather, paternal_grandmother, maternal_grandfather, maternal_grandmother]
     end
 
+    # @return [8-elements Array] paternal_grandfather's father, paternal_grandmother's father, maternal_grandfather's father, maternal_grandmother's father, paternal_grandfather's mother, paternal_grandmother's mother, maternal_grandfather's mother, maternal_grandmother's mother
     def great_grandparents
-      parents.compact.inject([]){|memo, parent| memo |= parent.grandparents}
-    end
-
-    # offspring
-    def offspring(options = {})
-      if spouse = options[:spouse]
-        raise WrongSexException, "Problems while looking for #{self}'s offspring made with spouse #{spouse} who should not be a #{spouse.sex}." if spouse.sex == sex
+      grandparents.inject([]){|memo, gp| memo += (gp.try(:parents) || [nil,nil]) }.flatten
+    end
+
+    # @param [Hash] options
+    # @option options [Object] spouse to filter children by spouse
+    # @return [ActiveRecord::Relation] children
+    def children(options = {})
+      raise SexError, "Sex value not valid for #{self}. It's needed to look for children" unless gclass.sex_values.include? sex
+      result = gclass.where(SEX2PARENT[ssex] => self)
+      if options.keys.include? :spouse
+        check_indiv(spouse = options[:spouse],opposite_ssex)
+        result = result.where(SEX2PARENT[opposite_ssex] => spouse ) if spouse
       end
-      result = case sex
-      when sex_male_value
-        if options.keys.include?(:spouse)
-          children_as_father.with(spouse.try(:id))
-        else
-          children_as_father
-        end
-      when sex_female_value
-        if options.keys.include?(:spouse)
-          children_as_mother.with(spouse.try(:id))
-        else
-          children_as_mother
-        end
-      else
-        raise WrongSexException, "Sex value not valid for #{self}"
-      end
-      result.to_a
-    end
-    alias_method :children, :offspring
-
-    def eligible_offspring
-      self.genealogy_class.all - ancestors - offspring - siblings - [self]
+      result
     end
-    alias_method :eligible_children, :eligible_offspring
 
-    # spouses
+    # @return [ActiveRecord::Relation] list of individuals with whom has had children
     def spouses
-      parent_method = Genealogy::SEX2PARENT[Genealogy::OPPOSITESEX[sex_to_s.to_sym]]
-      offspring.collect{|child| child.send(parent_method)}.uniq
-    end
-
-    def eligible_spouses
-      self.genealogy_class.send("#{Genealogy::OPPOSITESEX[sex_to_s.to_sym]}s") - spouses
+      gclass.where(id: children.pluck("#{SEX2PARENT[opposite_ssex]}_id".to_sym).compact.uniq)
     end
 
-    # siblings
+    # @param [Hash] options
+    # @option options [Symbol] half let you filter siblings. Possible values are:
+    #   :father for paternal halfsiblings
+    #   :mother for maternal halfsiblings
+    #   :only for all halfsiblings
+    #   :include for fullsiblings and halfsiblings
+    # @return [ActiveRecord::Relation] list of fullsiblings and/or halfsiblings
     def siblings(options = {})
-      result = case options[:half]
+      spouse = options[:spouse]
+
+      result = gclass.where.not(id: id)
+      case options[:half]
       when nil # only full siblings
-        unless parents.include?(nil)
-          father.try(:offspring, :spouse => mother ).to_a
+        result.all_with(:parents).where(father_id: father, mother_id: mother)
+      when :father # common father
+        result = result.all_with(:father).where(father_id: father)
+        if spouse 
+          check_indiv(spouse, :female)
+          result.where(mother_id: spouse)
+        elsif mother
+          result.where("#{gclass.mother_id_column} != ? or #{gclass.mother_id_column} is ?", mother_id, nil)
         else
-          []
+          result
         end
-      when :father # common father
-        father.try(:offspring, options.keys.include?(:spouse) ? {:spouse => options[:spouse]} : {}).to_a - mother.try(:offspring).to_a
       when :mother # common mother
-        mother.try(:offspring, options.keys.include?(:spouse) ? {:spouse => options[:spouse]} : {}).to_a - father.try(:offspring).to_a
+        result = result.all_with(:mother).where(mother_id: mother)
+        if spouse
+          check_indiv(spouse, :male)
+          result.where(father_id: spouse)
+        elsif father
+          result.where("#{gclass.father_id_column} != ? or #{gclass.father_id_column} is ?", father_id, nil)
+        else
+          result
+        end
       when :only # only half siblings
-        siblings(:half => :include) - siblings
+        ids = siblings(half: :father).pluck(:id) | siblings(half: :mother).pluck(:id)
+        result.where(id: ids)
       when :include # including half siblings
-        father.try(:offspring).to_a + mother.try(:offspring).to_a
+        result.where("#{gclass.father_id_column} == ? or #{gclass.mother_id_column} == ?", father_id, mother_id)
       else
-        raise WrongOptionValueException, "Admitted values for :half options are: :father, :mother, false, true or nil"
+        raise ArgumentError, "Admitted values for :half options are: :father, :mother, false, true or nil"
       end
-      result.uniq - [self]
-    end
 
-    def eligible_siblings
-      self.genealogy_class.all - ancestors - siblings(:half => :include) - [self]
     end
 
-    def half_siblings
-      siblings(:half => :only)
-      # todo: inprove with option :father and :mother
+    # siblings with option half: :only
+    # @see #siblings 
+    def half_siblings(options = {})
+      siblings(options.merge(half: :only))
     end
 
-    def paternal_half_siblings
-      siblings(:half => :father)
+    # siblings with option half: :father
+    # @see #siblings
+    def paternal_half_siblings(options = {})
+      siblings(options.merge(half: :father))
     end
 
-    def maternal_half_siblings
-      siblings(:half => :mother)
+    # siblings with option half: :mother
+    # @see #siblings
+    def maternal_half_siblings(options = {})
+      siblings(options.merge(half: :mother))
     end
 
-    alias_method :eligible_half_siblings, :eligible_siblings
-    alias_method :eligible_paternal_half_siblings, :eligible_siblings
-    alias_method :eligible_maternal_half_siblings, :eligible_siblings
-
-    # ancestors
-    def ancestors
-      result = []
-      remaining = parents.compact
-      until remaining.empty?
-        result << remaining.shift
-        remaining += result.last.parents.compact
+    # get list of known ancestrors iterateing over parents
+    # @param [Hash] options
+    # @return [ActiveRecord::Relation] list of ancestors
+    def ancestors(options = {})
+      ids = []
+      remaining_ids = parents.compact.map(&:id)
+      until remaining_ids.empty?
+        ids << remaining_ids.shift
+        remaining_ids += gclass.find(ids.last).parents.compact.map(&:id)
       end
-      result.uniq
+      gclass.where(id: ids)
     end
 
-    # descendants
+
+    # get list of known descendants iterateing over children ...
+    # @return [ActiveRecord::Relation] list of descendants
     def descendants
-      result = []
-      remaining = offspring.to_a.compact
-      until remaining.empty?
-        result << remaining.shift
-        remaining += result.last.offspring.to_a.compact
-        # break if (remaining - result).empty? can be necessary in case of loop. Idem for ancestors method
+      ids = []
+      remaining_ids = children.map(&:id)
+      until remaining_ids.empty?
+        ids << remaining_ids.shift
+        remaining_ids += gclass.find(ids.last).children.pluck(:id)
+        # break if (remaining_ids - ids).empty? can be necessary in case of loop. Idem for ancestors method
       end
-      result.uniq
+      gclass.where(id: ids)
     end
 
+    # @return [ActiveRecord::Relation] list of grandchildren
     def grandchildren
-      offspring.inject([]){|memo,child| memo |= child.offspring}
+      result = children.inject([]){|memo,child| memo |= child.children}
     end
 
+    # @return [ActiveRecord::Relation] list of grat-grandchildren
     def great_grandchildren
-      grandchildren.compact.inject([]){|memo,grandchild| memo |= grandchild.offspring}
-    end
-
+      result = grandchildren.compact.inject([]){|memo,grandchild| memo |= grandchild.children}
+    end
+    
+    # list of uncles and aunts iterating through parents' siblings
+    # @param [Hash] options
+    # @option options [Symbol] lineage to filter by lineage: :paternal or :maternal
+    # @option options [Symbol] half to filter by half siblings (see #siblings)
+    # @return [ActiveRecord::Relation] list of uncles and aunts
     def uncles_and_aunts(options={})
       relation = case options[:lineage]
       when :paternal
@@ -184,86 +178,71 @@ module Genealogy
       else
         parents
       end
-
-      case options[:sex]
-      when :male
-        relation.compact.inject([]){|memo,parent| memo |= parent.siblings(half: options[:half]).select(&:is_male?)}
-      when :female
-        relation.compact.inject([]){|memo,parent| memo |= parent.siblings(half: options[:half]).select(&:is_female?)}
-      else
-        relation.compact.inject([]){|memo,parent| memo |= parent.siblings(half: options[:half])}
-      end
+      ids = relation.compact.inject([]){|memo,parent| memo |= parent.siblings(half: options[:half]).pluck(:id)}
+      gclass.where(id: ids)
     end
 
+    # @see #uncles_and_aunts
     def uncles(options = {})
-      uncles_and_aunts(sex: :male, lineage: options[:lineage], half: options[:half])
+      uncles_and_aunts(options).males
     end
 
-    def aunts(options={})
-      uncles_and_aunts(sex: :female, lineage: options[:lineage], half: options[:half])
+    # @see #uncles_and_aunts
+    def aunts(options = {})
+      uncles_and_aunts(options).females
     end
 
+    # @see #uncles_and_aunts
     def paternal_uncles(options = {})
-      uncles(sex: :male, lineage: :paternal, half: options[:half])
+      uncles(options.merge(lineage: :paternal))
     end
 
+    # @see #uncles_and_aunts
     def maternal_uncles(options = {})
-      uncles(sex: :male, lineage: :maternal, half: options[:half])
+      uncles(options.merge(lineage: :maternal))
     end
 
+    # @see #uncles_and_aunts
     def paternal_aunts(options = {})
-      aunts(lineage: :paternal, half: options[:half])
+      aunts(options.merge(lineage: :paternal))
     end
 
+    # @see #uncles_and_aunts
     def maternal_aunts(options = {})
-      aunts(sex: :female, lineage: :maternal, half: options[:half])
+      aunts(options.merge(lineage: :maternal))
     end
 
-    def cousins(options = {}, uncle_aunt_options = {})
-      uncles_and_aunts(uncle_aunt_options).compact.inject([]){|memo,parent_sibling| memo |= parent_sibling.offspring}
+    # @param [Hash] options
+    # @option options [Symbol] lineage to filter uncles by lineage: :paternal or :maternal
+    # @option options [Symbol] half to filter uncles (see #siblings)
+    # @return [ActiveRecord::Relation] list of uncles and aunts' children
+    def cousins(options = {})
+      ids = uncles_and_aunts(options).inject([]){|memo,uncle| memo |= uncle.children.pluck(:id)}
+      gclass.where(id: ids)
     end
 
-    def nieces_and_nephews(options = {}, sibling_options = {})
-      case options[:sex]
-      when :male
-        siblings(sibling_options).inject([]){|memo,sib| memo |= sib.offspring}.select(&:is_male?)
-      when :female
-        siblings(sibling_options).inject([]){|memo,sib| memo |= sib.offspring}.select(&:is_female?)
-      else
-        siblings(sibling_options).inject([]){|memo,sib| memo |= sib.offspring}
-      end
+    # @param [Hash] options
+    # @option options [Symbol] half to filter siblings (see #siblings)
+    # @return [ActiveRecord::Relation] list of nieces and nephews
+    def nieces_and_nephews(options = {})
+      ids = siblings(options).inject([]){|memo,sib| memo |= sib.children.pluck(:id)}
+      gclass.where(id: ids)
     end
 
-    def nephews(options = {}, sibling_options = {})
-      nieces_and_nephews(options.merge({sex: :male}), sibling_options)
+    # @see #nieces_and_nephews
+    def nephews(options = {})
+      nieces_and_nephews.males
     end
 
-    def nieces(options = {}, sibling_options = {})
-      nieces_and_nephews(options.merge({sex: :female}), sibling_options)
-    end
-
-    def family(options = {})
-      res = [self] | siblings | parents | offspring
-      res |= [current_spouse] if self.class.current_spouse_enabled
-      res |= case options[:half]
-        when nil
-          []
-        when :include
-          half_siblings
-        when :father
-          paternal_half_siblings
-        when :mother
-          maternal_half_siblings
-        else
-          raise WrongOptionValueException, "Admitted values for :half options are: :father, :mother, :include, nil"
-      end
-      res = offspring.inject(res){|memo,child| memo |= child.parents} #add spouses
-
-      res += [grandparents + grandchildren + uncles_and_aunts + nieces_and_nephews].flatten if options[:extended]
-
-      res.compact
+    # @see #nieces_and_nephews
+    def nieces(options = {})
+      nieces_and_nephews.females
     end
 
+    # family hash with roles as keys? :spouse and individuals as values. Defaults roles are :father, :mother, :children, :siblings and current_spouse if enabled
+    # @option options [Symbol] half to filter siblings (see #siblings)
+    # @option options [Boolean] extended to include roles for grandparents, grandchildren, uncles, aunts, nieces, nephews and cousins
+    # @return [Hash] family hash with roles as keys? :spouse and individuals as values. 
     def family_hash(options = {})
       roles = [:father, :mother, :children, :siblings]
       roles += [:current_spouse] if self.class.current_spouse_enabled
@@ -277,79 +256,58 @@ module Genealogy
         when :mother
           [:maternal_half_siblings]
         else
-          raise WrongOptionValueException, "Admitted values for :half options are: :father, :mother, :include, nil"
+          raise ArgumentError, "Admitted values for :half options are: :father, :mother, :include, nil"
       end
-      roles += [:paternal_grandfather, :paternal_grandmother, :maternal_grandfather, :maternal_grandmother, :grandchildren, :uncles_and_aunts, :nieces_and_nephews] if options[:extended]
-      h = {}
-      roles.each{|role| h[role] = self.send(role)}
-      h
-    end
-
-    def extended_family(options = {})
-      family(options.merge(:extended => true))
+      roles += [:paternal_grandfather, :paternal_grandmother, :maternal_grandfather, :maternal_grandmother, :grandchildren, :uncles_and_aunts, :nieces_and_nephews, :cousins] if options[:extended] == true
+      roles.inject({}){|res,role| res.merge!({role => self.send(role)})}
     end
 
+    # family_hash with option extended: :true
+    # @see #family_hash
     def extended_family_hash(options = {})
-      family_hash(options.merge(:extended => true))
+      family_hash(options.merge(extended: true))
     end
 
-    def sex_to_s
-      case sex
-      when sex_male_value
-        'male'
-      when sex_female_value
-        'female'
-      else
-        raise WrongSexException, "Sex value not valid for #{self}"
-      end
-    end
-
-    def is_female?
-      return female? if respond_to?(:female?)
-      sex == sex_female_value
-    end
-
-    def is_male?
-      return male? if respond_to?(:male?)
-      sex == sex_male_value
-    end
-
-    def birth
-      self.send("#{genealogy_class.birth_date_column}")
+    # family individuals
+    # @return [Array]
+    # @see #family_hash 
+    def family(options = {})
+      hash = family_hash(options)
+      hash.keys.inject([]){|tot,k| tot << hash[k] }.compact.flatten
     end
 
-    def death
-      self.send("#{genealogy_class.death_date_column}")
+    # family with option extended: :true
+    # @see #family
+    def extended_family(options = {})
+      family(options.merge(extended: true))
     end
 
-    def age(options={})
-      birth_date = birth
-      death_date = death
-      return if birth_date.nil?
-
-      current = options[:end_date] ? DateTime.parse(options[:end_date]) : death_date || Time.zone.now
-      years = current.year - birth_date.year
-
-      if options[:measurement] == :years || !options[:measurement]
-        return  options[:string] ? "#{years} years" : years
-      end
-
-      months = current.month - birth_date.month
-      months += 12 if months < 0
-
-      if options[:measurement] == :months
-        return options[:string] ? "#{years} years and #{months} months" : (years * 12) + months
-      end
-      return years
-    end
+    private
 
     module ClassMethods
+      # all male individuals
+      # @return [ActiveRecord::Relation] 
       def males
-        where(sex_column => sex_male_value)
+        where(sex: sex_male_value)
       end
+      # all female individuals
+      # @return [ActiveRecord::Relation] 
       def females
-        where(sex_column => sex_female_value)
+        where(sex: sex_female_value)
       end
+      # all individuals individuals having relative with specified role
+      # @return [ActiveRecord, ActiveRecord::Relation] 
+      def all_with(role)
+        case role
+        when :father
+          where.not(father_id: nil)
+        when :mother
+          where.not(mother_id: nil)
+        when :parents
+          where.not(mother_id: nil,father_id: nil)
+        end
+      end
+
     end
 
   end