clowne 0.1.0.pre1 → 0.1.0

data/docs/execution_order.md

@@ -0,0 +1,14 @@
+---
+id: execution_order
+title: Execution Order
+---
+
+The order of cloning actions depends on the adapter (i.e., could be customized).
+
+All built-in adapters have the same order:
+- init clone (see [`init_as`](init_as.md))
+- clone associations
+- nullify attributes
+- run [`finalize`](finalize.md) blocks
+
+The order of [`finalize`](finalize.md) blocks is the order they've been written.

data/docs/finalize.md

@@ -0,0 +1,35 @@
+---
+id: finalize
+title: Finalization
+sidebar_label: Finalize
+---
+
+To apply custom transformations to the cloned record, you can use the `finalize` declaration:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  finalize do |_source, record, _params|
+    record.name = 'This is copy!'
+  end
+
+  trait :change_email do
+    finalize do |_source, record, params|
+      record.email = params[:email]
+    end
+  end
+end
+
+clone = UserCloner.call(user)
+clone.name
+# => 'This is copy!'
+clone.email == 'clone@example.com'
+# => false
+
+clone2 = UserCloner.call(user, traits: :change_email)
+clone2.name
+# => 'This is copy!'
+clone2.email
+# => 'clone@example.com'
+```
+
+Finalization blocks are called at the end of the [cloning process](execution_order.md).

data/docs/implicit_cloner.md

@@ -0,0 +1,36 @@
+---
+id: implicit_cloner
+title: Implicit Cloner
+---
+
+When [cloning associations](include_association.md) Clowne tries to infer an appropriate cloner class for the records (unless `clone_with` specified).
+
+It relies on the naming convention: `MyModel` -> `MyModelCloner`.
+
+Consider an example:
+
+```ruby
+class User < ActiveRecord::Base
+  has_one :profile
+end
+
+class UserCloner < Clowne::Cloner
+  include_association :profile
+end
+
+class ProfileCloner < Clowne::Cloner
+  finalize do |source, record|
+    record.name = "Clone of #{source.name}"
+  end
+end
+
+user = User.last
+user.profile.name
+#=> "Bimbo"
+
+cloned = UserCloner.call(user)
+cloned.profile.name
+# => "Clone of Bimbo"
+```
+
+**NOTE:** when using [in-model cloner](active_record.md) for ActiveRecord it is used by default.

data/docs/include_association.md

@@ -0,0 +1,119 @@
+---
+id: include_association
+title: Include Association
+---
+
+Use this declaration to clone model's associations:
+
+```ruby
+class User < ActiveRecord::Base
+  has_one :profile
+end
+
+class UserCloner < Clowne::Cloner
+  include_association :profile
+end
+```
+
+Looks pretty simple, right? But that's not all we may offer you! :)
+
+The declaration supports additional arguments:
+
+```ruby
+include_association name, scope, options
+```
+
+## Scope
+
+Scope can be a:
+- `Symbol` - named scope
+- `Proc` - custom scope (supports parameters).
+
+Example:
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :accounts
+  has_many :posts
+end
+
+class Account < ActiveRecord::Base
+  scope :active, -> { where(active: true) }
+end
+
+class Post < ActiveRecord::Base
+  # t.string :status
+end
+
+class UserCloner < Clowne::Cloner
+  include_association :accounts, :active
+  include_association :posts, ->(params) { where(state: params[:status]) if params[:status] }
+end
+
+# Clone only draft posts
+UserCloner.call(user, status: :draft)
+# => <#User...
+```
+
+## Options
+
+The following options are available:
+- `:clone_with` - use custom cloner\*
+- `:traits` - define special traits.
+
+\* **NOTE:** the same cloner class would be used for **all children**
+
+Example:
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :posts
+end
+
+class Post < ActiveRecord::Base
+  # t.string :title
+  has_many :tags
+end
+```
+
+```ruby
+class PostSpecialCloner < Clowne::Cloner
+  nullify :title
+
+  trait :with_tags do
+    include_association :tags
+  end
+end
+
+class UserCloner < Clowne::Cloner
+  adapter :active_record
+
+  include_association :posts, clone_with: PostSpecialCloner
+  # or clone user's posts with tags!
+  # include_association :posts, clone_with: PostSpecialCloner, traits: :with_tags
+end
+
+UserCloner.call(user)
+# => <#User...
+```
+
+**NOTE**: if custom cloner is not defined, Clowne tries to infer the [implicit cloner](implicit_cloner.md).
+
+## Include multiple associations
+
+You can include multiple associations at once too:
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :accounts
+  has_many :posts
+end
+
+class UserCloner < Clowne::Cloner
+  adapter :active_record
+
+  include_associations :accounts, :posts
+end
+```
+
+**NOTE:** in that case, it's not possible to provide custom scopes and options.

data/docs/init_as.md

@@ -0,0 +1,36 @@
+---
+id: init_as
+title: Initialize Cloning Target
+sidebar_label: Init As
+---
+
+You can override the default Clowne method which generates a _plain_ copy of a source object.
+By default, Clowne initiates the cloned record using a `#dup` method.
+
+For example, Cloners could be used not only to generate _fresh_ new models but to apply some transformations to the existing record:
+
+
+```ruby
+class User < ApplicationRecord
+  has_one :profile
+  has_many :posts
+end
+
+class UserCloner < Clowne::Cloner
+  adapter :active_record
+
+  include_association :profile
+
+  trait :copy_settings do
+    # Use a `target` for all the actions
+    init_as { |_source, target:| target }
+  end
+end
+
+jack = User.find_by(email: 'jack@evl.ms')
+john = User.find_by(email: 'john@evl.ms')
+
+# we want to clone Jack's profile settings to another user,
+# without creating a new one
+UserCloner.call(jack, traits: :copy_settings, target: john)
+```

