clowne 0.1.0 → 1.3.0

data/docs/assets/vue.css

@@ -0,0 +1 @@
+@import url("https://fonts.googleapis.com/css?family=Roboto+Mono|Source+Sans+Pro:300,400,600");*{-webkit-font-smoothing:antialiased;-webkit-overflow-scrolling:touch;-webkit-tap-highlight-color:rgba(0,0,0,0);-webkit-text-size-adjust:none;-webkit-touch-callout:none;box-sizing:border-box}body:not(.ready){overflow:hidden}body:not(.ready) .app-nav,body:not(.ready)>nav,body:not(.ready) [data-cloak]{display:none}div#app{font-size:30px;font-weight:lighter;margin:40vh auto;text-align:center}div#app:empty:before{content:"Loading..."}.emoji{height:1.2rem;vertical-align:middle}.progress{background-color:var(--theme-color,#42b983);height:2px;left:0;position:fixed;right:0;top:0;transition:width .2s,opacity .4s;width:0;z-index:5}.search .search-keyword,.search a:hover{color:var(--theme-color,#42b983)}.search .search-keyword{font-style:normal;font-weight:700}body,html{height:100%}body{-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased;color:#34495e;font-family:Source Sans Pro,Helvetica Neue,Arial,sans-serif;font-size:15px;letter-spacing:0;margin:0;overflow-x:hidden}img{max-width:100%}a[disabled]{cursor:not-allowed;opacity:.6}kbd{border:1px solid #ccc;border-radius:3px;display:inline-block;font-size:12px!important;line-height:12px;margin-bottom:3px;padding:3px 5px;vertical-align:middle}li input[type=checkbox]{margin:0 .2em .25em 0;vertical-align:middle}.app-nav{margin:25px 60px 0 0;position:absolute;right:0;text-align:right;z-index:2}.app-nav.no-badge{margin-right:25px}.app-nav p{margin:0}.app-nav>a{margin:0 1rem;padding:5px 0}.app-nav li,.app-nav ul{display:inline-block;list-style:none;margin:0}.app-nav a{color:inherit;font-size:16px;text-decoration:none;transition:color .3s}.app-nav a.active,.app-nav a:hover{color:var(--theme-color,#42b983)}.app-nav a.active{border-bottom:2px solid var(--theme-color,#42b983)}.app-nav li{display:inline-block;margin:0 1rem;padding:5px 0;position:relative}.app-nav li ul{background-color:#fff;border:1px solid #ddd;border-bottom-color:#ccc;border-radius:4px;box-sizing:border-box;display:none;max-height:calc(100vh - 61px);overflow-y:auto;padding:10px 0;position:absolute;right:-15px;text-align:left;top:100%;white-space:nowrap}.app-nav li ul li{display:block;font-size:14px;line-height:1rem;margin:0;margin:8px 14px;white-space:nowrap}.app-nav li ul a{display:block;font-size:inherit;margin:0;padding:0}.app-nav li ul a.active{border-bottom:0}.app-nav li:hover ul{display:block}.github-corner{border-bottom:0;position:fixed;right:0;text-decoration:none;top:0;z-index:1}.github-corner:hover .octo-arm{animation:a .56s ease-in-out}.github-corner svg{color:#fff;fill:var(--theme-color,#42b983);height:80px;width:80px}main{display:block;position:relative;width:100vw;height:100%;z-index:0}main.hidden{display:none}.anchor{display:inline-block;text-decoration:none;transition:all .3s}.anchor span{color:#34495e}.anchor:hover{text-decoration:underline}.sidebar{border-right:1px solid rgba(0,0,0,.07);overflow-y:auto;padding:40px 0 0;position:absolute;top:0;bottom:0;left:0;transition:transform .25s ease-out;width:300px;z-index:3}.sidebar>h1{margin:0 auto 1rem;font-size:1.5rem;font-weight:300;text-align:center}.sidebar>h1 a{color:inherit;text-decoration:none}.sidebar>h1 .app-nav{display:block;position:static}.sidebar .sidebar-nav{line-height:2em;padding-bottom:40px}.sidebar li.collapse .app-sub-sidebar{display:none}.sidebar ul{margin:0 0 0 15px;padding:0}.sidebar li>p{font-weight:700;margin:0}.sidebar ul,.sidebar ul li{list-style:none}.sidebar ul li a{border-bottom:none;display:block}.sidebar ul li ul{padding-left:20px}.sidebar::-webkit-scrollbar{width:4px}.sidebar::-webkit-scrollbar-thumb{background:transparent;border-radius:4px}.sidebar:hover::-webkit-scrollbar-thumb{background:hsla(0,0%,53%,.4)}.sidebar:hover::-webkit-scrollbar-track{background:hsla(0,0%,53%,.1)}.sidebar-toggle{background-color:transparent;background-color:hsla(0,0%,100%,.8);border:0;outline:none;padding:10px;position:absolute;bottom:0;left:0;text-align:center;transition:opacity .3s;width:284px;z-index:4}.sidebar-toggle .sidebar-toggle-button:hover{opacity:.4}.sidebar-toggle span{background-color:var(--theme-color,#42b983);display:block;margin-bottom:4px;width:16px;height:2px}body.sticky .sidebar,body.sticky .sidebar-toggle{position:fixed}.content{padding-top:60px;position:absolute;top:0;right:0;bottom:0;left:300px;transition:left .25s ease}.markdown-section{margin:0 auto;max-width:800px;padding:30px 15px 40px;position:relative}.markdown-section>*{box-sizing:border-box;font-size:inherit}.markdown-section>:first-child{margin-top:0!important}.markdown-section hr{border:none;border-bottom:1px solid #eee;margin:2em 0}.markdown-section iframe{border:1px solid #eee;width:1px;min-width:100%}.markdown-section table{border-collapse:collapse;border-spacing:0;display:block;margin-bottom:1rem;overflow:auto;width:100%}.markdown-section th{font-weight:700}.markdown-section td,.markdown-section th{border:1px solid #ddd;padding:6px 13px}.markdown-section tr{border-top:1px solid #ccc}.markdown-section p.tip,.markdown-section tr:nth-child(2n){background-color:#f8f8f8}.markdown-section p.tip{border-bottom-right-radius:2px;border-left:4px solid #f66;border-top-right-radius:2px;margin:2em 0;padding:12px 24px 12px 30px;position:relative}.markdown-section p.tip:before{background-color:#f66;border-radius:100%;color:#fff;content:"!";font-family:Dosis,Source Sans Pro,Helvetica Neue,Arial,sans-serif;font-size:14px;font-weight:700;left:-12px;line-height:20px;position:absolute;height:20px;width:20px;text-align:center;top:14px}.markdown-section p.tip code{background-color:#efefef}.markdown-section p.tip em{color:#34495e}.markdown-section p.warn{background:rgba(66,185,131,.1);border-radius:2px;padding:1rem}.markdown-section ul.task-list>li{list-style-type:none}body.close .sidebar{transform:translateX(-300px)}body.close .sidebar-toggle{width:auto}body.close .content{left:0}@media print{.app-nav,.github-corner,.sidebar,.sidebar-toggle{display:none}}@media screen and (max-width:768px){.github-corner,.sidebar,.sidebar-toggle{position:fixed}.app-nav{margin-top:16px}.app-nav li ul{top:30px}main{height:auto;overflow-x:hidden}.sidebar{left:-300px;transition:transform .25s ease-out}.content{left:0;max-width:100vw;position:static;padding-top:20px;transition:transform .25s ease}.app-nav,.github-corner{transition:transform .25s ease-out}.sidebar-toggle{background-color:transparent;width:auto;padding:30px 30px 10px 10px}body.close .sidebar{transform:translateX(300px)}body.close .sidebar-toggle{background-color:hsla(0,0%,100%,.8);transition:background-color 1s;width:284px;padding:10px}body.close .content{transform:translateX(300px)}body.close .app-nav,body.close .github-corner{display:none}.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:a .56s ease-in-out}}@keyframes a{0%,to{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}section.cover{-ms-flex-align:center;align-items:center;background-position:50%;background-repeat:no-repeat;background-size:cover;height:100vh;display:none}section.cover.show{display:-ms-flexbox;display:flex}section.cover.has-mask .mask{background-color:#fff;opacity:.8;position:absolute;top:0;height:100%;width:100%}section.cover .cover-main{-ms-flex:1;flex:1;margin:-20px 16px 0;text-align:center;z-index:1}section.cover a{color:inherit}section.cover a,section.cover a:hover{text-decoration:none}section.cover p{line-height:1.5rem;margin:1em 0}section.cover h1{color:inherit;font-size:2.5rem;font-weight:300;margin:.625rem 0 2.5rem;position:relative;text-align:center}section.cover h1 a{display:block}section.cover h1 small{bottom:-.4375rem;font-size:1rem;position:absolute}section.cover blockquote{font-size:1.5rem;text-align:center}section.cover ul{line-height:1.8;list-style-type:none;margin:1em auto;max-width:500px;padding:0}section.cover .cover-main>p:last-child a{border:1px solid var(--theme-color,#42b983);border-radius:2rem;box-sizing:border-box;color:var(--theme-color,#42b983);display:inline-block;font-size:1.05rem;letter-spacing:.1rem;margin:.5rem 1rem;padding:.75em 2rem;text-decoration:none;transition:all .15s ease}section.cover .cover-main>p:last-child a:last-child{background-color:var(--theme-color,#42b983);color:#fff}section.cover .cover-main>p:last-child a:last-child:hover{color:inherit;opacity:.8}section.cover .cover-main>p:last-child a:hover{color:inherit}section.cover blockquote>p>a{border-bottom:2px solid var(--theme-color,#42b983);transition:color .3s}section.cover blockquote>p>a:hover{color:var(--theme-color,#42b983)}.sidebar,body{background-color:#fff}.sidebar{color:#364149}.sidebar li{margin:6px 0}.sidebar ul li a{color:#505d6b;font-size:14px;font-weight:400;overflow:hidden;text-decoration:none;text-overflow:ellipsis;white-space:nowrap}.sidebar ul li a:hover{text-decoration:underline}.sidebar ul li ul{padding:0}.sidebar ul li.active>a{border-right:2px solid;color:var(--theme-color,#42b983);font-weight:600}.app-sub-sidebar li:before{content:"-";padding-right:4px;float:left}.markdown-section h1,.markdown-section h2,.markdown-section h3,.markdown-section h4,.markdown-section strong{color:#2c3e50;font-weight:600}.markdown-section a{color:var(--theme-color,#42b983);font-weight:600}.markdown-section h1{font-size:2rem;margin:0 0 1rem}.markdown-section h2{font-size:1.75rem;margin:45px 0 .8rem}.markdown-section h3{font-size:1.5rem;margin:40px 0 .6rem}.markdown-section h4{font-size:1.25rem}.markdown-section h5{font-size:1rem}.markdown-section h6{color:#777;font-size:1rem}.markdown-section figure,.markdown-section p{margin:1.2em 0}.markdown-section ol,.markdown-section p,.markdown-section ul{line-height:1.6rem;word-spacing:.05rem}.markdown-section ol,.markdown-section ul{padding-left:1.5rem}.markdown-section blockquote{border-left:4px solid var(--theme-color,#42b983);color:#858585;margin:2em 0;padding-left:20px}.markdown-section blockquote p{font-weight:600;margin-left:0}.markdown-section iframe{margin:1em 0}.markdown-section em{color:#7f8c8d}.markdown-section code{border-radius:2px;color:#e96900;font-size:.8rem;margin:0 2px;padding:3px 5px;white-space:pre-wrap}.markdown-section code,.markdown-section pre{background-color:#f8f8f8;font-family:Roboto Mono,Monaco,courier,monospace}.markdown-section pre{-moz-osx-font-smoothing:initial;-webkit-font-smoothing:initial;line-height:1.5rem;margin:1.2em 0;overflow:auto;padding:0 1.4rem;position:relative;word-wrap:normal}.token.cdata,.token.comment,.token.doctype,.token.prolog{color:#8e908c}.token.namespace{opacity:.7}.token.boolean,.token.number{color:#c76b29}.token.punctuation{color:#525252}.token.property{color:#c08b30}.token.tag{color:#2973b7}.token.string{color:var(--theme-color,#42b983)}.token.selector{color:#6679cc}.token.attr-name{color:#2973b7}.language-css .token.string,.style .token.string,.token.entity,.token.url{color:#22a2c9}.token.attr-value,.token.control,.token.directive,.token.unit{color:var(--theme-color,#42b983)}.token.function,.token.keyword{color:#e96900}.token.atrule,.token.regex,.token.statement{color:#22a2c9}.token.placeholder,.token.variable{color:#3d8fd1}.token.deleted{text-decoration:line-through}.token.inserted{border-bottom:1px dotted #202746;text-decoration:none}.token.italic{font-style:italic}.token.bold,.token.important{font-weight:700}.token.important{color:#c94922}.token.entity{cursor:help}.markdown-section pre>code{-moz-osx-font-smoothing:initial;-webkit-font-smoothing:initial;background-color:#f8f8f8;border-radius:2px;color:#525252;display:block;font-family:Roboto Mono,Monaco,courier,monospace;font-size:.8rem;line-height:inherit;margin:0 2px;max-width:inherit;overflow:inherit;padding:2.2em 5px;white-space:inherit}.markdown-section code:after,.markdown-section code:before{letter-spacing:.05rem}code .token{-moz-osx-font-smoothing:initial;-webkit-font-smoothing:initial;min-height:1.5rem}pre:after{color:#ccc;content:attr(data-lang);font-size:.6rem;font-weight:600;height:15px;line-height:15px;padding:5px 10px 0;position:absolute;right:0;text-align:right;top:0}

