decors 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c33d4924184f251e5ee9c3a372251355e09efe7f
-  data.tar.gz: 9ddc59be81ccc266b78d36b3b9dc656b37c97bc0
+  metadata.gz: 7759f5e7d47d9e741ae03ea06cb02acaff1f984e
+  data.tar.gz: 2b41184cffff4ba470f4730fe68c3fe52e779518
 SHA512:
-  metadata.gz: 3b965a9750314f1f8e921510c9e6275eae49ec18c3f8a2285b796700acfb813e9db6aa4f95e9c68d179d1cc2665bf8891c093a9617a94971f44cf4098f1f801e
-  data.tar.gz: 6f6e62a25f06fe9e2d474aa1ec45cc43c85f4e598d070e2b0da5ee9b42d854b8b0a44ab96f5e2d4b4567921dd9ac5a4ee75d8a4b766c46a0820b8b6b008132e4
+  metadata.gz: 7abe88ecad1024a83fefd0629af2120689063b0335d0fcb8f5711a071213c5919177804ddd9d377f38faffc7e0bf0aaa7cd9772b42e4df15376326850328c219
+  data.tar.gz: 66d71eea9cd047431f76e349f4a95e15cdf06d60bcaaaa7103831f4eb12539fe3622ead623755a9e68ba820b77c6c10fc09708ab1e09fbe7a131f1644f46c7ec

data/.gitignore

@@ -2,3 +2,4 @@
 .rspec
 .rubocop.yml
 *.gem
+README.html

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+install:
+  - bundle install
+script: bundle exec rspec spec

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Decors changelog
 