data/docs/inline_configuration.md

@@ -0,0 +1,38 @@
+---
+id: inline_configuration
+title: Inline Configuration
+---
+
+You can also enhance the cloner configuration inline (i.e., add declarations dynamically):
+
+```ruby
+cloned = UserCloner.call(User.last) do
+  exclude_association :profile
+
+  finalize do |source, record|
+    record.email = "clone_of_#{source.email}"
+  end
+end
+
+cloned.email
+# => "clone_of_john@example.com"
+
+# associations:
+cloned.posts.size == User.last.posts.size
+# => true
+cloned.profile
+# => nil
+```
+
+Inline enhancement doesn't affect the _global_ configuration so that you can use it without any fear.
+
+Thus it's also possible to clone objects without any cloner classes at all by using `Clowne::Cloner`:
+
+```ruby
+cloned = Clowne::Cloner.call(user) do
+  # anything you want!
+end
+
+cloned
+# => <#User..
+```

data/docs/installation.md

@@ -0,0 +1,16 @@
+---
+id: installation
+title: Installation
+---
+
+To install Clowne with RubyGems:
+
+```ruby
+gem install clowne
+```
+
+Or add this line to your application's Gemfile:
+
+```ruby
+gem 'clowne'
+```

data/docs/nullify.md

@@ -0,0 +1,37 @@
+---
+id: nullify
+title: Nullify Attributes
+sidebar_label: Nullify
+---
+
+To set a bunch of attributes to `nil` you can use the `nullify` declaration:
+
+```ruby
+class User < ActiveRecord::Base
+  # t.string :name
+  # t.string :surname
+  # t.string :email
+end
+
+class UserCloner < Clowne::Cloner
+  nullify :name, :email
+
+  trait :nullify_surname do
+    nullify :surname
+  end
+end
+
+clone = UserCloner.call(user)
+clone.name.nil?
+# => true
+clone.email.nil?
+# => true
+clone.surname.nil?
+# => false
+
+clone2 = UserCloner.call(user, traits: :nullify_surname)
+clone2.name.nil?
+# => true
+clone2.surname.nil?
+# => true
+```

data/docs/sequel.md

@@ -0,0 +1,56 @@
+---
+id: sequel
+title: Sequel
+---
+
+Clowne uses Sequel [`NestedAttributes` plugin](http://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/NestedAttributes.html) for cloning source's associations and you need to configure it.
+
+Also, Sequel target record wrapped into a special class for implementation full Clowne's behavior. You need to use method `to_model` for getting final cloned `Sequel::Model` object (or you can use `save` for saving the cloned object to DB).
+
+Example:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  adapter :sequel
+
+  include_association :account
+end
+
+class User < Sequel::Model
+  # Configure NestedAttributes plugin
+  plugin :nested_attributes
+
+  one_to_one :account
+  nested_attributes :account
+end
+```
+
+and get cloned user
+
+```ruby
+user = User.last
+wrapper = UserCloner.call(user)
+wrapper.class
+# => Clowne::Adapters::Sequel::RecordWrapper
+cloned_record = wrapper.to_model
+cloned_record.class
+# => User
+cloned_record.new?
+# => true
+```
+
+or you can save it immediately
+
+```ruby
+user = User.last
+wrapper = UserCloner.call(user)
+wrapper.class
+# => Clowne::Adapters::Sequel::RecordWrapper
+cloned_record = wrapper.save
+cloned_record.class
+# => User
+cloned_record.new?
+# => false
+```
+
+If you try to clone associations without `NestedAttributes` plugin, Clowne will skip this declaration.

data/docs/supported_adapters.md

@@ -0,0 +1,13 @@
+---
+id: supported_adapters
+title: Supported Adapters
+---
+
+Clowne supports the following ORM adapters (and associations):
+
+Adapter                                            |1:1         | 1:M         | M:M                     |
+---------------------------------------------------|------------|-------------|-------------------------|
+[:active_record](/clowne/docs/active_record.html)   | has_one    | has_many    | has_and_belongs_to_many |
+[:sequel](/clowne/docs/sequel.html)                 | one_to_one | one_to_many | many_to_many            |
+
+For more information see the corresponding adapter documentation.

data/docs/traits.md

@@ -0,0 +1,28 @@
+---
+id: traits
+title: Traits
+---
+
+Traits allow you to group cloner declarations together and then apply them (like in [`factory_bot`](https://github.com/thoughtbot/factory_bot)):
+
+```ruby
+class UserCloner < Clowne::Cloner
+  trait :with_posts do
+    include_association :posts
+  end
+
+  trait :with_profile do
+    include_association :profile
+  end
+
+  trait :nullify_name do
+    nullify :name
+  end
+end
+
+UserCloner.call(user, traits: %i[with_posts with_profile nullify_name])
+# or
+UserCloner.call(user, traits: :nullify_name)
+# or
+# ...
+```

data/docs/web/.gitignore

@@ -0,0 +1,11 @@
+node_modules
+.DS_Store
+lib/core/metadata.js
+lib/core/MetadataBlog.js
+website/translated_docs
+website/build/
+website/yarn.lock
+website/node_modules
+
+website/i18n/*
+!website/i18n/en.json