data/docs/clone_mapper.md

@@ -0,0 +1,59 @@
+# Clone mapper
+
+*Notice: `after_persist` supported only with [`active_record`](active_record.md) adapter.*
+
+In [`after_persist`](after_persist.md) documenation you can find interisting code:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  # ...
+  after_persist do |origin, clone, mapper:, **|
+    cloned_bio = mapper.clone_of(origin.bio)
+    clone.update(bio_id: cloned_bio.id)
+  end
+end
+```
+
+What is it `mapper:` and how it works?
+
+`mapper:` is an instance of `Clowne::Utils::CloneMapper`. Active Record pattern gives us an opportunity to build our cloning tool on objects, so while cloning, we remember origin records and their clones and can use these relations after saving with `Clowne::Utils::CloneMapper`.
+
+It perfectly works, and we can use the mapper to fix broken associations.
+There is only one small nuance - we can get `#clone_of` only for the record that participated in a cloning process, and this limits the functionality of the `after_persist` callbacks.
+
+But `Clowne is built with extensibility in mind™` and Clowne provides the ability to use your custom mapper:
+
+```ruby
+class CustomMapper < Clowne::Utils::CloneMapper
+  def initialize(dependencies)
+    super()
+    # inject dependencies if need
+    # or fetch it from other place (e.g. from DB)
+    @default_bios = dependencies.index_by(&:title)
+  end
+
+  def clone_of(record)
+    super(record) || fallback(record)
+  end
+
+  private
+
+  def fallback(record)
+    # put some mapping logic here
+    return if record.is_a?(Post)
+
+    @default_bios[record.title]
+  end
+end
+
+# now we can use it:
+
+class Post < ActiveRecord::Base
+  # add simple scope
+  # scope :default_bios, -> {...}
+end
+
+user = User.last
+operation = UserCloner.call(user, mapper: CustomMapper.new(Post.default_bios))
+operation.persist
+```

