prim 0.0.1

data/lib/prim.rb

@@ -0,0 +1,40 @@
+require "active_support/core_ext/object/try"
+require "prim/connector"
+require "prim/helpers"
+require "prim/railtie" if defined?(Rails)
+require "prim/relationship"
+
+module Prim
+  class << self
+    attr_accessor :configured_primaries
+    def configured_primaries
+      @configured_primaries ||= Array.new
+    end
+  end
+
+  module ClassMethods
+    include Prim::Helpers
+
+    def has_primary name, options = {}
+      singular_name    = name.to_sym
+      association_name = plural_sym(singular_name)
+
+      self.prim_relationships = self.prim_relationships.try(:dup) || Hash.new
+      self.prim_relationships[ singular_name ] = Prim::Relationship.new(association_name, self, options)
+
+      # Store this configuration for global access.
+      Prim.configured_primaries << self.prim_relationships[ singular_name ]
+
+      define_method "primary_#{ singular_name }" do
+        get_primary(singular_name)
+      end
+
+      define_method "primary_#{ singular_name }=" do |record|
+        assign_primary(singular_name, record)
+      end
+    end
+  end
+
+  class SingularAssociationError < StandardError; end
+  class MissingColumnError < StandardError; end
+end

data/lib/prim/callbacks.rb