+## Version 0.2 (Released May 10, 2017)
+
+- (bugfix) nested singleton handling (https://github.com/getbannerman/decors/issues/2)
+- (bugfix) keep method visibility (https://github.com/getbannerman/decors/issues/3)
+
+
 ## Version 0.1 (Released April 24, 2017)
 
 - First implementation

data/Gemfile

@@ -0,0 +1,5 @@
+ruby File.open('./.ruby-version').readline.split("\n").first
+
+source 'https://rubygems.org' do
+  gemspec
+end

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    decors (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.1)
+    diff-lcs (1.3)
+    method_source (0.8.2)
+    pry (0.10.4)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.4)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    slop (3.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  decors!
+  pry!
+  rspec (~> 3)!
+
+RUBY VERSION
+   ruby 2.3.1p112
+
+BUNDLED WITH
+   1.14.6

data/LICENSE

@@ -0,0 +1,23 @@
+
+Copyright (c) 2012 Michael Fairley
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,6 +1,6 @@
 # Decors
 
-#### Yet another implementation of Python Decorators/Java annotation in ruby
+#### Yet another implementation of Python Decorators/Java annotations in ruby
 
 Here are other implementations:
 - https://github.com/wycats/ruby_decorators
@@ -8,11 +8,191 @@ Here are other implementations:
 - https://github.com/fredwu/ruby_decorators
 - https://gist.github.com/reu/2762650
 
+[See why](#faq) we decided to implement this differently.
+
 ## Install
 
-Add `gem 'decors'` to your Gemfile and then `bundle`
+Add `gem 'decors'` to your Gemfile
+Then run `bundle`
 
 ## Usage
 
+#### Basic usage
+
+```ruby
+# Create a new decorator
+module DB
+    class WithinTransaction < ::Decors::DecoratorBase
+        def call(*)
+            DB.transaction { super }
+        end
+    end
+end
+
+# Define the alias on the class/module you want to use it
+class Item
+    define_decorator :WithinTransaction, DB::WithinTransaction
+
+    # From now on you can use the decorator to decorate any method/singleton method
+
+    WithinTransaction()
+    def do_stuff_in_db
+        # do_stuff_in_db within a db transaction
+    end
+
+    WithinTransaction()
+    def self.do_stuff_in_db
+        # do_stuff_in_db within a db transaction
+    end
+end
+```
+
+#### Mixin usage
+
+```ruby
+# Create a new decorator
+module DbDecorator
+    class WithinTransaction < ::Decors::DecoratorBase; end
+    class LogBeforeDbHit < ::Decors::DecoratorBase; end
+
+    # define decorator that can be mixed with other classes/modules
+    define_mixin_decorator :WithinTransaction, WithinTransaction
+    define_mixin_decorator :LogBeforeDbHit, LogBeforeDbHit
+end
+
+class Item
+    extend DbDecorator
+
+    WithinTransaction()
+    LogBeforeDbHit()
+    def do_stuff_in_db
+        # do_stuff_in_db within a db transaction
+    end
+end
+```
+
+#### Argument modification
+
+Sometimes you want the decorator to modify your method arguments. For example a generic way to define an api that handles pagination and filtering.
+
+```ruby
+    module Api
+        class SimpleApi < ::Decors::DecoratorBase
+            attr_reader :model_store, :pagination, :filtering
+
+            def initialize(*, model_store, pagination:, filtering:)
+                @model_store = model_store
+                @pagination = pagination
+                @filtering = filtering
+                super
+            end
+
+            def call(this, *)
+                models, page, per_page = paginate(filter(model_store.all))
+
+                super(this, models, page: page, per_page: per_page)
+            end
+
+            ...
+        end
+    end
+
+    class ItemController
+        SimpleApi(Item, pagination: true, filtering: true)
+        def index(items, page:, per_page:)
+            render json: { items: items.map(&:as_json), page: page, per_page: per_page }
+        end
+    end
+```
+
+## FAQ
+
+#### What is going on under the wood?
+```ruby
+    class User
+        define_decorator :Delay, Async::Delay
+
+        Delay(priority: :high)
+        def delayed_computation(*args, &blk)
+            # CODE here
+        end
+    end
+
+    # Is strictly equivalent to
+
+    class User
+        def secret_computation(*args, &blk)
+            Async::Delay.new(User, User.instance_method(:secret_computation), priority: :high)
+                .call(self, *args, &blk) do
+                    # CODE here
+                end
+        end
+    end
+```
+
+
+
+#### What is the difference between this and method modifiers?
+
+Method modifiers modify methods, specifically those are class methods which:
+
+1. Take the instance method name (symbol) as first argument
+2. Change subsequent calls to that method
+3. return the same symbol
+
+The limitation of those are:
+- They often come after the method which hurts lisibility
+- If they come before the method you cannot have other argument than the method_name
+- nesting those is a pain
+
+with decorator you can do the following
+
+```ruby
+    class User
+        ...
+
+        Delay(priority: :high)
+        Retry(3)
+        DbTransaction()
+        def secret_computation
+            # computation inside transaction retried up to 3 times if an error occurs.
+            # All that performed async
+        end
+    end
+
+    # VS
+
+    class User
+        ...
+
+        db_transaction def secret_computation
+        end
+
+        retry_when_failing :secret_computation, 3
+        handle_async :secret_computation, priority: :high
+
+    end
+```
+
+#### Why another implementation of this ?
+
+Most of the implementation use the unary operator `+@` syntax to define the decorator which leads to a lost reference to the caller instance. This imply a global state of what are the current decorators to apply to the next method definition (which is not always threadsafe depending on the implementation).
+
+Current implementations wasn't handling nested singleton (see https://github.com/getbannerman/decors/issues/2)
+
+Current implementations have a rather large footprint. A class that needs a decorated method have all of its method definition hooked on the `method_added` callback. In our case it's only added at the decorator call. And we'll soon support callback removal after method definition.
+
+The obvious drawback of our approach are: The syntax that might be less comprehensive for a new comer, and the namespacing which we handle via aliasing at decorator declaration.
+
+#### What is that weird syntax?
+
+By convention we use ConstantName case for the decorators in order not to mix them with other method call/DSL.
+This is not enforced and you can have the text case you like.
+
+Note that, this syntax is also used in other gems such as [Contract](https://github.com/egonSchiele/contracts.ruby)
+
 ## License
 
+Copyright (c) 2017 [Bannerman](https://github.com/getbannerman), [Vivien Meyet](https://github.com/vmeyet)
+
+Licensed under the [MIT license](http://fredwu.mit-license.org/).

data/decors.gemspec

@@ -6,6 +6,7 @@ require 'decors'
 Gem::Specification.new do |gem|
     gem.name          = "decors"
     gem.version       = ::Decors::VERSION
+    gem.licenses      = ['MIT']
     gem.authors       = ['Vivien Meyet']
     gem.email         = ['vivien@getbannerman.com']
     gem.description   = "Ruby implementation of Python method decorators / Java annotations"
@@ -17,6 +18,6 @@ Gem::Specification.new do |gem|
     gem.test_files    = gem.files.grep(%r{^spec/})
     gem.require_paths = ['lib']
 
-    gem.add_development_dependency 'pry-byebug', '~> 0'
-    gem.add_development_dependency 'rspec', '~> 0'
+    gem.add_development_dependency 'pry', '~> 0'
+    gem.add_development_dependency 'rspec', '~> 3'
 end

data/lib/decors/decorator_definition.rb

@@ -8,9 +8,9 @@ module Decors
             method_definer = mixin ? :define_method : :define_singleton_method
 
             send(method_definer, decorator_name) do |*params, &blk|
-                ctx = self.singleton_class? ? ObjectSpace.each_object(self).first : self
-                ctx.send(:extend, MethodAddedListener)
-                ctx.declared_decorators << [decorator_class, params, blk]
+                extend(singleton_class? ? Decors::MethodAdded::SingletonListener : Decors::MethodAdded::StandardListener)
+
+                declared_decorators << [decorator_class, params, blk]
             end
         end
     end

data/lib/decors/method_added.rb

@@ -0,0 +1,63 @@
+require 'decors/utils'
+
+module Decors
+    module MethodAdded
+        module Handler
+            private
+
+            def declared_decorators
+                @declared_decorators ||= []
+            end
+
+            # method addition handling is the same for singleton and instance method
+            def handle_method_addition(clazz, method_name)
+                # @_ignore_additions allows to temporarily disable the hook
+                return if @_ignore_additions || declared_decorators.empty?
+                decorator_class, params, blk = declared_decorators.pop
+
+                decorated_method = clazz.instance_method(method_name)
+
+                @_ignore_additions = true
+                decorator = decorator_class.new(clazz, decorated_method, *params, &blk)
+                @_ignore_additions = false
+
+                clazz.send(:define_method, method_name) { |*args, &block| decorator.call(self, *args, &block) }
+                clazz.send(Decors::Utils.method_visibility(decorated_method), method_name)
+            end
+        end
+
+        module StandardListener
+            include ::Decors::MethodAdded::Handler
+
+            def method_added(meth)
+                super
+                handle_method_addition(self, meth)
+            end
+
+            def singleton_method_added(meth)
+                super
+                handle_method_addition(singleton_class, meth)
+            end
+        end
+
+        module SingletonListener
+            include ::Decors::MethodAdded::Handler
+
+            def singleton_method_added(meth)
+                super
+                handle_method_addition(singleton_class, meth)
+            end
+
+            def self.extended(base)
+                ObjectSpace.each_object(base).first.send(:extend, ForwardToSingletonListener)
+            end
+
+            module ForwardToSingletonListener
+                def singleton_method_added(meth)
+                    super
+                    singleton_class.send(:handle_method_addition, singleton_class, meth)
+                end
+            end
+        end
+    end
+end

data/lib/decors/utils.rb

@@ -0,0 +1,17 @@
+module Decors
+    module Utils
+        class << self
+            def method_visibility(method)
+                if method.owner.private_method_defined?(method.name)
+                    :private
+                elsif method.owner.protected_method_defined?(method.name)
+                    :protected
+                elsif method.owner.public_method_defined?(method.name)
+                    :public
+                else
+                    fail ArgumentError, 'Unkwnown method'
+                end
+            end
+        end
+    end
+end

data/lib/decors.rb

@@ -1,7 +1,7 @@
 require 'decors/decorator_base'
 require 'decors/decorator_definition'
-require 'decors/method_added_listener'
+require 'decors/method_added'
 
 module Decors
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
 end

data/spec/decors_spec.rb

@@ -64,6 +64,25 @@ describe Decors do
                 instance.test_method_not_decorated
             }
         end
+
+        context 'It keep the method visibility' do
+            before {
+                TestClass.class_eval {
+                    SimpleDecorator()
+                    public def public_test_method(*); end
+
+                    SimpleDecorator()
+                    private def private_test_method(*); end
+
+                    SimpleDecorator()
+                    protected def protected_test_method(*); end
+                }
+            }
+
+            it { expect(TestClass).to be_public_method_defined(:public_test_method) }
+            it { expect(TestClass).to be_protected_method_defined(:protected_test_method) }
+            it { expect(TestClass).to be_private_method_defined(:private_test_method) }
+        end
     end
 
     context 'when decorator is defining a method during initialization' do
@@ -310,6 +329,48 @@ describe Decors do
             after { TestClass.test_method }
         end
 
+        context 'when mixin extended on the class (singleton method in singleton class)' do
+            before {
+                TestClass.class_eval {
+                    class << self
+                        extend Decors::DecoratorDefinition
+
+                        define_decorator :Deco, Deco
+
+                        Deco()
+                        def self.test_method
+                            :ok
+                        end
+                    end
+                }
+            }
+
+            it { expect(Spy).to receive(:called) }
+            after { TestClass.singleton_class.test_method }
+        end
+
+        context 'when mixin extended on the class (method in singleton class of singleton class)' do
+            before {
+                TestClass.class_eval {
+                    class << self
+                        class << self
+                            extend Decors::DecoratorDefinition
+
+                            define_decorator :Deco, Deco
+
+                            Deco()
+                            def test_method
+                                :ok
+                            end
+                        end
+                    end
+                }
+            }
+
+            it { expect(Spy).to receive(:called) }
+            after { TestClass.singleton_class.test_method }
+        end
+
         context 'when mixin extended on the class (method in singleton class)' do
             before {
                 TestClass.class_eval {
@@ -366,4 +427,3 @@ describe Decors do
         end
     end
 end
-

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: decors
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Vivien Meyet
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-25 00:00:00.000000000 Z
+date: 2017-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: pry-byebug
+  name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
 description: Ruby implementation of Python method decorators / Java annotations
 email:
 - vivien@getbannerman.com
@@ -46,17 +46,24 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".ruby-version"
+- ".travis.yml"
 - CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
 - README.md
 - decors.gemspec
 - lib/decors.rb
 - lib/decors/decorator_base.rb
 - lib/decors/decorator_definition.rb
-- lib/decors/method_added_listener.rb
+- lib/decors/method_added.rb
+- lib/decors/utils.rb
 - spec/decors_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/getbannerman/decors
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -74,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.8
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Ruby implementation of Python method decorators / Java annotations

data/lib/decors/method_added_listener.rb

@@ -1,35 +0,0 @@
-module Decors
-    # Mixin that add method_added hooks
-    module MethodAddedListener
-        def method_added(meth)
-            super
-            handle_method_addition(self, meth)
-        end
-
-        def singleton_method_added(meth)
-            super
-            handle_method_addition(singleton_class, meth)
-        end
-
-        def declared_decorators
-            @declared_decorators ||= []
-        end
-
-        private
-
-        # method addition handling is the same for singleton and instance method
-        def handle_method_addition(clazz, method_name)
-            # @_ignore_additions allows to temporarily disable the hook
-            return if @_ignore_additions || declared_decorators.empty?
-            decorator_class, params, blk = declared_decorators.pop
-
-            decorated_method = clazz.instance_method(method_name)
-
-            @_ignore_additions = true
-            decorator = decorator_class.new(clazz, decorated_method, *params, &blk)
-            @_ignore_additions = false
-
-            clazz.send(:define_method, method_name) { |*args, &block| decorator.call(self, *args, &block) }
-        end
-    end
-end