advisor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dce5c0242a387f50ef334a97a2583cade06759e3
+  data.tar.gz: 3eccbc9c38091e8ab6eafd8f4a64f5fa2ecb07e7
+SHA512:
+  metadata.gz: 3d749fa9ae030a74fa61ee73b3a96cf739f48c0233ba110575453150d3adb73030a4522fb61d80bc1f1a00b189b6b0cc949f2d5e3120448767c9e9cf84311cc0
+  data.tar.gz: 4427ed176fb927dda723ff41fdbc84ad07107dc02f5b255e6363177abd0f6fc207bf435b6591f68799d9ffb59d4c2f15e646a6a0d51845e1dcb4785dcad34958

data/.gitignore

@@ -0,0 +1,34 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+Documentation:
+  Enabled: false
+
+Style/Encoding:
+  Enabled: false
+
+Style/MultilineOperationIndentation:
+  Enabled: false
+
+AllCops:
+  Include:
+    - '**/*.gemspec'
+    - '**/Rakefile'

data/.ruby-version

@@ -0,0 +1 @@
+2.1.5

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/Gemfile.lock

@@ -0,0 +1,55 @@
+PATH
+  remote: .
+  specs:
+    advisor (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.0.0)
+    astrolabe (1.3.0)
+      parser (>= 2.2.0.pre.3, < 3.0)
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    method_source (0.8.2)
+    parser (2.2.0.3)
+      ast (>= 1.1, < 3.0)
+    powerpack (0.1.0)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rainbow (2.0.0)
+    rake (10.4.2)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.3)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.2)
+    rubocop (0.30.0)
+      astrolabe (~> 1.3)
+      parser (>= 2.2.0.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.4)
+    ruby-progressbar (1.7.5)
+    slop (3.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  advisor!
+  bundler (~> 1.7)
+  pry
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  rubocop

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/Readme.org

@@ -0,0 +1,125 @@
+* Advisor: Solve your cross-cutting concerns without mumbo-jumbo.
+
+  =Advisor= is Ruby gem that enables you to solve cross-cutting concerns without
+  the usual =method-renaming= present in most alternatives.
+
+  =Advisor= intercepts method calls and allows you to mix cross cutting concerns
+  and tedious book-keeping tasks. Logging, metric reporting, auditing, timing,
+  timeouting can be handled beautifully.
+
+  =Advisor= works with plain Ruby modules and do not mess your stack trace.
+
+  Also, the amount of /intrusion/ required to set up is kept to a minimum while
+  still keeping it /discoverable/. Every affected class must explicitly extend a
+  given module and every affected method call must also be declared.
+
+*** Usage
+
+    =Advisor= is organized between two main concepts only: =Advisor modules= and
+    =Advice modules=. =Advisor modules= are extensions applied to your classes
+    and =Advice modules= define the actual behavior of the intercepted method
+    calls.
+
+    In order to understand better how =Advisor= works, we are going to use an
+    example:
+
+***** Example
+
+      Suppose you want to log calls to some methods but don't want to keep
+      repeating the message formatting or messing with the method body.
+      =Advisor= provides a simple built-in module called =Advisor::Loggable=
+      that solves this issue.
+
+      #+begin_src ruby
+      class Account
+        extend Advisor::Loggable
+
+        log_calls_to :deposit
+
+        def deposit(_amount, _origin)
+          #...
+          :done
+        end
+      end
+      #+end_src
+
+      In an interactive console:
+
+      #+begin_src ruby
+      $ Account.new.deposit(300, 'Jane Doe')
+      # => I, [2015-04-11T21:26:42.405180 #13840]  INFO -- : [Time=2015-04-11 21:26:42 -0300][Thread=70183196300040]Called: Account#deposit(300, "Jane Doe")
+      # => :done
+      #+end_src
+
+      As you can see, the method call is intercepted and a message is printed to
+      =stdout=.
+
+      =Advisor= achieves this by using Ruby 2.0's =Module#prepend=. If you were
+      to check =Account='s ancestors you would get:
+
+      #+begin_src ruby
+      $ Account.ancestors
+      # => [Advisor::Advices::CallLogger(deposit), Account, Object, Kernel, BasicObject]
+      #+end_src
+
+      As you can see, the =Advisor::Advices::CallLogger(deposit)= module is
+      listed *before* Account itself in the ancestor chain.
+
+      In the next session we are going to explain how to write your own custom
+      advice.
+
+***** Writing an =Advice=
+
+      An =Advice= defines what to do with the advised method call.
+
+      The required interface for an advice must be like the example bellow:
+
+      #+begin_src ruby
+      class Advice
+        def initialize(receiver, advised_method, call_args, **options)
+          # The constructor of an advice must receive 3 arguments and extra options.
+          # Those extra options are defined when applying the extension to the advised
+          # class.
+        end
+
+        def self.applier_method
+          # Must return the name of the method which must be called in the class body
+          # to define which methods will be intercepted with the advice.
+
+          # In the case of `Advisor::Loggable`, this method returns `:log_calls_to`
+        end
+
+        def call
+          # This is the body of the advice.
+          #
+          # This method will always be called with the block `{ super(*call_args,
+          # &blk) }` That means the method implementation can decide when to run the
+          # advised method call. Check `Advisor::Advices::CallLogger` for an example.
+        end
+      end
+      #+end_src
+
+***** Creating an =Advisor= module
+
+      Every =Advisor= module must be built from the corresponding =Advice= by
+      using the =Advisor::Factory#build= method.
+
+      =Advisor::Loggable= is built from the =Advisor::Advices::CallLogger=
+      module.
+
+      =Advisor::Loggable= itself is built like this:
+
+      #+begin_src ruby
+      module Advisor
+        Loggable = Factory.new(Advices::CallLogger).build
+      end
+      #+end_src
+
+      Hence, if your custom =Advice= complies to the required interface,
+      =Advisor::Factory= will be able to convert it to an extension module with
+      no problems.
+
+*** Disclaimer
+
+    This version of the library is still experimental and probably not
+    production ready. Use at your own risk.

data/advisor.gemspec

@@ -0,0 +1,26 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'advisor/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'advisor'
+  spec.version = Advisor::VERSION
+  spec.required_ruby_version = '~>2.0'
+
+  spec.summary  = 'AOP with anonymous modules'
+  spec.authors  = ['Renan Ranelli']
+  spec.email    = ['renanranelli@gmail.com']
+  spec.homepage = 'http://github.com/rranelli/advisor'
+  spec.license  = 'MIT'
+
+  spec.files       = `git ls-files -z`.split("\x0")
+  spec.executables = spec.files.grep(%r{^bin\/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'pry'
+end

data/lib/advisor/advices/call_logger.rb

@@ -0,0 +1,69 @@
+require 'logger'
+
+module Advisor
+  module Advices
+    class CallLogger
+      class << self
+        attr_accessor :default_logger
+      end
+      self.default_logger = Logger.new(STDOUT)
+
+      def initialize(object, method, call_args, **opts)
+        @object = object
+        @method = method
+        @call_args = call_args
+        @logger = opts[:logger] || CallLogger.default_logger
+      end
+
+      attr_reader :object, :method, :call_args, :logger
+
+      def self.applier_method
+        :log_calls_to
+      end
+
+      def call
+        logger.info(success_message)
+        yield
+      rescue => e
+        logger.warn(failure_message(e))
+        raise
+      end
+
+      private
+
+      def success_message
+        call_message('Called: ')
+      end
+
+      def failure_message(ex)
+        call_message('Failed: ', "\n#{ex}")
+      end
+
+      def call_message(prefix, suffix = '')
+        "#{time}#{thread}#{id}#{prefix}\
+#{klass}##{method}(#{arguments})\
+#{suffix}"
+      end
+
+      def thread
+        "[Thread=#{Thread.current.object_id}]"
+      end
+
+      def time
+        "[Time=#{Time.now}]"
+      end
+
+      def klass
+        object.class
+      end
+
+      def arguments
+        call_args.map(&:inspect).join(', ')
+      end
+
+      def id
+        "[id=#{object.id}]" if object.respond_to?(:id)
+      end
+    end
+  end
+end

data/lib/advisor/advices.rb

@@ -0,0 +1 @@
+require_relative 'advices/call_logger'

data/lib/advisor/builtin_advisors.rb

@@ -0,0 +1,5 @@
+require 'logger'
+
+module Advisor
+  Loggable = Factory.new(Advices::CallLogger).build
+end

data/lib/advisor/factory.rb

@@ -0,0 +1,45 @@
+module Advisor
+  class Factory
+    def initialize(advice_klass)
+      @advice_klass = advice_klass
+    end
+
+    def build
+      advice_klazz = advice_klass
+      advisor_module = method(:advisor_module)
+
+      Module.new do
+        define_method(advice_klazz.applier_method) do |*methods, **args|
+          methods_str = methods.map(&:to_s).join(', ')
+
+          mod = advisor_module.call(methods, args)
+          mod.module_eval(%(def self.inspect
+                              "#{advice_klazz}(#{methods_str})"
+                            end))
+          mod.module_eval(%(def self.to_s; inspect; end))
+
+          prepend mod
+        end
+      end
+    end
+
+    protected
+
+    attr_reader :advice_klass
+
+    private
+
+    def advisor_module(methods, args)
+      advice_klazz = advice_klass
+
+      Module.new do
+        methods.each do |method_name|
+          define_method(method_name) do |*call_args, &blk|
+            advice = advice_klazz.new(self, method_name, call_args, **args)
+            advice.call { super(*call_args, &blk) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/advisor/version.rb

@@ -0,0 +1,3 @@
+module Advisor
+  VERSION = '0.1.0'
+end

data/lib/advisor.rb

@@ -0,0 +1,4 @@
+require_relative 'advisor/version'
+require_relative 'advisor/advices'
+require_relative 'advisor/factory'
+require_relative 'advisor/builtin_advisors'

data/spec/advisor/advices/call_logger_spec.rb

@@ -0,0 +1,60 @@
+require 'ostruct'
+
+module Advisor
+  module Advices
+    describe CallLogger do
+      subject(:advice) do
+        described_class.new(object, method, args, logger: logger)
+      end
+
+      let(:object) { OpenStruct.new(id: 42) }
+      let(:method) { 'the_meaning_of_life' }
+      let(:args) { ['the universe', 'and everything'] }
+      let(:logger) { instance_double(Logger) }
+
+      let(:block) { -> () { :bla } }
+
+      describe '#call' do
+        subject(:call) { advice.call(&block) }
+
+        let(:log_message) do
+          "[Time=#{Time.now}][Thread=#{Thread.current.object_id}][id=42]\
+Called: OpenStruct#the_meaning_of_life(\"the universe\", \"and everything\")"
+        end
+
+        before do
+          allow(Time).to receive(:now).and_return(Time.now)
+          allow(logger).to receive(:info)
+        end
+
+        it { is_expected.to eq(:bla) }
+
+        it do
+          expect(logger).to receive(:info).with(log_message)
+
+          call
+        end
+
+        context 'when yielding the block raises an exception' do
+          let(:block) { -> () { fail 'deu ruim!' } }
+
+          let(:log_message) do
+            "[Time=#{Time.now}][Thread=#{Thread.current.object_id}][id=42]\
+Failed: OpenStruct#the_meaning_of_life(\"the universe\", \"and everything\")
+deu ruim!"
+          end
+
+          before { allow(logger).to receive(:warn) }
+
+          it { expect { call }.to raise_error(StandardError, 'deu ruim!') }
+
+          it do
+            expect(logger).to receive(:warn).with(log_message)
+
+            expect { call }.to raise_error
+          end
+        end
+      end
+    end
+  end
+end

data/spec/advisor/builtin_advisors_spec.rb

@@ -0,0 +1,91 @@
+require 'logger'
+
+module Advisor
+  describe Factory do
+    subject(:loggable) do
+      Advices::CallLogger.default_logger = default_logger
+
+      Class.new do
+        extend Loggable
+        log_calls_to :inc
+
+        def inc(number)
+          number + 1
+        end
+
+        def foo(*)
+        end
+      end
+    end
+
+    let(:loggable_instance) { loggable.new }
+    let(:default_logger) { instance_double(Logger, info: nil, warn: nil) }
+    let(:call_logger) do
+      Advices::CallLogger.new(
+        loggable_instance, :inc, [1], logger: default_logger
+      )
+    end
+
+    before do
+      allow(Advices::CallLogger).to receive(:new)
+        .and_return(call_logger)
+    end
+
+    it 'instantiates a call logger when calling the advised method' do
+      expect(Advices::CallLogger)
+        .to receive(:new)
+        .with(loggable_instance, :inc, [1], {})
+        .and_call_original
+
+      loggable_instance.inc(1)
+    end
+
+    it 'uses the call_logger to log the method call' do
+      expect(call_logger)
+        .to receive(:call)
+        .and_call_original
+
+      loggable_instance.inc(1)
+    end
+
+    it 'does not change the return value' do
+      expect(loggable_instance.inc(1)).to eq(2)
+    end
+
+    it 'does not log when calling a non-advised method' do
+      expect(Advices::CallLogger).to_not receive(:new)
+
+      loggable_instance.foo
+    end
+
+    describe '#log_calls_to' do
+      subject(:log_calls_to) { loggable.send(:log_calls_to, :foo, :bar) }
+
+      it 'prepends an anonymous module in the ancestor chain' do
+        expect(loggable).to receive(:prepend)
+          .and_call_original
+
+        expect { log_calls_to }.to change { loggable.ancestors.count }.by(1)
+      end
+
+      context 'when redefining an advised method' do
+        let(:child_class) do
+          Class.new(loggable) do
+            def inc(number)
+              number + 2
+            end
+          end
+        end
+
+        let(:child_class_instance) { child_class.new }
+
+        it 'the advice is overridden' do
+          log_calls_to
+
+          expect(Advices::CallLogger).not_to receive(:new)
+          expect(child_class_instance.inc(1)).to eq(3)
+        end
+      end
+    end
+  end
+end

data/spec/advisor/factory_spec.rb

@@ -0,0 +1,56 @@
+describe Advisor::Factory do
+  subject(:factory) { described_class.new(advice_klass) }
+
+  let(:advice_klass) do
+    Struct.new(:obj, :method, :call_args, :args) do
+      define_method(:call) { 'overridden!' }
+      define_singleton_method(:applier_method) { 'apply_advice_to' }
+    end
+  end
+  let(:advice_instance) do
+    advice_klass.new(advised_instance, :apply_advice_to, [], arg1: 1, arg2: 2)
+  end
+
+  let(:advised_klass) do
+    advisor = build
+
+    Struct.new(:advised_method) do
+      extend advisor
+
+      apply_advice_to :advised_method, arg1: 1, arg2: 2
+    end
+  end
+  let(:advised_instance) { advised_klass.new(33) }
+
+  before do
+    allow(advised_klass).to receive(:new)
+      .and_return(advised_instance)
+
+    allow(advice_klass).to receive(:new)
+      .and_return(advice_instance)
+  end
+
+  describe '#build' do
+    subject(:build) { factory.build }
+
+    it { is_expected.to be_kind_of(Module) }
+
+    describe 'when applying the advice to methods' do
+      subject(:invoke_advised_method) { advised_instance.advised_method }
+
+      it do
+        expect(advice_klass).to receive(:new)
+          .with(advised_instance, :advised_method, [], arg1: 1, arg2: 2)
+
+        invoke_advised_method
+      end
+
+      it do
+        expect(advice_instance).to receive(:call)
+
+        invoke_advised_method
+      end
+      it { is_expected.to eq('overridden!') }
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'advisor'
+
+RSpec.configure do |config|
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: advisor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Renan Ranelli
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- renanranelli@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- Rakefile
+- Readme.org
+- advisor.gemspec
+- lib/advisor.rb
+- lib/advisor/advices.rb
+- lib/advisor/advices/call_logger.rb
+- lib/advisor/builtin_advisors.rb
+- lib/advisor/factory.rb
+- lib/advisor/version.rb
+- spec/advisor/advices/call_logger_spec.rb
+- spec/advisor/builtin_advisors_spec.rb
+- spec/advisor/factory_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/rranelli/advisor
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: AOP with anonymous modules
+test_files: []
+has_rdoc: