clowne 1.3.0 → 1.5.0

data/docs/customization.md

@@ -1,63 +0,0 @@
-# Customization
-
-Clowne is built with extensibility in mind. You can create your own DSL commands and resolvers.
-
-Let's consider an example.
-
-Suppose that you want to add the `include_all` declaration to automagically include all associations (for ActiveRecord).
-
-First, you should add a custom declaration:
-
-```ruby
-# Extend from Base declaration
-class IncludeAll < Clowne::Declarations::Base # :nodoc: all
-  def compile(plan)
-    # Just add all_associations declaration (self) to plan
-    plan.set(:all_associations, self)
-  end
-end
-
-# Register our declrations, i.e. extend DSL
-Clowne::Declarations.add :include_all, IncludeAll
-```
-
-See more on `plan` in [architecture overview](architecture.md).
-
-Secondly, register a resolver:
-
-```ruby
-class AllAssociations
-  # This method is called when all_associations command is applied.
-  #
-  #   source – source record
-  #   record – target record (our clone)
-  #   declaration – declaration object
-  #   params – custom params passed to cloner
-  def call(source, record, declaration, params:)
-    source.class.reflections.each_value do |_name, reflection|
-      # Exclude belongs_to associations
-      next if reflection.macro == :belongs_to
-
-      # Resolve and apply association cloner
-      cloner_class = Clowne::Adapters::ActiveRecord::Associations.cloner_for(reflection)
-      cloner_class.new(reflection, source, declaration, params).call(record)
-    end
-    record
-  end
-end
-
-# Finally, register the resolver
-Clowne::Adapters::ActiveRecord.register_resolver(
-  :all_associations, AllAssociations
-)
-```
-
-Now you can use it likes this:
-
-```ruby
-class UserCloner < Clowne::Cloner
-  adapter :active_record
-
-  include_all
-end
-```

data/docs/exclude_association.md

@@ -1,61 +0,0 @@
-# Exclude Association
-
-Clowne doesn't include any association by default and doesn't provide _magic_ `include_all` declaration (although you can [add one by yourself](customization.md)).
-
-Nevertheless, sometimes you might want to exclude already added associations (when inheriting a cloner or using [traits](traits.md)).
-
-Consider an example:
-
-```ruby
-class UserCloner < Clowne::Cloner
-  include_association :posts
-
-  trait :without_posts do
-    exclude_association :posts
-  end
-end
-
-# copy user and posts
-clone = UserCloner.call(user).to_record
-clone.posts.count == user.posts.count
-# => true
-
-# copy only user
-clone2 = UserCloner.call(user, traits: :without_posts).to_record
-clone2.posts
-# => []
-```
-
-**NOTE**: once excluded association cannot be re-included, e.g. the following cloner:
-
-```ruby
-class UserCloner < Clowne::Cloner
-  exclude_association :comments
-
-  trait :with_comments do
-    # That wouldn't work
-    include_association :comments
-  end
-end
-
-clone = UserCloner.call(user, traits: :with_comments).to_record
-clone.comments.empty?
-# => true
-```
-
-Why so? That allows us to have a deterministic cloning plan when combining multiple traits
-(or inheriting cloners).
-
-## Exclude multiple associations
-
-It's possible to exclude multiple associations at once the same way as [`include_associations`](include_association.md):
-
-```ruby
-class UserCloner < Clowne::Cloner
-  include_associations :accounts, :posts, :comments
-
-  trait :without_posts do
-    exclude_associations :posts, :comments
-  end
-end
-```

data/docs/finalize.md

@@ -1,31 +0,0 @@
-# Finalization
-
-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
-
-cloned = UserCloner.call(user).to_record
-cloned.name
-# => 'This is copy!'
-cloned.email == "clone@example.com"
-# => false
-
-cloned2 = UserCloner.call(user, traits: :change_email).to_record
-cloned2.name
-# => 'This is copy!'
-cloned2.email
-# => 'clone@example.com'
-```
-
-Finalization blocks are called at the end of the [cloning process](getting_started?id=execution-order).

data/docs/from_v02_to_v1.md

@@ -1,83 +0,0 @@
-# From v0.2.x to v1.0.0
-
-The breaking change of v1.0 is the return of a unified [`result object`](operation.md) for all adapters.
-
-## ActiveRecord
-
-### Update code to work with [`Operation`](operation.md)
-
-```ruby
-# Before
-clone = UserCloner.call(user)
-# => <#User id: nil, ...>
-clone.save!
-# => true
-
-# After
-clone = UserCloner.call(user)
-# => <#Clowne::Utils::Operation ...>
-clone = clone.to_record
-# => <#User id: 2, ...>
-clone.save!
-# => true
-
-# After (even better because of using full functionality)
-operation = UserCloner.call(user)
-# => <#Clowne::Utils::Operation ...>
-operation.persist!
-# => true
-clone = operation.to_record
-# => <#User id: 2, ...>
-clone.persisted?
-# => true
-```
-
-### Move post-processing cloning logic into [`after_persist`](after_persist.md) callback (if you have it)
-
-*Notice: `after_persist` supported only with [`active_record`](active_record.md) adapter.*
-
-```ruby
-# Before
-clone = UserCloner.call(user)
-clone.save!
-# do something with persisted clone
-
-# After
-class UserCloner < Clowne::Cloner
-  # ...
-  after_persist do |origin, clone, **|
-    # do something with persisted clone
-  end
-end
-
-clone = UserCloner.call(user).tap(&:persist).to_record
-```
-## Sequel
-
-### Use `to_record` instead of `to_model`
-
-```ruby
-# Before
-record_wrapper = UserCloner.call(user)
-clone = record_wrapper.to_model
-clone.new?
-# => true
-
-# After
-operation = UserCloner.call(user)
-clone = operation.to_record
-clone.new?
-# => true
-```
-
-### Use `operation#persist` instead of converting to model and calling `#save`
-
-```ruby
-# Before
-record_wrapper = UserCloner.call(user)
-clone = record_wrapper.to_model
-clone.save
-
-# After
-clone = UserCloner.call(user).tap(&:persist).to_record
-```

data/docs/getting_started.md