data/docs/customization.md

@@ -1,7 +1,4 @@
----
-id: customization
-title: Customization
----
+# Customization
 
 Clowne is built with extensibility in mind. You can create your own DSL commands and resolvers.
 
@@ -12,15 +9,16 @@ Suppose that you want to add the `include_all` declaration to automagically incl
 First, you should add a custom declaration:
 
 ```ruby
-class IncludeAll # :nodoc: all
+# Extend from Base declaration
+class IncludeAll < Clowne::Declarations::Base # :nodoc: all
   def compile(plan)
-    # Just add all_associations object to 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, Clowne::Declarations::IncludeAll
+Clowne::Declarations.add :include_all, IncludeAll
 ```
 
 See more on `plan` in [architecture overview](architecture.md).
@@ -39,6 +37,7 @@ class AllAssociations
     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)

data/docs/exclude_association.md

@@ -1,7 +1,4 @@
----
-id: exclude_association
-title: Exclude Association
----
+# 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)).
 
@@ -19,12 +16,12 @@ class UserCloner < Clowne::Cloner
 end
 
 # copy user and posts
-clone = UserCloner.call(user)
+clone = UserCloner.call(user).to_record
 clone.posts.count == user.posts.count
 # => true
 
 # copy only user
-clone2 = UserCloner.call(user, traits: :without_posts)
+clone2 = UserCloner.call(user, traits: :without_posts).to_record
 clone2.posts
 # => []
 ```
@@ -41,8 +38,9 @@ class UserCloner < Clowne::Cloner
   end
 end
 
-clone = UserCloner.call(user, traits: :with_comments)
-clone.comments.empty? #=> true
+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

data/docs/finalize.md

@@ -1,35 +1,31 @@
----
-id: finalize
-title: Finalization
-sidebar_label: Finalize
----
+# 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!'
+  finalize do |_source, record, **_params|
+    record.name = "This is copy!"
   end
 
   trait :change_email do
-    finalize do |_source, record, params|
+    finalize do |_source, record, **params|
       record.email = params[:email]
     end
   end
 end
 
-clone = UserCloner.call(user)
-clone.name
+cloned = UserCloner.call(user).to_record
+cloned.name
 # => 'This is copy!'
-clone.email == 'clone@example.com'
+cloned.email == "clone@example.com"
 # => false
 
-clone2 = UserCloner.call(user, traits: :change_email)
-clone2.name
+cloned2 = UserCloner.call(user, traits: :change_email).to_record
+cloned2.name
 # => 'This is copy!'
-clone2.email
+cloned2.email
 # => 'clone@example.com'
 ```
 
-Finalization blocks are called at the end of the [cloning process](execution_order.md).
+Finalization blocks are called at the end of the [cloning process](getting_started?id=execution-order).

data/docs/from_v02_to_v1.md

@@ -0,0 +1,83 @@
+# 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

@@ -0,0 +1,171 @@
+# 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,7 +1,4 @@
----
-id: implicit_cloner
-title: Implicit Cloner
----
+# Implicit Cloner
 
 When [cloning associations](include_association.md) Clowne tries to infer an appropriate cloner class for the records (unless `clone_with` specified).
 
@@ -28,7 +25,7 @@ user = User.last
 user.profile.name
 #=> "Bimbo"
 
-cloned = UserCloner.call(user)
+cloned = UserCloner.call(user).to_record
 cloned.profile.name
 # => "Clone of Bimbo"
 ```