copyable 0.0.1

data/lib/copyable/copyable_extension.rb

@@ -0,0 +1,118 @@
+module Copyable
+  module CopyableExtension
+
+    def self.included(klass)
+      klass.extend ClassMethods
+    end
+
+    module ClassMethods
+
+      # Use this copyable declaration in an ActiveRecord model to instruct
+      # the model how to copy itself.  This declaration will create a
+      # create_copy! method that follows the instructions in the copyable
+      # declaration.
+      def copyable(&block)
+
+        begin
+          model_class = self
+          # raise an error if the copyable declaration is stated incorrectly
+          SyntaxChecker.check!(model_class, block)
+          # "execute" the copyable declaration, which basically saves the
+          # information listed in the declaration for later use by the
+          # create_copy! method
+          main = Declarations::Main.new
+          main.execute(block)
+        rescue => e
+          # if suppressing schema errors, don't raise an error, but also don't define a create_copy! method since it would have broken behavior
+          return if (e.is_a?(Copyable::ColumnError) || e.is_a?(Copyable::AssociationError) || e.is_a?(ActiveRecord::StatementInvalid)) && Copyable.config.suppress_schema_errors == true
+          raise
+        end
+
+        # define a create_copy! method for use on model objects
+        define_method(:create_copy!) do |options={}|
+
+          # raise an error if passed invalid options
+          OptionChecker.check!(options)
+
+          # we basically wrap the method in a lambda to help us manage
+          # running it in a transaction
+          do_the_copy = lambda do |options|
+            new_model = nil
+            begin
+              # start by disabling all callbacks and observers (except for
+              # validation callbacks and observers)
+              ModelHooks.disable!(model_class)
+              # rename self for clarity
+              original_model = self
+              # create a brand new, empty model
+              new_model = model_class.new
+              # fill in each column of this brand new model according to the
+              # instructions given in the copyable declaration
+              column_overrides = options[:override] || {}
+              Declarations::Columns.execute(main.column_list, original_model, new_model, column_overrides)
+              # save that sucker!
+              Copyable::Saver.save!(new_model, options[:skip_validations])
+              # tell the registry that we've created a new model (the registry
+              # helps keep us from creating another copy of a model we've
+              # already copied)
+              CopyRegistry.register(original_model, new_model)
+              # for this brand new model, visit all of the associated models,
+              # making new copies according to the instructions in the copyable
+              # declaration
+              Declarations::Associations.execute(main.association_list, original_model, new_model, options[:skip_validations])
+              # run the after_copy block if it exists
+              Declarations::AfterCopy.execute(main.after_copy_block, original_model, new_model)
+            ensure
+              # it's critically important to re-enable the callbacks and
+              # observers or they will stay disabled for future web
+              # requests
+              ModelHooks.reenable!(model_class)
+            end
+            # it's polite to return the newly created model
+            new_model
+          end
+
+
+          # create_copy! can end up calling itself (by copying associations).
+          # There is some behavior that we want to be slightly different if
+          # create_copy! is called from within another create_copy! call.
+          # (This means that any create_copy! call in copyable's internal
+          # code should pass { __called_recursively: true } to create_copy!.
+          if options[:__called_recursively]
+            do_the_copy.call(options)
+          else
+            # Imagine the case where you have a model hierarchy such as
+            # a Book that has many Sections that has many Pages.
+            #
+            # When @book.create_copy! is called, the CopyRegistry will keep
+            # track of all of the copied models, making sure no model is
+            # re-duplicated (such as in an unusual case where book sections
+            # actually overlapped, and therefore two different sections
+            # contained some of the same pages--you wouldn't want to re-copy
+            # the pages).
+            #
+            # If we don't clear the registry before we start @book.create_copy!,
+            # then we can't do this:
+            #
+            #    copy1 = @book.create_copy!
+            #    copy2 = @book.create_copy!
+            #
+            # since when copying copy2, the CopyRegistry will remember the
+            # Sections and Pages that it copied for copy1 and therefore
+            # they won't get recopied.  So we have to clear the CopyRegistry's
+            # memory each time before create_copy! is called.
+            CopyRegistry.clear
+            # Nested transactions can end up swallowing ActiveRecord::Rollback
+            # errors in surprising ways.  create_copy! can eventually call
+            # create_copy! when copying associated objects, which can result
+            # in nested transactions.  We use this option to avoid the nesting.
+            ActiveRecord::Base.transaction do
+              do_the_copy.call(options)
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/copyable/declarations/after_copy.rb

@@ -0,0 +1,15 @@
+module Copyable
+  module Declarations
+    class AfterCopy < Declaration
+
+      def self.execute(after_copy_block, original_model, new_model)
+        after_copy_block.call(original_model, new_model) if after_copy_block
+      end
+
+      def self.required?
+        false
+      end
+
+    end
+  end
+end

data/lib/copyable/declarations/associations.rb

