poly_belongs_to 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 56d5f029c2d24b2474440dc487ca11d9da0592bd
-  data.tar.gz: 626db50369225abcd48137ece11615554ea8ad77
+  metadata.gz: ab96e43c85c346057343a22a9e06b8cf532eef4c
+  data.tar.gz: af27f3c4ec9facc1577fdace270ebd3bbbb9f9ff
 SHA512:
-  metadata.gz: 5344d97c85fb343ef385e647f1c2c043ea881e9a727d63774ca46de9e90ebccf1fcff5c24084ff8c9d058938f0587b57da8e76c4f47da854908fa4abd5709e03
-  data.tar.gz: 7d0c57c277948b7d336ac2e882d2f1fee2e9330f653a9370265f2b1d7ca3158b62c850a2371c21ce6c95dd6aa94086339e8a579204c89b5ca1b4bd2c374c4182
+  metadata.gz: 4b3fb493356381a13b006f927f2c13c28bde9ae004c0bdff342f7ad5cd224a080e76776d21cb28317e707ca419afba8cf41e3aee66c2357cda753eb4b58746fc
+  data.tar.gz: 778008ce2888fc121386f93bb71242d33f92048164451dda3ee5db436894235334bfab5c15dcd09c3ea2de15bf2e133199ac8387e272bb133fa318b3e3418bb2

data/README.md