@@ -1,171 +0,0 @@
-# Getting Started
-
-## Installation
-
-To install Clowne with RubyGems:
-
-```ruby
-gem install clowne
-```
-
-Or add this line to your application's Gemfile:
-
-```ruby
-gem "clowne"
-```
-
-## Configuration
-
-Basic cloner implementation looks like:
-
-```ruby
-class SomeCloner < Clowne::Cloner
-  adapter :active_record # or adapter Clowne::Adapters::ActiveRecord
-  # some implementation ...
-end
-```
-
-You can configure the default adapter for cloners:
-
-```ruby
-# put to initializer
-# e.g. config/initializers/clowne.rb
-Clowne.default_adapter = :active_record
-```
-
-and skip explicit adapter declaration
-
-```ruby
-class SomeCloner < Clowne::Cloner
-  # some implementation ...
-end
-```
-See the list of [available adapters](supported_adapters.md).
-
-## Basic Example
-
-Assume that you have the following model:
-
-```ruby
-class User < ActiveRecord::Base
-  # create_table :users do |t|
-  #  t.string :login
-  #  t.string :email
-  #  t.timestamps null: false
-  # end
-
-  has_one :profile
-  has_many :posts
-end
-
-class Profile < ActiveRecord::Base
-  # create_table :profiles do |t|
-  #   t.string :name
-  # end
-end
-
-class Post < ActiveRecord::Base
-  # create_table :posts
-end
-```
-
-Let's declare our cloners first:
-
-```ruby
-class UserCloner < Clowne::Cloner
-  adapter :active_record
-
-  include_association :profile, clone_with: SpecialProfileCloner
-  include_association :posts
-
-  nullify :login
-
-  # params here is an arbitrary Hash passed into cloner
-  finalize do |_source, record, **params|
-    record.email = params[:email]
-  end
-end
-
-class SpecialProfileCloner < Clowne::Cloner
-  adapter :active_record
-
-  nullify :name
-end
-```
-
-Now you can use `UserCloner` to clone existing records:
-
-```ruby
-user = User.last
-# => <#User id: 1, login: 'clown', email: 'clown@circus.example.com'>
-
-operation = UserCloner.call(user, email: "fake@example.com")
-# => <#Clowne::Utils::Operation...>
-
-operation.to_record
-# => <#User id: nil, login: nil, email: 'fake@example.com'>
-
-operation.persist!
-# => true
-
-cloned = operation.to_record
-# => <#User id: 2, login: nil, email: 'fake@example.com'>
-
-cloned.login
-# => nil
-cloned.email
-# => "fake@example.com"
-
-# associations:
-cloned.posts.count == user.posts.count
-# => true
-cloned.profile.name
-# => nil
-```
-
-## Overview
-
-In [the basic example](#basic-example), you can see that Clowne consists of flexible DSL which is used in a class inherited of `Clowne::Cloner`.
-
-You can combinate this DSL via [`traits`](traits.md) and make a cloning plan which exactly you want.
-
-**We strongly recommend [`write tests`](testing.md) to cover resulting cloner logic**
-
-Cloner class returns [`Operation`](operation.md) instance as a result of cloning. The operation provides methods to save cloned record. You can wrap this call to a transaction if it is necessary.
-
-### Execution Order
-
-The order of cloning actions depends on the adapter (i.e., could be customized).
-
-All built-in adapters have the same order and what happens when you call `Operation#persist`:
-- init clone (see [`init_as`](init_as.md)) (empty by default)
-- [`clone associations`](include_association.md)
-- [`nullify`](nullify.md) attributes
-- run [`finalize`](finalize.md) blocks. _The order of [`finalize`](finalize.md) blocks is the order they've been written._
-- run [`after_clone`](after_clone.md) callbacks
-- __SAVE CLONED RECORD__
-- run [`after_persist`](after_persist.md) callbacks
-
-## Motivation & Alternatives
-
-### Why did we decide to build our own cloning gem instead of using the existing solutions?
-
-First, the existing solutions turned out not to be stable and flexible enough for us.
-
-Secondly, they are Rails-only (or, more precisely, ActiveRecord-only).
-
-Nevertheless, thanks to [amoeba](https://github.com/amoeba-rb/amoeba) and [deep_cloneable](https://github.com/moiristo/deep_cloneable) for inspiration.
-
-For ActiveRecord we support amoeba-like [in-model configuration](active_record.md) and you can add missing DSL declarations yourself [easily](customization.md).
-
-We also provide an ability to specify cloning [configuration in-place](inline_configuration.md) like `deep_clonable` does.
-
-So, we took the best of these too and brought to the outside-of-Rails world.
-
-### Why build a gem to clone models at all?
-
-That's a good question. Of course, you can write plain old Ruby services do handle the cloning logic. But for complex models hierarchies, this approach has major disadvantages: high code complexity and lack of re-usability.
-
-The things become even worse when you deal with STI models and different cloning contexts.
-
-That's why we decided to build a specific cloning tool.

data/docs/implicit_cloner.md

@@ -1,33 +0,0 @@
-# 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).to_record
-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

@@ -1,133 +0,0 @@
-# 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
-```
-
-### Supported Associations
-
-Adapter                                   |1:1         |*:1         | 1:M         | M:M                     |
-------------------------------------------|------------|------------|-------------|-------------------------|
-[Active Record](active_record)  | has_one    | belongs_to | has_many    | has_and_belongs_to|
-[Sequel](sequel)                | one_to_one | -          | one_to_many | many_to_many     |
-
-## 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[:state]) }
-end
-
-# Clone only draft posts
-UserCloner.call(user, state: :draft).to_record
-# => <#User id: nil, ... >
-```
-
-## 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).to_record
-# => <#User id: nil, ... >
-```
-
-**NOTE**: if custom cloner is not defined, Clowne tries to infer the [implicit cloner](implicit_cloner.md).
-
-## Nested parameters
-
-Follow to [documentation page](parameters.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.
-
-### Belongs To association
-
-You can include belongs_to association, but will do it carefully.
-If you have loop by relations in your models, when you clone it will raise SystemStackError.
-Check this [test](https://github.com/palkan/clowne/blob/master/spec/clowne/integrations/active_record_belongs_to_spec.rb) for instance.

data/docs/index.html

@@ -1,29 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Document</title>
-  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
-  <meta name="description" content="Description">
-  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
-  <link rel="stylesheet" href="assets/vue.css">
-  <link rel="stylesheet" href="assets/styles.css">
-</head>
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      name: 'Clowne',
-      repo: 'https://github.com/clowne-rb/clowne',
-      loadSidebar: true,
-      subMaxLevel: 2,
-      auto2top: true,
-      search: {
-        namespace: 'clowne'
-      }
-    }
-  </script>
-  <script src="assets/docsify.min.js"></script>
-  <script src="assets/prism-ruby.min.js"></script>
-</body>
-</html>

data/docs/init_as.md

@@ -1,40 +0,0 @@
-# Initialize Cloning Target
-
-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")
-# => <#User id: 1, ...>
-jack.create_profile(name: "Jack")
-# => <#Profile id: 1, name: 'Jack', ...>
-
-john = User.find_by(email: "john@evl.ms")
-# => <#User id: 2, ...>
-
-# we want to clone Jack's profile to John's user,
-# without creating a new one
-john_with_profile = UserCloner.call(jack, traits: :copy_settings, target: john).to_record
-# => <#User id: 2, ...>
-john_with_profile.profile
-#=> <#Profile id: nil, name: 'Jack',...>
-```

data/docs/inline_configuration.md

@@ -1,37 +0,0 @@
-# Inline Configuration
-
-You can also enhance the cloner configuration inline (i.e., add declarations dynamically):
-
-```ruby
-operation = UserCloner.call(User.last) do
-  exclude_association :profile
-
-  finalize do |source, record|
-    record.email = "clone_of_#{source.email}"
-  end
-end
-
-cloned = operation.to_record
-
-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.to_record
-
-cloned
-# => <#User..
-```