@@ -0,0 +1,116 @@
+module Copyable
+  module Declarations
+    class Associations < Declaration
+
+      class << self
+
+        # this is the algorithm for copying associated records according to the
+        # instructions given in the copyable declaration
+        def execute(association_list, original_model, new_model, skip_validations)
+          @skip_validations = skip_validations
+          association_list.each do |assoc_name, advice|
+            association = original_model.class.reflections[assoc_name.to_sym]
+            check_advice(association, advice, original_model)
+            unless advice == :do_not_copy
+              copy_association(association, original_model, new_model)
+            end
+          end
+        end
+
+      private
+
+        def check_advice(association, advice, original_model)
+          if ![:copy, :do_not_copy, :copy_only_habtm_join_records].include?(advice)
+            message = "Error in copyable:associations of "
+            message << "#{original_model.class.name}: the association '#{association.name}' "
+            message << "has unrecognized advice '#{advice}'."
+            raise AssociationError.new(message)
+          end
+          if association.macro == :has_and_belongs_to_many && advice == :copy
+            message = "Error in copyable:associations of "
+            message << "#{original_model.class.name}: the association '#{association.name}' "
+            message << "only supports the :copy_only_habtm_join_records advice, not the :copy advice, "
+            message << "because it is a has_and_belongs_to_many association."
+            raise AssociationError.new(message)
+          end
+          if association.macro != :has_and_belongs_to_many && advice == :copy_only_habtm_join_records
+            message = "Error in copyable:associations of "
+            message << "#{original_model.class.name}: the association '#{association.name}' "
+            message << "only supports the :copy advice, not the :copy_only_habtm_join_records advice, "
+            message << "because it is not a has_and_belongs_to_many association."
+            raise AssociationError.new(message)
+          end
+        end
+
+        def copy_association(association, original_model, new_model)
+          case association.macro
+          when :has_many
+            copy_has_many(association, original_model, new_model)
+          when :has_one
+            copy_has_one(association, original_model, new_model)
+          when :has_and_belongs_to_many
+            copy_habtm(association, original_model, new_model)
+          else
+            raise "Unsupported association #{association.macro}" # should never happen, since we filter out belongs_to
+          end
+        end
+
+        def copy_has_many(association, original_model, new_model)
+          original_model.send(association.name).each do |child|
+            copy_record(association, child, new_model)
+          end
+        end
+
+        def copy_has_one(association, original_model, new_model)
+          child = original_model.send(association.name)
+          copy_record(association, child, new_model) if child
+        end
+
+        def copy_habtm(association, original_model, new_model)
+          original_model.send(association.name).each do |child|
+            new_model.send(association.name) << child
+          end
+        end
+
+        def copy_record(association, original_record, parent_model)
+          if SingleCopyEnforcer.can_copy?(original_record)
+            if original_record.respond_to? :create_copy!
+              copied_record = original_record.create_copy!(
+                override: { association.foreign_key => parent_model.id },
+                __called_recursively: true,
+                skip_validations: @skip_validations)
+            else
+              message = "Could not copy #{parent_model.class.name}#id:#{parent_model.id} "
+              message << "because #{original_record.class.name} does not have a copyable declaration."
+              raise Copyable::CopyableError.new(message)
+            end
+          else
+            copied_record = CopyRegistry.fetch_copy(record: original_record)
+            copied_record.update_column(association.foreign_key, parent_model.id)
+          end
+          update_other_belongs_to_associations(association.foreign_key, copied_record)
+        end
+
+        def update_other_belongs_to_associations(already_updated_key, copied_record)
+          copied_record.class.reflect_on_all_associations(:belongs_to).each do |assoc|
+            next if assoc.foreign_key == already_updated_key
+            id = copied_record.send(assoc.foreign_key)
+            if id
+              if assoc.options.key? :polymorphic
+                klass = copied_record.send("#{assoc.name}_type").constantize
+              else
+                klass = assoc.klass
+              end
+              copied_child = CopyRegistry.fetch_copy(class: klass, id: id)
+              if copied_child
+                copied_record.update_column(assoc.foreign_key, copied_child.id)
+              end
+            end
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/copyable/declarations/columns.rb

@@ -0,0 +1,34 @@
+module Copyable
+  module Declarations
+    class Columns < Declaration
+
+      # this is the algorithm for copying columns from the original record
+      # to the brand new copy of the record according to the instructions
+      # given in the copyable declaration
+      def self.execute(column_list, original_model, new_model, overrides)
+        column_list.each do |column, advice|
+          # when create_copy! is called, you can pass in a hash of
+          # overrides that trumps the instructions in the copyable
+          # declaration
+          if overrides[column.to_sym].present?
+            value = overrides[column.to_sym]
+          elsif overrides[column.to_s].present?
+            value = overrides[column.to_s]
+          elsif advice == :copy
+            value = original_model.send(column)
+          elsif advice == :do_not_copy
+            value = nil
+          elsif advice.is_a? Proc
+            value = advice.call(original_model)
+          else
+            message = "Error in copyable:columns of #{original_model.class.name}: "
+            message << "the column '#{column}' must be :copy, :do_not_copy, or a lambda."
+            raise ColumnError.new(message)
+          end
+          new_model.send("#{column}=", value)
+        end
+      end
+
+    end
+  end
+end

