clowne 0.1.0.pre1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b833f076ba69c9b626d4038e977e4a40d8de8dbb
-  data.tar.gz: 271303497d931c2773c8c4f948baacfa9819cd4a
+  metadata.gz: cb07a988be474d61f3bbf9360cfc4ab25de047be
+  data.tar.gz: 1a4763ae4bd1537ab0a254d4a0ebcb5ddd56930d
 SHA512:
-  metadata.gz: f4df02c8872ecdc0b1f70fd74a12549065aaf85cd6922b2648043905f3eba9d4bf415716a11b5f0a8f458d7c59d11edbe590e2e1c92f3328887ab9da38c7de1b
-  data.tar.gz: '0683a5756b9797ac8c2a9cd60a4adbd29c214b9dbd55ef3fd736e2e05b414a7b0d92493edcde7e9a109434ceb67ca557cc55953ec08f1caad2a2c35e13ac1439'
+  metadata.gz: 1ff3270acfabe0aebebfd272b3cb6eb27c9c7faea337fb59489898e008095d71dbfb835062e6c99c3b0fbc4b63e909073dd7e9e46231a6c3a0ecf5762f7204ef
+  data.tar.gz: 53e267bcb71f9283a64bb95df753e26b38058d5283c0b0b01276209fe6a27a07b3906cfbae881734875fca9a987e25fcbda6b3143f44956ef361102296821860

data/.codeclimate.yml

@@ -0,0 +1,7 @@
+version: "2"
+checks:
+  method-complexity:
+    enabled: false
+exclude_patterns:
+- "docs/"
+- "spec/"

data/.gitattributes

@@ -0,0 +1 @@
+docs/**/* linguist-vendored

data/.gitignore

@@ -13,3 +13,4 @@ rubocop.html
 *.gem
 gemfiles/*.lock
 Gemfile.local
+/docs/web/build/

data/.rubocop.yml

@@ -1,19 +1,29 @@
+require:
+- 'rubocop-md'
 AllCops:
   Exclude:
     - 'bin/**/*'
     - 'tmp/**/*'
+    - 'docs/web/**/*'
     - 'vendor/**/*'
     - 'gemfiles/vendor/**/*'
   DisplayCopNames: true
   StyleGuideCopsOnly: false
   TargetRubyVersion: 2.3
 
+Markdown:
+  WarnInvalid: true
+
 Rails:
   Enabled: false
 
 Naming/AccessorMethodName:
   Enabled: false
 
+Naming/ClassAndModuleCamelCase:
+  Exclude:
+    - 'spec/**/*.rb'
+
 Style/TrivialAccessors:
   Enabled: false
 
@@ -23,6 +33,7 @@ Metrics/LineLength:
 Style/Documentation:
   Exclude:
     - 'spec/**/*.rb'
+    - 'README.md'
 
 Style/SymbolArray:
   Enabled: false
@@ -33,6 +44,8 @@ Style/FrozenStringLiteralComment:
     - 'Gemfile'
     - 'Rakefile'
     - '*.gemspec'
+    - 'CHANGELOG.md'
+    - 'README.md'
 
 Metrics/BlockLength:
   Exclude:
@@ -43,3 +56,7 @@ Bundler/OrderedGems:
 
 Gemspec/OrderedDependencies:
   Enabled: false
+
+Lint/Void:
+  Exclude:
+    - 'README.md'

data/.travis.yml

@@ -4,6 +4,9 @@ language: ruby
 notifications:
   email: false
 
+before_install:
+  gem update --system
+
 before_script:
   # Only generate coverage report for the specified job
   - if [ "$CC_REPORT" == "true" ]; then curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter; fi
@@ -11,8 +14,8 @@ before_script:
   - if [ "$CC_REPORT" == "true" ]; then ./cc-test-reporter before-build; fi
 script:
   - bundle exec rake
-after_script:
   - if [ "$CC_REPORT" == "true" ]; then ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT; fi