@@ -3,6 +3,7 @@
 [![Code Climate](https://codeclimate.com/github/danielpclark/PolyBelongsTo/badges/gpa.svg)](https://codeclimate.com/github/danielpclark/PolyBelongsTo)
 [![Build Status](https://travis-ci.org/danielpclark/PolyBelongsTo.svg)](https://travis-ci.org/danielpclark/PolyBelongsTo)
 [![Test Coverage](https://codeclimate.com/github/danielpclark/PolyBelongsTo/badges/coverage.svg)](https://codeclimate.com/github/danielpclark/PolyBelongsTo)
+[![Inline docs](http://inch-ci.org/github/danielpclark/PolyBelongsTo.svg?branch=master)](http://inch-ci.org/github/danielpclark/PolyBelongsTo)
 
 **Original Purpose:** A standard way to check belongs_to relations on any belongs_to Object and let you check your DB Objects polymorphism in a more across-the-board meta-programatically friendly way.
 

data/lib/poly_belongs_to.rb

@@ -1,6 +1,3 @@
-# Poly Belongs To
-# The MIT License (MIT)
-# Copyright (C) 2015 by Daniel P. Clark
 $: << File.join(File.dirname(__FILE__), "/poly_belongs_to")
 require 'active_support/concern'
 require 'poly_belongs_to/version'
@@ -12,3 +9,19 @@ require 'poly_belongs_to/faked_collection'
 ActiveRecord::Base.send(:include, PolyBelongsTo::Core )
 ActiveRecord::Base.send(:include, PolyBelongsTo::Dup  )
 
+
+
+##
+#
+# PolyBelongsTo
+# @author Daniel P. Clark
+#
+# Creates uniform helper methods on all ActiveModel & ActiveRecord instances
+# to allow universal access and control over (most) any kind of database
+# relationship.
+#
+# PolyBelongsTo::Core and PolyBelongsTo::Dup methods are included on each instance.
+# @see PolyBelongsTo::Core
+# @see PolyBelongsTo::Dup
+#
+module PolyBelongsTo end

data/lib/poly_belongs_to/core.rb

@@ -1,20 +1,29 @@
 module PolyBelongsTo
+  ##
+  # PolyBelongsTo::Core are the core set of methods included on all ActiveModel & ActiveRecord instances.
   module Core
     extend ActiveSupport::Concern
 
     included do
+      # @return [Symbol] first belongs_to relation
       def self.pbt
         reflect_on_all_associations(:belongs_to).first.try(:name)
       end
 
+      # @return [Array<Symbol>] belongs_to relations
       def self.pbts
         reflect_on_all_associations(:belongs_to).map(&:name)
       end
       
+      # Boolean reponse of current class being polymorphic
+      # @return [true, false]
       def self.poly?
         !!reflect_on_all_associations(:belongs_to).first.try {|i| i.options[:polymorphic] }
       end
 
+      # Symbol for html form params
+      # @param allow_as_nested [true, false] Allow parameter name to be nested attribute symbol
+      # @return [Symbol] The symbol for the form in the view
       def self.pbt_params_name(allow_as_nested = true)
         if poly? && allow_as_nested
           "#{table_name}_attributes".to_sym
@@ -23,37 +32,51 @@ module PolyBelongsTo
         end
       end
 
+      # The symbol as an id field for the first belongs_to relation
+      # @return [Symbol, nil] :`belongs_to_object`_id or nil
       def self.pbt_id_sym
         val = pbt
         val ? "#{val}_id".to_sym : nil
       end
 
+      # The symbol as an sym field for the polymorphic belongs_to relation, or nil
+      # @return [Symbol, nil] :`belongs_to_object`_sym or nil
       def self.pbt_type_sym
         poly? ? "#{pbt}_type".to_sym : nil
       end
     end
     
+    # @return [Symbol] first belongs_to relation
     def pbt
       self.class.pbt
     end
 
+    # @return [Array<Symbol>] belongs_to relations
     def pbts
       self.class.pbts
     end
     
+    # Boolean reponse of current class being polymorphic
+    # @return [true, false]
     def poly?
       self.class.poly?
     end
 
+    # Value of parent id.  nil if no parent
+    # @return [Integer, nil]
     def pbt_id
       val = pbt
       val ? self.send("#{val}_id") : nil
     end
 
+    # Value of polymorphic relation type.  nil if not polymorphic.
+    # @return [String, nil]
     def pbt_type
       poly? ? self.send("#{pbt}_type") : nil
     end
 
+    # Get the parent relation.  Polymorphic relations are prioritized first.
+    # @return [Object] ActiveRecord object instasnce
     def pbt_parent
       val = pbt
       if val && !pbt_id.nil?
@@ -67,6 +90,9 @@ module PolyBelongsTo
       end
     end
 
+    # Climb up each parent object in the hierarchy until the top is reached.
+    #   This has a no-repeat safety built in.  Polymorphic parents have priority.
+    # @return [Object] top parent ActiveRecord object instace
     def pbt_top_parent
       record = self
       return nil unless record.pbt_parent
@@ -78,6 +104,8 @@ module PolyBelongsTo
       record
     end
 
+    # All belongs_to parents as class objects. One if polymorphic.
+    # @return [Array<Object>] ActiveRecord classes of parent objects.
     def pbt_parents
       if poly?
         Array[pbt_parent].compact
@@ -88,14 +116,21 @@ module PolyBelongsTo
       end
     end
 
+    # The symbol as an id field for the first belongs_to relation
+    # @return [Symbol, nil] :`belongs_to_object`_id or nil
     def pbt_id_sym
       self.class.pbt_id_sym
     end
 
+    # The symbol as an sym field for the polymorphic belongs_to relation, or nil
+    # @return [Symbol, nil] :`belongs_to_object`_sym or nil
     def pbt_type_sym
       self.class.pbt_type_sym
     end
 
+    # Symbol for html form params
+    # @param allow_as_nested [true, false] Allow parameter name to be nested attribute symbol
+    # @return [Symbol] The symbol for the form in the view
     def pbt_params_name(allow_as_nested = true)
       self.class.pbt_params_name(allow_as_nested)
     end

data/lib/poly_belongs_to/dup.rb

@@ -1,8 +1,13 @@
 module PolyBelongsTo
+  ##
+  # PolyBelongsTo::Dup contains duplication methods which is included on all ActiveModel & ActiveRecord instances
   module Dup
     extend ActiveSupport::Concern
 
     included do
+      # Build child object by dup'ing its attributes
+      # @param item_to_build_on [Object] Object on which to build on
+      # @param item_to_duplicate [Object] Object to duplicate as new child
       def self.pbt_dup_build(item_to_build_on, item_to_duplicate)
         singleton_record = yield if block_given? 
         if PolyBelongsTo::Pbt::IsReflected[item_to_build_on, item_to_duplicate]
@@ -12,6 +17,9 @@ module PolyBelongsTo
         end
       end
 
+      # Build child object by dup'ing its attributes. Recursive for ancestry tree.
+      # @param item_to_build_on [Object] Object on which to build on
+      # @param item_to_duplicate [Object] Object to duplicate as new child along with child ancestors
       def self.pbt_deep_dup_build(item_to_build_on, item_to_duplicate)
         singleton_record = (block_given? ? yield : PolyBelongsTo::SingletonSet.new)
         pbt_dup_build(item_to_build_on, item_to_duplicate) {singleton_record}
@@ -29,10 +37,14 @@ module PolyBelongsTo
 
    end
 
+    # Build child object by dup'ing its attributes
+    # @param item_to_duplicate [Object] Object to duplicate as new child
     def pbt_dup_build(item_to_duplicate, &block)
       self.class.pbt_dup_build(self, item_to_duplicate, &block)
     end
 
+    # Build child object by dup'ing its attributes. Recursive for ancestry tree.
+    # @param item_to_duplicate [Object] Object to duplicate as new child along with child ancestors
     def pbt_deep_dup_build(item_to_duplicate, &block)
       self.class.pbt_deep_dup_build(self, item_to_duplicate, &block)
     end

data/lib/poly_belongs_to/faked_collection.rb

@@ -1,5 +1,8 @@
 module PolyBelongsTo
+  ##
+  # PolyBelongsTo::FakedCollection emulates an ActiveRecord::CollectionProxy of exactly one or zero items
   class FakedCollection
+    # Create the Faked Colllection Proxy
     def initialize(obj = nil, child = nil)
       @obj = obj
       @child = child
@@ -12,75 +15,109 @@ module PolyBelongsTo
       self
     end
 
+    # @return [Integer, nil]
     def id
       @instance.try(:id)
     end
 
+    # @return [Array]
     def all
       Array[@instance].compact
     end
 
+    # Boolean of empty?
+    # @return [true, false]
     def empty?
       all.empty?
     end
 
+    # Boolean of not empty?
+    # @return [true, false]
     def present?
       !empty?
     end
 
+    # @return [self, nil]
     def presence
       all.first ? self : nil
     end
 
+    # Boolean of validity
+    # @return [true, false]
     def valid?
       !!@instance.try(&:valid?)
     end
 
+    # @return [Object, nil]
     def first
       @instance
     end
 
+    # @return [Object, nil]
     def last
       @instance
     end
 
+    # @return [Integer] 1 or 0
     def size
       all.size
     end
 
+    # @return [Array<Object>]
     def ancestors
       klass.ancestors.unshift(PolyBelongsTo::FakedCollection)
     end
-
+    
+    # Boolean of kind match
+    # @param thing [Object] object class
+    # @return [true, false]
     def kind_of?(thing)
       ancestors.include? thing
     end
 
+    # Boolean of kind match
+    # @param thing [Object] object class
+    # @return [true, false]
     def is_a?(thing)
       kind_of?(thing)
     end
 
+    # alias for size
+    # @return [Integer] 1 or 0
     def count
       size
     end
 
+    # @return [Object] object class
     def klass
       @instance.class
     end
 
+    # build preforms calculated build command and returns self
+    # @param args [Array<Symbol>] arguments
+    # @return [self]
     def build(*args)
       @instance = @obj.send(PolyBelongsTo::Pbt::BuildCmd[@obj, @child], *args)
       self
     end
 
+    # @param args [Array<Symbol>] arguments
+    # @return [Enumerator]
     def each(*args, &block)
       all.each(*args, &block)
     end
 
+    # Returns whether this or super responds to method
+    # @param method_name [Symbol]
+    # @return [true, false]
     def respond_to?(method_name)
       @instance.respond_to?(method_name) || super
     end
 
+    # Hands method and argument on to instance if it responds to method, otherwise calls super
+    # @param method_name [Symbol]
+    # @param args [Array<Symbol>] arguments
+    # @return [true, false]
     def method_missing(method_name, *args, &block)
       if @instance.respond_to?(method_name)
         @instance.send method_name, *args, &block

data/lib/poly_belongs_to/pbt.rb

@@ -1,5 +1,11 @@
 module PolyBelongsTo
+  ##
+  # PolyBelongsTo::Pbt is where internal methods are for implementing core and duplication methods; available on all instances.
+  # They are available for other use if the need should arise.
   module Pbt
+    # Strips date and id fields dup'd attributes
+    # @param obj [Object] ActiveRecord instance that has attributes
+    # @return [Hash] attributes
     AttrSanitizer = lambda {|obj|
       return {} unless obj
       obj.dup.attributes.delete_if {|ky,vl|
@@ -7,12 +13,19 @@ module PolyBelongsTo
       } 
     }
 
+    # Discerns which type of build command is used between obj and child
+    # @param obj [Object] ActiveRecord instance to build on
+    # @param child [Object] ActiveRecord child relation as class or instance
+    # @return [String, nil] build command for relation, or nil
     BuildCmd = lambda {|obj, child|
       return nil unless obj && child
       dup_name = CollectionProxy[obj, child]
       IsSingular[obj, child] ? "build_#{dup_name}" : IsPlural[obj, child] ? "#{dup_name}.build" : nil
     }
 
+    # Returns all has_one and has_many relationships as symbols (reflec_on_all_associations)
+    # @param obj [Object] ActiveRecord instance to reflect on
+    # @return [Array<Symbol>]
     Reflects = lambda {|obj|
       return [] unless obj
       [:has_one, :has_many].map { |has|
@@ -20,16 +33,27 @@ module PolyBelongsTo
       }.flatten
     }
 
+    # Returns all has_one and has_many relationships as class objects (reflec_on_all_associations)
+    # @param obj [Object] ActiveRecord instance to reflect on
+    # @return [Array<Object>]
     ReflectsAsClasses = lambda {|obj|
       Reflects[obj].map {|ref|
         (obj.send(ref).try(:klass) || obj.send(ref).class).name.constantize
       }
     }
     
+    # Check if the child object is a kind of child that belongs to obj
+    # @param obj [Object] ActiveRecord instance
+    # @param child [Object] ActiveRecord instance or model class
+    # @return [true, false]
     IsReflected = lambda {|obj, child|
       !!CollectionProxy[obj, child]
     }
 
+    # Plurality of object relationship (plural for has_many)
+    # @param obj [Object] ActiveRecord instance
+    # @param child [Object] ActiveRecord instance or model class
+    # @return [Symbol, nil] :plural, :singular, or nil
     SingularOrPlural = lambda {|obj, child|
       return nil unless obj && child
       reflects = Reflects[obj]
@@ -42,24 +66,44 @@ module PolyBelongsTo
       end
     }
 
+    # Singularity of object relationship (for has_one)
+    # @param obj [Object] ActiveRecord instance
+    # @param child [Object] ActiveRecord instance or model class
+    # @return [true, false]
     IsSingular = lambda {|obj, child|
       SingularOrPlural[obj, child] == :singular
     }
 
+    # Plurality of object relationship (for has_many)
+    # @param obj [Object] ActiveRecord instance
+    # @param child [Object] ActiveRecord instance or model class
+    # @return [true, false]
     IsPlural = lambda {|obj,child|
       SingularOrPlural[obj, child] == :plural
     }
 
+    # Returns the symbol of the child relation object
+    # @param obj [Object] ActiveRecord instance
+    # @param child [Object] ActiveRecord instance or model class
+    # @return [Symbol] working relation on obj
     CollectionProxy = lambda {|obj, child|
       return nil unless obj && child
       names = [ActiveModel::Naming.singular(child).to_s, ActiveModel::Naming.plural(child).to_s].uniq
       Reflects[obj].detect {|ref| "#{ref}"[/(?:#{ names.join('|') }).{,3}/]}
     }
   
+    # Returns either a ActiveRecord::CollectionProxy or a PolyBelongsTo::FakedCollection as a proxy
+    # @param obj [Object] ActiveRecord instance
+    # @param child [Object] ActiveRecord instance or model class
+    # @return [Object]
     AsCollectionProxy = lambda {|obj, child|
       return PolyBelongsTo::FakedCollection.new() unless obj && child
       return PolyBelongsTo::FakedCollection.new(obj, child) if IsSingular[obj, child]
-      !!CollectionProxy[obj, child] ? obj.send(PolyBelongsTo::Pbt::CollectionProxy[obj, child]) : []
+      if CollectionProxy[obj, child]
+        obj.send(PolyBelongsTo::Pbt::CollectionProxy[obj, child])
+      else
+        PolyBelongsTo::FakedCollection.new()
+      end
     }
   end
   

data/lib/poly_belongs_to/singleton_set.rb

@@ -1,16 +1,26 @@
 require 'set'
 module PolyBelongsTo
+  ##
+  # PolyBelongsTo::SingletonSet is a modified instance of Set for maintaining singletons of ActiveRecord objects during any recursive flow.
   class SingletonSet
+    # Creates two internal Sets
+    # @return [self]
     def initialize
       @set = Set.new
       @flagged = Set.new
       self
     end
 
+    # Takes ActiveRecord object and returns string of class name and object id
+    # @param record [Object] ActiveRecord object instance
+    # @return [String]
     def formatted_name(record)
       "#{record.class.name}-#{record.id}"
     end
 
+    # Add record to set.  Flag if covered already.
+    # @param record [Object] ActiveRecord object instance
+    # @return [Object, nil] Object if added safely, nil otherwise
     def add?(record)
       result = @set.add?( formatted_name( record ) )
       return result if result
@@ -18,20 +28,31 @@ module PolyBelongsTo
       result
     end
 
+    # Boolean of record inclusion
+    # @param record [Object] ActiveRecord object instance
+    # @return [true, false]
     def include?(record)
       return nil unless record
       @set.include?(formatted_name(record))
     end
 
+    # Add record to flagged Set list
+    # @param record [Object] ActiveRecord object instance
+    # @return [Set]
     def flag(record)
       @flagged << formatted_name(record)
     end
 
+    # Boolean of record inclusion in flagged Set
+    # @param record [Object] ActiveRecord object instance
+    # @return [true, false]
     def flagged?(record)
       return nil unless record
       @flagged.include?(formatted_name(record))
     end
 
+    # method_missing will transform any record argument into a formatted string and pass the
+    # method and arguments on to the internal Set.  Also will flag any existing records covered.
     def method_missing(mthd, *args, &block)
       new_recs = args.reduce([]) {|a, i| a.push(formatted_name(i)) if i.class.ancestors.include?(ActiveRecord::Base); a}
       result = @set.send(mthd,