data/lib/copyable/declarations/declaration.rb

@@ -0,0 +1,15 @@
+module Copyable
+  module Declarations
+    class Declaration
+
+      def self.method_name
+        self.name.demodulize.underscore
+      end
+
+      def self.required?
+        true
+      end
+
+    end
+  end
+end

data/lib/copyable/declarations/declarations.rb

@@ -0,0 +1,14 @@
+module Copyable
+  module Declarations
+
+    ALL = [ DisableAllCallbacksAndObserversExceptValidate,
+            Columns,
+            Associations,
+            AfterCopy ]
+
+    def self.include?(method_name)
+      ALL.map(&:method_name).include?(method_name.to_s)
+    end
+
+  end
+end

data/lib/copyable/declarations/disable_all_callbacks_and_observers_except_validate.rb

@@ -0,0 +1,9 @@
+module Copyable
+  module Declarations
+    class DisableAllCallbacksAndObserversExceptValidate < Declaration
+
+      # intentionally left blank
+
+    end
+  end
+end

data/lib/copyable/declarations/main.rb

@@ -0,0 +1,32 @@
+module Copyable
+  module Declarations
+    class Main
+
+      attr_reader :column_list, :association_list, :after_copy_block
+
+      def execute(block)
+        self.instance_eval(&block)
+      end
+
+      # This declaration doesn't actually *do* anything.  It exists
+      # so that any copyable declaration must explicitly state that
+      # callbacks and observers are skipped (to make it easier to reason
+      # about the code when it is read).
+      def disable_all_callbacks_and_observers_except_validate
+      end
+
+      def columns(columns)
+        @column_list = columns
+      end
+
+      def associations(associations)
+        @association_list = associations
+      end
+
+      def after_copy(&block)
+        @after_copy_block = block
+      end
+
+    end
+  end
+end

data/lib/copyable/exceptions.rb

@@ -0,0 +1,10 @@
+module Copyable
+
+  class CopyableError < StandardError; end
+
+  class DeclarationError < CopyableError; end
+  class ColumnError < CopyableError; end
+  class AssociationError < CopyableError; end
+  class CallbackError < CopyableError; end
+
+end

data/lib/copyable/model_hooks.rb

@@ -0,0 +1,40 @@
+module Copyable
+  class ModelHooks
+
+    # Disabling callbacks automatically disables any registered observers,
+    # since observers use the callback mechanism internally.
+
+    def self.disable!(klass)
+      disable_all_callbacks(klass)
+    end
+
+    def self.reenable!(klass)
+      reenable_all_callbacks(klass)
+    end
+
+  private
+
+    def self.disable_all_callbacks(klass)
+      klass.class_eval do
+        alias_method :__disabled__run_callbacks, :run_callbacks
+        # We are violently duck-punching ActiveRecord because ActiveRecord
+        # gives us no way to turn off callbacks.  My apologies to the
+        # squeamish.
+        def run_callbacks(kind, *args, &block)
+          if block_given?
+            yield
+          else
+            true
+          end
+        end
+      end
+    end
+
+    def self.reenable_all_callbacks(klass)
+      klass.class_eval do
+        alias_method :run_callbacks, :__disabled__run_callbacks
+      end
+    end
+
+  end
+end

data/lib/copyable/option_checker.rb

@@ -0,0 +1,23 @@
+module Copyable
+  class OptionChecker
+
+    VALID_OPTIONS = [:override, :skip_validations]
+    VALID_PRIVATE_OPTIONS = [:__called_recursively]  # for copyable's internal use only
+
+    def self.check!(options)
+      unrecognized_options = options.keys - VALID_OPTIONS - VALID_PRIVATE_OPTIONS
+      if unrecognized_options.any?
+        message = "Unrecognized options passed to create_copy!:\n"
+        unrecognized_options.each do |opt|
+          message << "  #{opt.inspect}\n"
+        end
+        message << "The options passed to create_copy! can only be one of the following:\n"
+        VALID_OPTIONS.each do |opt|
+          message << "  #{opt.inspect}\n"
+        end
+        raise CopyableError.new(message)
+      end
+    end
+
+  end
+end

data/lib/copyable/railtie.rb

@@ -0,0 +1,9 @@
+module Copyable
+  class Railtie < Rails::Railtie
+    railtie_name :copyable
+
+    rake_tasks do
+      load "tasks/copyable.rake"
+    end
+  end
+end