deep_cloneable 1.4.0 → 3.2.1

data/readme.md

@@ -0,0 +1,242 @@
+# deep_cloneable
+
+![Build Status](https://github.com/moiristo/deep_cloneable/actions/workflows/ruby.yml/badge.svg)
+
+This gem gives every ActiveRecord::Base object the possibility to do a deep clone that includes user specified associations. It is a rails 3+ upgrade of the [deep_cloning plugin](http://github.com/openminds/deep_cloning).
+
+## Requirements
+
+- Ruby 2.3.0, 2.4.4, 2.5.5, 2.6.3, 2.7.5, 3.3.5 (tested)
+- Activerecord 3.2, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2, 6.0, 7.0, 8.0 (tested)
+- Rails 2.x/3.0 users, please check out the 'rails2.x-3.0' branch
+
+## Installation
+
+- Add deep_cloneable to your Gemfile:
+
+```ruby
+gem 'deep_cloneable', '~> 3.2.1'
+```
+
+## Upgrade details
+
+### Upgrading from v2
+
+There are two breaking changes that you might need to pay attention to:
+
+- When using an optional block (see below), the block used to be evaluated before `deep_cloneable` had performed its changes (inclusions, exclusions, includes). In v3, the block is evaluated after all processing has been done, just before the copy is about to be returned.
+- When a defined association is not found, `deep_cloneable` raises an exception. The exception class has changed namespace: the class definition used to be `ActiveRecord::Base::DeepCloneable::AssociationNotFoundException` and this has changed to `DeepCloneable::AssociationNotFoundException`.
+
+### Upgrading from v1
+
+The `dup` method with arguments has been replaced in deep_cloneable 2 by the method `deep_clone`. Please update your sources accordingly.
+
+## Usage
+
+The `deep_clone` method supports a couple options that can be specified by passing an options hash. Without options, the behaviour is the same as ActiveRecord's [`dup`](http://apidock.com/rails/ActiveRecord/Core/dup) method.
+
+### Association inclusion
+
+Associations to be included in the dup can be specified with the `include` option:
+
+```ruby
+# Single include
+pirate.deep_clone include: :mateys
+
+# Multiple includes
+pirate.deep_clone include: [ :mateys, :treasures ]
+
+# Deep includes
+pirate.deep_clone include: { treasures: :gold_pieces }
+pirate.deep_clone include: [ :mateys, { treasures: :gold_pieces } ]
+
+# Disable validation for a performance speedup when saving the dup
+pirate.deep_clone include: { treasures: :gold_pieces }, validate: false
+
+# Conditional includes
+pirate.deep_clone include: [
+  {
+    treasures: { gold_pieces: { if: lambda{|piece| piece.is_a?(Parrot) } } } },
+    mateys: { unless: lambda{|matey| matey.is_a?(GoldPiece) }
+  }
+]
+
+ship.deep_clone include: [
+  pirates: [ :treasures, :mateys, if: lambda {|pirate| pirate.name == 'Jack Sparrow' } ]
+]
+```
+
+#### The Dictionary (Object Reusage)
+
+The dictionary ensures that models are not duped multiple times when it is associated to nested models. It does this by storing a mapping of the original object to its duped object. It can be used as follows:
+
+```ruby
+# Enables the dictionary (empty on initialization)
+pirate.deep_clone include: [ :mateys, { treasures:  [ :matey, :gold_pieces ] } ], use_dictionary: true
+
+# Deep clones with a prefilled dictionary
+dictionary = { mateys: {} }
+pirate.mateys.each{|m| dict[:mateys][m] = m.deep_clone }
+pirate.deep_clone include: [ :mateys, { treasures: [ :matey, :gold_pieces ] } ], dictionary: dictionary
+```
+
+### Attribute Exceptions & Inclusions
+
+The `deep_clone` method supports both `except` and `only` for specifying which attributes should be duped:
+
+#### Exceptions
+
+```ruby
+# Single exception
+pirate.deep_clone except: :name
+
+# Multiple exceptions
+pirate.deep_clone except: [ :name, :nick_name ]
+
+# Nested exceptions
+pirate.deep_clone include: :parrot, except: [ :name, { parrot: [ :name ] } ]
+```
+
+#### Inclusions
+
+```ruby
+# Single attribute inclusion
+pirate.deep_clone only: :name
+
+# Multiple attribute inclusions
+pirate.deep_clone only: [ :name, :nick_name ]
+
+# Nested attribute inclusions
+pirate.deep_clone include: :parrot, only: [ :name, { parrot: [ :name ] } ]
+
+```
+
+### Pre- and postprocessor
+
+You can specify a pre- and/or a postprocessor to modify a duped object after duplication:
+
+```ruby
+pirate.deep_clone(include: :parrot, preprocessor: ->(original, kopy) { kopy.cloned_from_id = original.id if kopy.respond_to?(:cloned_from_id) })
+pirate.deep_clone(include: :parrot, postprocessor: ->(original, kopy) { kopy.cloned_from_id = original.id if kopy.respond_to?(:cloned_from_id) })
+```
+
+_Note_: Specifying a postprocessor is essentially the same as specifying an optional block (see below).
+
+_Note_: Using `deep_clone` with a processors will pass all associated objects that are being cloned to the processor, so be sure to check whether the object actually responds to your method of choice.
+
+### Optional Block
+
+Pass a block to `deep_clone` to modify a duped object after duplication:
+
+```ruby
+pirate.deep_clone include: :parrot do |original, kopy|
+  kopy.cloned_from_id = original.id if kopy.respond_to?(:cloned_from_id)
+end
+```
+
+_Note_: Using `deep_clone` with a block will also pass the associated objects that are being cloned to the block, so be sure to check whether the object actually responds to your method of choice.
+
+### Cloning models with files
+
+#### Carrierwave
+
+If you are cloning models that have associated files through Carrierwave these will not get transferred automatically. To overcome the issue you need to explicitly set the file attribute.
+
+Easiest solution is to add the code in a clone block as described above.
+
+```ruby
+pirate.deep_clone include: :parrot do |original, kopy|
+  kopy.thumbnail = original.thumbnail
+end
+```
+
+#### ActiveStorage
+
+For ActiveStorage, you have two options: you can either make a full copy, or share data blobs between two records.
+
+##### Full copy example
+
+```ruby
+# Rails 5.2, has_one_attached example 1
+pirate.deep_clone include: [:parrot, :avatar_attachment, :avatar_blob]
+
+# Rails 5.2, has_one_attached example 2
+pirate.deep_clone include: :parrot do |original, kopy|
+  if kopy.is_a?(Pirate) && original.avatar.attached?
+    attachment = original.avatar
+    kopy.avatar.attach \
+      :io           => StringIO.new(attachment.download),
+      :filename     => attachment.filename,
+      :content_type => attachment.content_type
+  end
+end
+
+# Rails 5.2, has_many_attached example 1 (attach one by one)
+pirate.deep_clone include: :parrot do |original, kopy|
+  if kopy.is_a?(Pirate) && original.crew_members_images.attached?
+    original.crew_members_images.each do |attachment|
+      kopy.crew_members_images.attach \
+        :io           => StringIO.new(attachment.download),
+        :filename     => attachment.filename,
+        :content_type => attachment.content_type
+    end
+  end
+end
+
+# Rails 5.2, has_many_attached example 2 (attach bulk)
+pirate.deep_clone include: :parrot do |original, kopy|
+  if kopy.is_a?(Pirate) && original.crew_members_images.attached?
+    all_attachments_arr = original.crew_members_images.map do |attachment|
+      {
+        :io           => StringIO.new(attachment.download),
+        :filename     => attachment.filename,
+        :content_type => attachment.content_type
+      }
+    end
+    kopy.crew_members_images.attach(all_attachments_arr) # attach all at once
+  end
+end
+
+# Rails 6
+pirate.deep_clone include: :parrot do |original, kopy|
+  if kopy.is_a?(Pirate) && original.avatar.attached?
+    original.avatar.open do |tempfile|
+      kopy.avatar.attach({
+        io: File.open(tempfile.path),
+        filename: original.avatar.blob.filename,
+        content_type: original.avatar.blob.content_type
+      })
+    end
+  end
+end
+```
+
+##### Shallow copy example
+
+```ruby
+pirate.deep_clone include: :parrot do |original, kopy|
+  kopy.avatar.attach(original.avatar.blob) if kopy.is_a?(Pirate) && original.avatar.attached?
+end
+```
+
+### Skipping missing associations
+
+By default, deep_cloneable will throw a `DeepCloneable::AssociationNotFoundException` error when an association cannot be found. You can also skip missing associations by specifying `skip_missing_associations` if needed, for example when you have associations on some (but not all) subclasses of an STI model:
+
+```ruby
+pirate.deep_clone include: [:parrot, :rum], skip_missing_associations: true
+```
+
+### Note on Patches/Pull Requests
+
+- Fork the project.
+- Make your feature addition or bug fix.
+- Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+- Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+- Send me a pull request. Bonus points for topic branches.
+
+### Copyright
+
+Copyright © 2024 Reinier de Lange. See LICENSE for details.

metadata

@@ -1,113 +1,79 @@
 --- !ruby/object:Gem::Specification
 name: deep_cloneable
 version: !ruby/object:Gem::Version
-  version: 1.4.0
-  prerelease: 
+  version: 3.2.1
 platform: ruby
 authors:
 - Reinier de Lange
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2012-04-02 00:00:00.000000000 Z
+date: 2024-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: deep_cloneable
+  name: activerecord
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
+        version: 3.1.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rails
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: jeweler
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
+        version: 3.1.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0'
-description: ! 'Extends the functionality of ActiveRecord::Base#clone to perform a
-  deep clone that includes user specified associations. '
-email: r.j.delange@nedforce.nl
+        version: '9'
+description: Extends the functionality of ActiveRecord::Base#dup to perform a deep
+  clone that includes user specified associations.
+email: rjdelange@icloud.com
 executables: []
 extensions: []
 extra_rdoc_files:
 - LICENSE
-- README.rdoc
 files:
-- .document
+- Appraisals
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
-- README.rdoc
 - Rakefile
-- VERSION
 - deep_cloneable.gemspec
 - init.rb
 - lib/deep_cloneable.rb
-- test/database.yml
-- test/schema.rb
-- test/test_deep_cloneable.rb
-- test/test_helper.rb
-homepage: http://github.com/moiristo/deep_cloneable
-licenses: []
-post_install_message: 
+- lib/deep_cloneable/association_not_found_exception.rb
+- lib/deep_cloneable/deep_clone.rb
+- lib/deep_cloneable/skip_validations.rb
+- lib/deep_cloneable/version.rb
+- readme.md
+homepage: https://github.com/moiristo/deep_cloneable
+licenses:
+- MIT
+metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
-      segments:
-      - 0
-      hash: -1579513982850858765
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.21
-signing_key: 
-specification_version: 3
+rubygems_version: 3.5.20
+signing_key:
+specification_version: 4
 summary: This gem gives every ActiveRecord::Base object the possibility to do a deep
   clone.
 test_files: []

data/.document

@@ -1,5 +0,0 @@
-README.rdoc
-lib/**/*.rb
-bin/*
-features/**/*.feature
-LICENSE

data/README.rdoc

@@ -1,78 +0,0 @@
-= Deep_cloneable
-
-This gem gives every ActiveRecord::Base object the possibility to do a deep clone. It is a rails3 upgrade of the deep_cloning plugin (http://github.com/openminds/deep_cloning).
-
-== Requirements
-
-* Activerecord 3.1, 3.2
-
-* Rails 2.x/3.0 users, please check out the 'rails2.x-3.0' branch.
-
-== Installation
-
-* In your Gemfile:
-
-  gem 'deep_cloneable', '~> 1.3.1'
-
-== Example
- 
-=== Cloning one single association
-   pirate.dup :include => :mateys
-
-=== Cloning multiple associations
-   pirate.dup :include => [:mateys, :treasures]
-
-=== Cloning really deep
-   pirate.dup :include => {:treasures => :gold_pieces}
-
-=== Cloning really deep with multiple associations
-   pirate.dup :include => [:mateys, {:treasures => :gold_pieces}]
-
-=== Cloning really deep with multiple associations and a dictionary
-
-A dictionary ensures that models are not cloned multiple times when it is associated to nested models. 
-When using a dictionary, ensure recurring associations are cloned first:
-
-  pirate.dup :include => [:mateys, {:treasures => [:matey, :gold_pieces], :use_dictionary => true }]    
-
-If this is not an option for you, it is also possible to populate the dictionary manually in advance:
-
-  dict = { :mateys => {} }
-  pirate.mateys.each{|m| dict[:mateys][m] = m.dup }
-  pirate.dup :include => [:mateys, {:treasures => [:matey, :gold_pieces], :dictionary => dict }]     
-  
-=== Cloning a model without an attribute
-   pirate.dup :except => :name
- 
-=== Cloning a model without multiple attributes
-   pirate.dup :except => [:name, :nick_name]
-   
-=== Cloning a model without an attribute or nested multiple attributes   
-   pirate.dup :include => :parrot, :except => [:name, { :parrot => [:name] }]
-
-=== Cloning with a block
-   pirate.dup :include => :parrot do |original, kopy|
-     kopy.cloned_from_id = original.id if kopy.respond_to?(:cloned_from_id)
-   end
-
-== Contributors
-
-* Michael He
-* Indrek Juhkam
-* Mart Karu
-* Rolf Timmermans
-* Ilya Kuzmin
-
-== Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-== Copyright
-
-Copyright (c) 2012 Reinier de Lange. See LICENSE for details.

data/VERSION

@@ -1 +0,0 @@
-1.4.0

data/test/database.yml

@@ -1,6 +0,0 @@
-sqlite: 
-  adapter: sqlite 
-  database: ":memory:"
-sqlite3: 
-  adapter: sqlite3 
-  database: ":memory:"

data/test/schema.rb

@@ -1,52 +0,0 @@
-ActiveRecord::Schema.define(:version => 1) do
-  create_table :pirates, :force => true do |t|
-    t.column :name, :string
-    t.column :nick_name, :string, :default => 'no nickname'
-    t.column :age, :string
-    t.column :ship_id, :integer
-    t.column :ship_type, :string
-  end
-  
-  create_table :parrots, :force => true do |t|
-    t.column :name, :string
-    t.column :pirate_id, :integer
-  end
-  
-  create_table :mateys, :force => true do |t|
-    t.column :name, :string
-    t.column :pirate_id, :integer
-  end
-  
-  create_table :treasures, :force => true do |t|
-    t.column :found_at, :string
-    t.column :owner, :integer
-    t.column :matey_id, :integer    
-  end
-  
-  create_table :gold_pieces, :force => true do |t|
-    t.column :treasure_id, :integer
-  end
-  
-  create_table :battle_ships, :force => true do |t|
-    t.column :name, :string
-  end  
-  
-  create_table :pigs, :force => true do |t|
-    t.column :name, :string
-    t.column :human_id, :integer
-  end
-  
-  create_table :humen, :force => true do |t|
-    t.column :name, :string
-  end
-  
-  create_table :chickens, :force => true do |t|
-    t.column :name, :string
-  end  
-  
-  create_table :ownerships, :force => true do |t|
-    t.column :human_id, :integer
-    t.column :chicken_id, :integer    
-  end  
-  
-end

data/test/test_deep_cloneable.rb

@@ -1,162 +0,0 @@
-require File.dirname(__FILE__) + '/test_helper'
-
-class TestDeepCloneable < Test::Unit::TestCase
-  load_schema
-  
-  @@clone_method = ActiveRecord::VERSION::MAJOR >= 3 && ActiveRecord::VERSION::MINOR > 0 ? :dup : :clone  
-
-  def setup    
-    @jack  = Pirate.create(:name => 'Jack Sparrow', :nick_name => 'Captain Jack', :age => 30)
-    @polly = Parrot.create(:name => 'Polly', :pirate => @jack)
-    @john = Matey.create(:name => 'John', :pirate => @jack)
-    @treasure = Treasure.create(:found_at => 'Isla del Muerte', :pirate => @jack, :matey => @john)
-    @gold_piece = GoldPiece.create(:treasure => @treasure)
-    @ship = BattleShip.create(:name => 'Black Pearl', :pirates => [@jack])
-  end
-
-  def test_single_dup_exception
-    dup = @jack.send(@@clone_method, :except => :name)
-    assert dup.save
-    assert_equal @jack.name, @jack.send(@@clone_method).name # Old behaviour
-    assert_nil dup.name
-    assert_equal @jack.nick_name, dup.nick_name
-  end
-
-  def test_multiple_dup_exception
-    dup = @jack.send(@@clone_method, :except => [:name, :nick_name])
-    assert dup.save
-    assert_nil dup.name
-    assert_equal 'no nickname', dup.nick_name
-    assert_equal @jack.age, dup.age
-  end
-
-  def test_single_include_association
-    dup = @jack.send(@@clone_method, :include => :mateys)
-    assert dup.save
-    assert_equal 1, dup.mateys.size
-  end
-
-  def test_single_include_belongs_to_polymorphic_association
-    dup = @jack.send(@@clone_method, :include => :ship)
-    assert dup.save
-    assert_not_nil dup.ship
-    assert_not_equal @jack.ship, dup.ship
-  end
-
-  def test_single_include_has_many_polymorphic_association
-    dup = @ship.send(@@clone_method, :include => :pirates)
-    assert dup.save
-    assert dup.pirates.any?
-  end
-
-  def test_multiple_include_association
-    dup = @jack.send(@@clone_method, :include => [:mateys, :treasures])
-    assert dup.save
-    assert_equal 1, dup.mateys.size
-    assert_equal 1, dup.treasures.size
-  end
-
-  def test_deep_include_association
-    dup = @jack.send(@@clone_method, :include => {:treasures => :gold_pieces})
-    assert dup.save
-    assert_equal 1, dup.treasures.size
-    assert_equal 1, dup.gold_pieces.size
-  end
-
-  def test_include_association_assignments
-    dup = @jack.send(@@clone_method, :include => :treasures)
-
-    dup.treasures.each do |treasure|
-      assert_equal dup, treasure.pirate
-    end
-  end
-
-  def test_multiple_and_deep_include_association
-    dup = @jack.send(@@clone_method, :include => {:treasures => :gold_pieces, :mateys => {}})
-    assert dup.save
-    assert_equal 1, dup.treasures.size
-    assert_equal 1, dup.gold_pieces.size
-    assert_equal 1, dup.mateys.size
-  end
-
-  def test_multiple_and_deep_include_association_with_array
-    dup = @jack.send(@@clone_method, :include => [{:treasures => :gold_pieces}, :mateys])
-    assert dup.save
-    assert_equal 1, dup.treasures.size
-    assert_equal 1, dup.gold_pieces.size
-    assert_equal 1, dup.mateys.size
-  end
-
-  def test_with_belongs_to_relation
-    dup = @jack.send(@@clone_method, :include => :parrot)
-    assert dup.save
-    assert_not_equal dup.parrot, @jack.parrot
-  end
-
-  def test_should_pass_nested_exceptions
-    dup = @jack.send(@@clone_method, :include => :parrot, :except => [:name, { :parrot => [:name] }])
-    assert dup.save
-    assert_not_equal dup.parrot, @jack.parrot
-    assert_not_nil @jack.parrot.name
-    assert_nil dup.parrot.name
-  end
-
-  def test_should_not_double_dup_when_using_dictionary
-    current_matey_count = Matey.count
-    dup = @jack.send(@@clone_method, :include => [:mateys, { :treasures => :matey }], :use_dictionary => true)
-    dup.save!
-
-    assert_equal current_matey_count + 1, Matey.count
-  end
-
-  def test_should_not_double_dup_when_using_manual_dictionary
-    current_matey_count = Matey.count
-
-    dict = { :mateys => {} }
-    @jack.mateys.each{|m| dict[:mateys][m] = m.send(@@clone_method) }
-
-    dup = @jack.send(@@clone_method, :include => [:mateys, { :treasures => :matey }], :dictionary => dict)
-    dup.save!
-
-    assert_equal current_matey_count + 1, Matey.count
-  end
-
-  def test_should_support_ar_class_under_module
-    @human = Animal::Human.create :name => "Michael"
-    @pig = Animal::Pig.create :human => @human, :name => 'big pig'
-
-    dup_human = @human.send(@@clone_method, :include => [:pigs])
-    assert dup_human.save
-    assert_equal 1, dup_human.pigs.count
-    
-    @human2 = Animal::Human.create :name => "John"
-    @pig2 = @human2.pigs.create :name => 'small pig'
-    
-    dup_human_2 = @human.send(@@clone_method, :include => [:pigs])
-    assert dup_human_2.save
-    assert_equal 1, dup_human_2.pigs.count
-  end 
-  
-  def test_should_dup_many_to_many_associations
-    @human = Animal::Human.create :name => "Michael" 
-    @human2 = Animal::Human.create :name => "Jack"        
-    @chicken1 = Animal::Chicken.create :name => 'Chick1'
-    @chicken2 = Animal::Chicken.create :name => 'Chick2'    
-    @human.chickens << [@chicken1, @chicken2]
-    @human2.chickens << [@chicken1, @chicken2]    
-    
-    dup_human = @human.send(@@clone_method, :include => :ownerships)
-    assert dup_human.save
-    assert_equal 2, dup_human.chickens.count    
-  end 
-  
-  def test_should_dup_with_block
-    dup = @jack.send(@@clone_method, :include => :parrot) do |original, kopy|
-      kopy.cloned_from_id = original.id
-    end
-
-    assert dup.save
-    assert_equal @jack.id, dup.cloned_from_id
-    assert_equal @jack.parrot.id, dup.parrot.cloned_from_id
-  end
-end