+  - if [ "$DEPLOY_ME" == "true" ]; then (cd ./docs/web && yarn && yarn run build); fi
 
 matrix:
   fast_finish: true
@@ -25,7 +28,9 @@ matrix:
       gemfile: Gemfile
     - rvm: 2.4.3
       gemfile: Gemfile
-      env: CC_REPORT=true
+      env:
+        - CC_REPORT=true
+        - DEPLOY_ME=true
     - rvm: 2.4.1
       gemfile: gemfiles/activerecord42.gemfile
     - rvm: 2.3.1
@@ -37,3 +42,11 @@ matrix:
       gemfile: gemfiles/railsmaster.gemfile
     - rvm: jruby-9.1.0.0
       gemfile: gemfiles/jruby.gemfile
+deploy:
+  provider: pages
+  skip_cleanup: true
+  github_token: $GITHUB_TOKEN
+  local_dir: "./docs/web/build/clowne"
+  on:
+    branch: master
+    condition: $DEPLOY_ME = true

data/CHANGELOG.md

@@ -1,9 +1,16 @@
 # Change log
 
-## master branch
+## 0.1.0 (2018-02-01)
+
+- Add `init_as` declaration. ([@palkan][])
+
+- Support [Sequel](https://github.com/jeremyevans/sequel). ([@ssnickolay][])
+
+- Support passing a block to `#clowne` for inline configuration. ([@palkan][])
+
+## 0.1.0.beta1 (2018-01-08)
 
 - Initial version. ([@ssnickolay][], [@palkan][])
 
 [@palkan]: https://github.com/palkan
 [@ssnickolay]: https://github.com/ssnickolay
-

data/Gemfile

@@ -6,6 +6,7 @@ gemspec
 gem 'pry-byebug'
 gem 'sqlite3'
 gem 'activerecord', '>= 5.0'
+gem 'sequel', '>= 5.0'
 gem 'simplecov'
 
 local_gemfile = 'Gemfile.local'

data/README.md

@@ -1,26 +1,17 @@
 [![Gem Version](https://badge.fury.io/rb/clowne.svg)](https://badge.fury.io/rb/clowne)
 [![Build Status](https://travis-ci.org/palkan/clowne.svg?branch=master)](https://travis-ci.org/palkan/clowne)
-[![Code Climate](https://codeclimate.com/github/palkan/clowne.svg)](https://codeclimate.com/github/palkan/clowne)
 [![Test Coverage](https://codeclimate.com/github/palkan/clowne/badges/coverage.svg)](https://codeclimate.com/github/palkan/clowne/coverage)
+[![Docs](https://img.shields.io/readthedocs/pip.svg)](https://palkan.github.io/clowne)
 
 # Clowne
 
-**NOTICE**: gem is currently under heavy development, we plan to release the first version 'till the end of the year. 
+**NOTE**: this is the documentation for pre-release version **0.1.0.beta1**.
 
-A flexible gem for cloning your models. Clowne focuses on ease of use and provides the ability to connect various ORM adapters (currently only ActiveRecord is supported).
+A flexible gem for cloning your models. Clowne focuses on ease of use and provides the ability to connect various ORM adapters.
 
 <a href="https://evilmartians.com/">
 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
-### Alternatives
-
-Why did we decide to build our own cloning gem?
-
-First, existing solutions turned out not stable and flexible enough for us.
-
-Secondly, they are Rails-only. And we are not.
-
-Nevertheless, thanks to [amoeba](https://github.com/amoeba-rb/amoeba) and [deep_cloneable](https://github.com/moiristo/deep_cloneable) for inspiration.
 
 ## Installation
 
@@ -38,9 +29,7 @@ gem 'clowne'
 
 ## Quick Start
 
-This is a basic example that demonstrates how to clone your ActiveRecord model. For detailed documentation see [Features](#features).
-
-At first, define your cloneable model
+Assume that you have the following model:
 
 ```ruby
 class User < ActiveRecord::Base
@@ -55,7 +44,7 @@ class User < ActiveRecord::Base
 end
 ```
 
-The next step is to declare cloner
+Let's declare our cloners first:
 
 ```ruby
 class UserCloner < Clowne::Cloner
@@ -65,8 +54,8 @@ class UserCloner < Clowne::Cloner
   include_association :posts
 
   nullify :login
-  
-  # params here is an arbitrary hash passed into cloner
+
+  # params here is an arbitrary Hash passed into cloner
   finalize do |_source, record, params|
     record.email = params[:email]
   end
@@ -79,382 +68,37 @@ class SpecialProfileCloner < Clowne::Cloner
 end
 ```
 
-and call it
+Now you can use `UserCloner` to clone existing records:
 
 ```ruby
-clone = UserCloner.call(User.last, { email: "fake@example.com" })
-clone.persisted?
+user = User.last
+#=> <#User(login: 'clown', email: 'clown@circus.example.com')>
+
+cloned = UserCloner.call(user, email: 'fake@example.com')
+cloned.persisted?
 # => false
-clone.save!
-clone.login
+
+cloned.save!
+cloned.login
 # => nil
-clone.email
+cloned.email
 # => "fake@example.com"
 
 # associations:
-clone.posts.count == User.last.posts.count
+cloned.posts.count == user.posts.count
 # => true
-clone.profile.name
+cloned.profile.name
 # => nil
 ```
 
-## <a name="features">Features
-
-- [Configuration](#configuration)
-- [Include one association](#include_association)
-- - [Scope](#include_association_scope)
-- - [Options](#include_association_options)
-- [Exclude association](#exclude_association)
-- [Nullify attribute(s)](#nullify)
-- [Execute finalize block](#finalize)
-- [Traits](#traits)
-- [Execution order](#execution_order)
-- [Customization](#customization)
+Take a look at our [documentation](https://palkan.github.io/clowne) for more information!
 
-### <a name="configuration"></a>Configuration
+### Supported ORM adapters
 
-You can configure the default adapter for cloners:
-
-```ruby
-# somewhere in initializers
-Clowne.default_adapter = :active_record
-```
-
-### <a name="include_association"></a>Include one association
-
-Powerful declaration for including model's association.
-
-```ruby
-class User < ActiveRecord::Base
-  has_one :profile
-end
-
-class UserCloner < Clowne::Cloner
-  adapter Clowne::ActiveRecord::Adapter
-
-  include_association :profile
-end
-```
-
-But it's not all! :) The DSL looks like
-
-```ruby
-include_association name, scope, options
-```
-
-#### <a name="include_association_scope"></a>Include one association: Scope
-Scope can be a:
-
-`Symbol` - named scope.
-
-`Proc` - custom scope (supports parameter passing).
-
-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
-  adapter Clowne::ActiveRecord::Adapter
-
-  include_association :accounts, :active
-  include_association :posts, ->(params) { where(state: params[:post_status] }
-end
-
-# posts will be cloned only with draft status
-UserCloner.call(user, { post_status: :draft })
-# => <#User...
-```
-
-#### <a name="include_association_options"></a>Include one association: Options
-
-Options keys can be a:
-
-`:clone_with` - use custom cloner for all children.
-
-`:traits` - define special traits.
-
-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
-  adapter :active_record
-
-  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...
-```
-
-**Notice: if custom cloner is not defined, clowne tries to find default cloner and use it. (PostCloner for previous example)**
-
-### <a name="exclude_association"></a>Exclude association
-
-Exclude association from copying
-
-```ruby
-class UserCloner < Clowne::Cloner
-  adapter Clowne::ActiveRecord::Adapter
-
-  include_association :posts
-
-  trait :without_posts do
-    exclude_association :posts
-  end
-end
-
-# copy user and posts
-clone = UserCloner.call(user)
-clone.posts.count == user.posts.count
-# => true
-
-# copy only user
-clone2 = UserCloner.call(user, traits: :without_posts)
-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)
-clone.comments.empty? #=> true
-```
-
-Why so? That allows to have deterministic cloning plans when combining multiple traits
-(or inheriting cloners).
-
-### <a name="nullify"></a>Nullify attribute(s)
-
-Nullify attributes:
-
-```ruby
-class User < ActiveRecord::Base
-  # t.string :name
-  # t.string :surename
-  # t.string :email
-end
-
-class UserCloner < Clowne::Cloner
-  adapter Clowne::ActiveRecord::Adapter
-
-  nullify :name, :email
-
-  trait :nullify_surename do
-    nullify :surename
-  end
-end
-
-# nullify only name
-clone = UserCloner.call(user)
-clone.name.nil?
-# => true
-clone.email.nil?
-# => true
-clone.surename.nil?
-# => false
-
-# nullify name and surename
-clone2 = UserCloner.call(user, traits: :nullify_surename)
-clone.name.nil?
-# => true
-clone.surename.nil?
-# => true
-```
-
-### <a name="finalize"></a>Execute finalize block
-
-Simple callback for changing record manually.
-
-```ruby
-class UserCloner < Clowne::Cloner
-  adapter Clowne::ActiveRecord::Adapter
-
-  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
-
-# execute first finalize
-clone = UserCloner.call(user)
-clone.name
-# => 'This is copy!'
-clone.email == 'clone@example.com'
-# => false
-
-# execute both finalizes
-clone2 = UserCloner.call(user, traits: :change_email)
-clone.name
-# => 'This is copy!'
-clone.email
-# => 'clone@example.com'
-```
-
-### <a name="traits"></a>Traits
-
-Traits allow you to group cloner declarations together and then apply them (like in factory_bot).
-
-```ruby
-class UserCloner < Clowne::Cloner
-  adapter Clowne::ActiveRecord::Adapter
-
-  trait :with_posts do
-    include_association :posts
-  end
-
-  trait :with_profile do
-    include_association :profile
-  end
-
-  trait :nullify_name do
-    nullify :name
-  end
-end
-
-# execute first finalize
-UserCloner.call(user, traits: [:with_posts, :with_profile, :nullify_name])
-# or
-UserCloner.call(user, traits: :nullify_name)
-# or
-# ...
-```
-
-### <a name="execution_order"></a>Execution order
-
-The order of cloning actions depends on the adapter.
-
-For ActiveRecord:
-- clone associations
-- nullify attributes
-- run `finalize` blocks
-The order of `finalize` blocks is the order they've been written.
-
-### <a name="customization"></a>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 `include_all` declaration to automagically include all associations (for ActiveRecord).
-
-First, you should add a custom declaration:
-
-```ruby
-class IncludeAll # :nodoc: all
-  def compile(plan)
-    # Just add all_associations object to plan
-    plan.set(:all_associations, self)
-    # Plan supports 3 types of registers:
-    #
-    # 1) Scalar
-    #
-    # plan.set(key, value)
-    # plan.remove(key)
-    #
-    # 2) Append-only lists
-    #
-    # plan.add(key, value)
-    #
-    # 3) Two-phase set (2P-Set) (see below)
-    #
-    # plan.add_to(type, key, value)
-    # plan.remove_from(type, key)
-  end
-end
-
-# Register our declrations, i.e. extend DSL
-Clowne::Declarations.add :include_all, Clowne::Declarations::IncludeAll
-```
-
-\* Operations over [2P-Set](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type#2P-Set_(Two-Phase_Set)) (adding/removing) do not depend on the order of execution; we use "remove-wins" semantics, i.e. when a key has been removed, it cannot be re-added.
-
-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 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
-```
+Adapter                                   |1:1         | 1:M         | M:M                     |
+------------------------------------------|------------|-------------|-------------------------|
+[Active Record](https://palkan.github.io/clowne/docs/active_record.html)  | has_one    | has_many    | has_and_belongs_to_many |
+[Sequel](https://palkan.github.io/clowne/docs/sequel.html)           | one_to_one | one_to_many | many_to_many            |
 
 ## Maintainers