@@ -0,0 +1,30 @@
+module Prim
+  module Callbacks
+    def self.included(base)
+      base.send :extend,  Defining
+      base.send :include, Running
+    end
+
+    module Defining
+      def define_prim_callbacks(*callbacks)
+        define_callbacks *[callbacks, { terminator: "result == false" }].flatten
+        callbacks.each do |callback|
+          eval <<-end_callbacks
+            def before_#{callback}(*args, &blk)
+              set_callback(:#{callback}, :before, *args, &blk)
+            end
+            def after_#{callback}(*args, &blk)
+              set_callback(:#{callback}, :after, *args, &blk)
+            end
+          end_callbacks
+        end
+      end
+    end
+
+    module Running
+      def run_prim_callbacks(callback, &block)
+        run_callbacks(callback, &block)
+      end
+    end
+  end
+end

data/lib/prim/collection.rb

@@ -0,0 +1,76 @@
+module Prim
+  # Collection largely wraps an association collection (like a Relation) but adds
+  # the concept of a primary member. Collections can only exist in the context of
+  # a Relationship (see Prim::Relationship for more info) and an `owner` instance,
+  # and contain mapping records.
+  class Collection
+
+    # The members of a Collection are not necessarily the "source" records, or
+    # the Tags if a Post `has_many :tags`. If a mapping table (say, "taggings")
+    # lies between Post and Tag, a Collection's members will be Taggings instead.
+    attr_reader :instance, :relationship, :members
+
+    def initialize relationship, instance
+      @instance     = instance
+      @relationship = relationship
+    end
+
+    def primary
+      sources.where( relationship.through_reflection.name => { primary: true } ).first
+    end
+
+    def primary= source_record
+      mapping = mapping_for(source_record)
+
+      if source_record.persisted?
+        if mapping.nil?
+          create_mapping!(source_record)
+
+        elsif !mapping.primary?
+          mapping.update_attributes(primary: true)
+        end
+
+      else
+        create_source_record!(source_record)
+      end
+
+      true
+    end
+
+    private
+
+    # Creates a new source record and a mapping between it and the owner instance.
+    def create_source_record! source_record
+      if source_record.save
+        create_mapping!(source_record)
+      else
+        false
+      end
+    end
+
+    def create_mapping! source_record
+      mappings.create( relationship.foreign_key => source_record.id, primary: true )
+    end
+
+    def mappings force_reload = false
+      instance.send( relationship.collection_method, force_reload )
+    end
+
+    def sources force_reload = false
+      instance.send( relationship.association_name, force_reload )
+    end
+
+    # Returns the mapping for a given source record. If this Relationship doesn't
+    # involve a mapping table, returns the source record itself.
+    def mapping_for source_record
+      if relationship.mapping_table?
+        mappings.detect do |member|
+          member[ relationship.source_reflection.foreign_key ] == source_record.id
+        end
+
+      else
+        source_record
+      end
+    end
+  end
+end

data/lib/prim/connector.rb

@@ -0,0 +1,12 @@
+require "prim/instance_methods"
+
+module Prim
+  module Connector
+    def self.included base
+      base.send :extend,  ClassMethods
+      base.send :include, InstanceMethods::Owner
+      
+      base.class_attribute :prim_relationships
+    end
+  end
+end

data/lib/prim/helpers.rb

@@ -0,0 +1,13 @@
+require 'active_support/inflector/methods'
+
+module Prim
+  module Helpers
+    def plural_sym singular_sym
+      singular_sym.to_s.pluralize.to_sym
+    end
+
+    def singular_sym plural_sym
+      plural_sym.to_s.singularize.to_sym
+    end
+  end
+end

data/lib/prim/instance_methods.rb

@@ -0,0 +1,39 @@
+require 'prim/collection'
+require 'active_support/concern'
+
+module Prim
+  module InstanceMethods
+
+    module Owner
+      def get_primary singular_name
+        collection_for(singular_name).primary
+      end
+
+      def assign_primary singular_name, instance
+        collection_for(singular_name).primary = instance
+      end
+
+      def collection_for singular_name
+        @_prim_collections ||= {}
+        @_prim_collections[ singular_name ] ||= Prim::Collection.new(self.class.prim_relationships[ singular_name ], self)
+      end
+    end
+
+    module Reflected
+      extend ActiveSupport::Concern
+
+      included do
+
+        validate :only_one_primary
+
+        def only_one_primary
+          if self[:primary]
+            siblings.update_all('"primary" = false')
+          end
+        end
+
+      end
+    end
+
+  end
+end

data/lib/prim/primary.rb

@@ -0,0 +1,11 @@
+module Prim
+  class Primary
+    attr_reader :relationship, :record
+
+    def initialize relationship, record
+      @relationship = relationship
+      @record = record
+      
+    end
+  end
+end

data/lib/prim/railtie.rb

@@ -0,0 +1,13 @@
+require "prim"
+
+module Prim
+  require "rails"
+
+  class Railtie < Rails::Railtie
+    initializer "prim.insert_into_active_record" do |app|
+      ActiveSupport.on_load :active_record do
+        ActiveRecord::Base.send(:include, Prim::Connector) if defined?(ActiveRecord)
+      end
+    end
+  end
+end

data/lib/prim/relationship.rb

@@ -0,0 +1,113 @@
+module Prim
+  # This class largely wraps ActiveRecord::Reflection::MacroReflection and its subclasses.
+  # A Relationship encapsulates the interaction among the two or three classes involved in
+  # a one-to-many or many-to-many model association, and reconfigures these classes to
+  # make handling primary members of those associations simple.
+  class Relationship
+
+    attr_reader :reflection, :owning_class, :association_name, :options
+    delegate :source_reflection, :through_reflection, :foreign_key, to: :reflection
+
+    def initialize association_name, owning_class, options = {}
+      @options = extract_options options
+      @association_name = association_name
+      @owning_class = owning_class
+      @reflection   = owning_class.reflect_on_association( association_name )
+
+      if reflection.nil?
+        raise ArgumentError.new("Prim: Association '#{ association_name }' not found " +
+          "on #{ owning_class.name }. Perhaps you misspelled it?")
+      
+      elsif !reflection.collection?
+        raise SingularAssociationError.new("Prim: Association '#{ association_name }' " +
+          "is not a one-to-many or many-to-many relationship, so it can't have a primary.")
+
+      elsif !reflected_column_names.include? "primary"
+        raise MissingColumnError.new("Prim: #{ owning_class.name } needs table " +
+          "`#{ mapping_reflection.table_name }` to have a boolean 'primary' column in " +
+          "order to have a primary #{ source_class.name }.")
+      end
+
+      # TODO: ensure the association isn't nested?
+
+      configure_reflected_class!
+
+      true
+    end
+
+    def configure_reflected_class!
+      foreign_key  = mapping_reflection.foreign_key
+      mapping_type = mapping_reflection.type
+
+      load_siblings = lambda do
+        primary_key = self.class.primary_key
+        query = self.class.where( foreign_key => self[ foreign_key ] )
+
+        if mapping_type
+          query = query.where( mapping_type => self[ mapping_type ] )
+        end
+
+        query.where( self.class.arel_table[ primary_key ].not_eq(self[ primary_key ]) )
+      end
+
+      reflected_class.class_eval do
+        define_method :siblings, &load_siblings
+      end
+
+      reflected_class.send :include, InstanceMethods::Reflected
+    end
+
+    # The association method to call on the owning class to retrieve a record's collection.
+    def collection_method
+      options[:through] || mapping_reflection.plural_name
+    end
+
+    # The class of the reflection source: i.e. Post if the owning class `has_many :posts`.
+    def source_class
+      source_reflection.klass
+    end
+
+    # The class of the `mapping_reflection`.
+    def reflected_class
+      mapping_reflection.klass
+    end
+
+    # The association reflection representing the link between the owning class and the
+    # mapping class, whether or not the mapping class represents a join-table.
+    def mapping_reflection
+      through_reflection || source_reflection
+    end
+
+    # True if the `mapping_reflection` class has an "inverse" mapping back to the owning
+    # class with a matching name. Verifies that a polymorphic mapping exists.
+    # def polymorphic_mapping?
+    #   if polymorphic_as.present?
+    #     !!reflected_class.reflect_on_all_associations.detect do |refl|
+    #       refl.name == polymorphic_as and refl.association_class == ActiveRecord::Associations::BelongsToPolymorphicAssociation
+    #     end
+    #   end
+    # end
+
+    # The name the owning class uses to create mappings in the reflected class; i.e. the
+    # `:as` option set on the `has_many` association in the owner.
+    # def reflection_polymorphic_as
+    #   mapping_reflection.options[:as].to_sym
+    # end
+
+    # True if this relationship relies on a mapping table for `primary` records.
+    def mapping_table?
+      !!through_reflection
+    end
+
+    private
+
+    # The columns of the reflected class (where `primary` needs to be).
+    def reflected_column_names
+      reflected_class.column_names
+    end
+
+    def extract_options options
+      options
+    end
+  end
+end

data/prim.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |s|
+  s.name        = "prim"
+  s.version     = "0.0.1"
+  s.date        = "2012-12-19"
+  s.summary     = "Easily manage Rails associations that need a primary member."
+  s.description = "Prim makes it dead simple to add a primary member to any Rails one-to-many or many-to-many association. 
+                  Just add a short configuration to a model, generate and run a migration, and you're all set."
+  s.authors     = [ "Piers Mainwaring" ]
+  s.email       = "piers@impossibly.org"
+  s.files       = `git ls-files`.split("\n")
+  s.homepage    = "https://github.com/orcahealth/prim"
+
+  s.require_paths = [ "lib" ]
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: prim
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Piers Mainwaring
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-19 00:00:00.000000000 Z
+dependencies: []
+description: ! "Prim makes it dead simple to add a primary member to any Rails one-to-many
+  or many-to-many association. \n                  Just add a short configuration
+  to a model, generate and run a migration, and you're all set."
+email: piers@impossibly.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/prim.rb
+- lib/prim/callbacks.rb
+- lib/prim/collection.rb
+- lib/prim/connector.rb
+- lib/prim/helpers.rb
+- lib/prim/instance_methods.rb
+- lib/prim/primary.rb
+- lib/prim/railtie.rb
+- lib/prim/relationship.rb
+- lib/tasks/prim.rake
+- prim.gemspec
+homepage: https://github.com/orcahealth/prim
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Easily manage Rails associations that need a primary member.
+test_files: []