cheap_advice 1.0.0

data/lib/cheap_advice/configuration.rb

@@ -0,0 +1,217 @@
+require 'cheap_advice'
+
+class CheapAdvice
+  # 
+  class Configuration
+    class Error < ::CheapAdvice::Error; end
+
+    # Configuration input hash.
+    attr_accessor :config
+
+    # Hash mapping advice names to CheapAdvice objects.
+    attr_accessor :advice
+
+    # Array of CheapAdvice::Advised methods.
+    attr_accessor :advised
+
+    # Hash of file names that were explicity required before applying advice.
+    attr_accessor :required
+
+    # Flag
+    attr_accessor :config_changed
+    alias :config_changed? :config_changed
+
+    attr_accessor :verbose
+
+    def initialize opts = nil
+      opts ||= EMPTY_Hash
+      @verbose = false
+      opts.each do | k, v |
+        send(:"#{k}=", v)
+      end
+      @advice ||= { }
+      @targets = [ ]
+      @advised = [ ]
+      @required = { }
+    end
+
+    def config_changed!
+      @config_changed = true
+      self
+    end
+
+    def configure_if_changed!
+      if config_changed?
+        configure!
+        @config_changed = false
+      end
+      self
+    end
+
+    def configure!
+      disable!
+
+      # First pass: parse target and defaults.
+      c = [ ]
+      d = { }
+      get_config.each do | target_name, target_config |
+        annotate_error "target=#{target_name}" do
+          t = parse_target(target_name)
+          # _log { "#{target_name.inspect} => #{t.inspect}" }
+          case target_config
+          when true, false
+            target_config = { :enabled => target_config }
+          end
+          t.update(target_config) if target_config
+          [ :advice, :require ].each do | k |
+            t[k] = as_array(t[k]) if t.key?(k)
+          end
+          case
+          when t[:meth].nil? && t[:mod].nil? # global default.
+            d[nil] = t
+          when t[:meth].nil? # module default.
+            d[t[:mod]] = t
+          else
+            c << t # real target
+          end
+        end
+      end
+      d[nil] ||= { }
+
+      # Second pass: merge defaults with target.
+      @targets = [ ]
+      c.each do | t |
+        x = merge!(d[nil].dup, d[t[:mod]] || EMPTY_Hash)
+        t = merge!(x, t)
+        # _log { "target = #{t.inspect}" }
+        next if t[:enabled] == false
+        @targets << t
+      end
+
+      enable!
+
+      self
+    end
+
+    def disable!
+      @targets.each do | t |
+        (t[:advice] || EMPTY_Array).each do | advice_name |
+          advice_name = advice_name.to_sym
+          if advised = (t[:advised] || EMPTY_Hash)[advice_name]
+            advised.disable!
+          end
+        end
+      end
+      @advised.clear
+      self
+    end
+
+    def enable!
+      @advised.clear
+      @targets.each do | t |
+        t_str = target_as_string(t)
+        annotate_error "target=#{t_str.inspect}" do
+          (t[:require] || EMPTY_Array).each do | r |
+            _log { "#{t_str}: require #{r}" }
+            unless @required[r]
+              require r
+              @required[r] = true
+            end
+          end
+        end
+            
+        (t[:advice] || EMPTY_Array).each do | advice_name |
+          advice_name = advice_name.to_sym
+          annotate_error "target=#{target_as_string(t)} advice=#{advice_name.inspect}" do
+            unless advice = @advice[advice_name]
+              raise Error, "no advice by that name"
+            end
+            options = t[:options][nil]
+            options = merge!(options, t[:options][advice_name])
+            # _log { "#{t.inspect} options => #{options.inspect}" }
+            
+            advised = advice.advise!(t[:mod], t[:meth], t[:kind], options)
+
+            (t[:advised] ||= { })[advice_name] = advised
+
+            @advised << advised
+          end
+        end
+      end
+      self
+    end
+
+    def _log msg = nil
+      return self unless @verbose
+      msg ||= yield if block_given?
+      $stderr.puts "#{self.class}: #{msg}"
+      self
+    end
+
+    def annotate_error x
+      yield
+    rescue Exception => err
+      msg = "in #{x.inspect}: #{err.inspect}"
+      _log { "ERROR: #{msg}\n  #{err.backtrace * "\n  "}" }
+      raise Error, msg, err.backtrace
+    end
+
+    def get_config
+      case @config
+      when Hash
+        @config
+      when Proc
+        @config.call(self)
+      when nil
+        raise Error, "no config"
+      end
+    end
+
+    def as_array x
+      x = EMPTY_Array if x == nil
+      x = x.split(/\s+|\s*,\s*/) if String === x
+      raise "Unexpected Hash" if Hash === x
+      x
+    end
+
+    def parse_target x
+      case x
+      when nil
+        { }
+      when Hash
+        x
+      when String, Symbol
+        if x.to_s =~ /\A([a-z0-9_:]+)(?:([#\.])([a-z0-9_]+[=\!\?]?))?\Z/i
+          { :mod => $1,
+            :kind => $2 && ($2 == '.' ? :module : :instance),
+            :meth => $3,
+          }
+        else
+          raise Error, "cannot parse #{x.inspect}"
+        end
+      end
+    end
+    def target_as_string t
+      "#{t[:mod]}#{t[:kind] == :instance ? '#' : '.'}#{t[:meth]}"
+    end
+
+    def merge! dst, src
+      case dst
+      when nil, Hash
+        case src
+        when Hash
+          dst = dst ? dst.dup : { }
+          src.each do | k, v |
+            dst[k] = merge!(dst[k], v)
+          end
+        else
+          dst = src
+        end
+      else
+        dst = src
+      end
+      dst
+    end
+
+  end
+end

data/lib/cheap_advice/trace.rb

@@ -0,0 +1,228 @@
+require 'cheap_advice'
+
+require 'time' # Time#iso8601
+
+class CheapAdvice
+  # Sample Tracing Advice factory.
+  module Trace
+    def self.new opts = nil
+      opts ||= { }
+      trace = CheapAdvice.new(:around, opts) do | ar, body |
+        a = ar.advice
+        ad = ar.advised
+        logger = ad.logger[:name] || ad.logger_default[:name]
+        logger = a.logger[logger] || a.logger_default[logger]
+
+        formatter = nil
+        if ad[:log_before] != false
+          a.log(logger) do
+            formatter = a.new_formatter(logger)
+            ar[:time_before] = Time.now
+            formatter.record(ar, :before)
+          end
+        end
+
+        body.call
+
+        if ad[:log_after] != false
+          a.log(logger) do
+            formatter ||= a.new_formatter(logger)
+            ar[:time_after] = Time.now
+            if ar.error
+              ar[:error] = ar.error   if ad[:log_error] != false
+            else
+              ar[:result] = ar.result if ad[:log_result] != false
+            end
+            formatter.record(ar, :after)
+          end
+        end
+      end
+      trace.extend(Behavior)
+      trace.advised_extend = Behavior
+      trace
+    end
+
+    module Behavior
+      def logger
+        # $stderr.puts " #{self.class} @options = #{@options.inspect}"
+        @options[:logger] ||= { }
+      end
+      def logger_default
+        logger[nil] ||= { }
+      end
+
+      def new_formatter logger
+        formatter(logger).new(logger, *formatter_options(logger))
+      end
+
+      def formatter logger
+        logger[:formatter] ||= 
+          logger_default[:formatter] ||= 
+          DefaultFormatter
+      end
+
+      def formatter_options logger
+        logger[:formatter_options] ||=
+          logger_default[:formatter_options] ||=
+          [ ]
+      end
+
+      def log_prefix logger, ar
+        pre = 
+          logger[:log_prefix] ||= 
+          logger_default[:log_prefix] ||= 
+          EMPTY_String
+        case pre
+        when Proc
+          pre.call(ar)
+        else
+          pre
+        end
+      end
+
+      def log logger, msg = nil
+        return msg unless logger
+        msg ||= yield if block_given?
+        return msg if msg.nil?
+        dst = logger[:target]
+        case dst
+        when nil
+          nil
+        when IO
+          dst.seek(0, IO::SEEK_END)
+          dst.puts msg.to_s
+          dst.flush
+        when Proc
+          dst.call(msg)
+        else
+          dst.send(logger[:method] || :debug, msg)
+        end
+        msg
+      end
+
+      def log_all msg = nil
+        logger.values.each do | dst |
+          log(dst) { msg ||= yield if block_given?; msg }
+        end
+        msg
+      end
+
+    end
+
+    class BaseFormatter
+      attr_reader :logger
+
+      def initialize logger, *args
+        @logger = logger
+      end
+
+      def format obj, mode
+        case mode
+        when :rcvr
+          obj && obj.to_s
+        when :module
+          obj && obj.name
+        when :time
+          obj && obj.iso8601(6)
+        when :error
+          obj.inspect
+        when :result
+          obj.inspect
+        when :method
+          ad = ar.meth_to_s
+        else
+          nil
+        end
+      end
+    end
+      
+    class DefaultFormatter < BaseFormatter
+      def format obj, mode
+        case mode
+        when :error
+          return "ERROR #{obj.inspect}"
+        when :result
+          return "=> #{obj.inspect}"
+        when :time
+          return super
+        else
+          obj = super || obj
+        end
+
+        obj = obj.inspect
+        if mode == :args
+          obj = obj.to_s.gsub(/\A\[|\]\Z/, '')
+        end
+        obj
+      end
+
+      # Formats the ActivationRecord for the logger.
+      def record ar, mode
+        ad = ar.advised
+        msg = nil
+
+        case mode
+        when :before, :after
+          msg = ad.log_prefix(logger, ar).to_s
+          msg = msg.dup if msg.frozen?
+          ar[:args] ||= format(ar.args, :args) if ad[:log_args] != false
+          ar[:meth] ||= "#{ad.meth_to_s} #{ar.rcvr.class}"
+          msg << "#{format(ar[:"time_#{mode}"], :time)} #{ar[:meth]}"
+          msg << " #{format(ar.rcvr, :rcvr)}" if ad[:log_rcvr]
+          msg << " ( #{ar[:args]} )" if ar[:args]
+        end
+
+        case mode
+        when :before
+          msg << " {"
+        when :after
+          msg << " }"
+          if ar.error
+            msg << " #{format(ar[:error],  :error )}" if ad[:log_error]  != false
+          else
+            msg << " #{format(ar[:result], :result)}" if ad[:log_result] != false
+          end
+        end
+
+        msg
+      end
+    end # class
+
+    class YamlFormatter < BaseFormatter
+      def to_hash ar, mode
+        ad = ar.advised
+
+        data = (ar.advice[:log_data] || EMPTY_Hash).dup
+        data.update(ar.advised[:log_data] || EMPTY_Hash)
+        # pp [ :'ar.data=', ar.data ]
+        data.update(ar.data)
+        # pp [ :'data=', data ]
+        if x = ad.log_prefix(logger, ar)
+          data[:log_prefix] = x
+        end
+        data[:meth] = ar.meth
+        data[:mod] = Module === (x = ar.mod) ? x.name : x
+        data[:kind] = ar.kind
+        data[:signature] = ar.meth_to_s
+        data[:rcvr] = format(ar.rcvr, :rcvr) if ad[:log_rcvr]
+        data[:rcvr_class] = ar.rcvr.class.name
+        if x = data[:time_after] && 
+            data[:time_before] && 
+            (data[:time_after].to_f - data[:time_before].to_f)
+          data[:time_elapsed] = x
+        end
+        data
+      end
+
+      def record ar, mode
+        case mode
+        when :after
+          data = to_hash(ar, mode)
+          YAML.dump(data)
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/spec/cheap_advice_spec.rb

@@ -0,0 +1,342 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+class CheapAdvice
+  module Test
+
+    module M
+      attr_accessor :_m
+      def m(arg)
+        @_m = 1 + arg
+      end
+      def self.mm(arg)
+        3 + arg
+      end
+    end
+
+    class Foo
+      include M
+      attr_accessor :foo, :bar
+      attr_reader :_baz, :_bar
+      (class << self; self; end).instance_eval do 
+        attr_accessor :_baz
+      end
+      
+      def self.baz(arg)
+        self._baz = 3 + arg
+      end
+
+      def baz(arg)
+        @_baz = 5 + arg
+      end
+
+      def do_it(arg)
+        yield(arg + 7) + 2
+      end
+    end
+    
+    
+    class Bar
+      include M
+      attr_accessor :bar
+      attr_reader :_baz
+      
+      def baz(arg)
+        @_baz = 7 + arg
+      end
+
+      def calls_private_method(arg)
+        private_method(arg)
+      end
+                               
+      private
+      def private_method(arg)
+        arg
+      end
+
+      protected
+      def protected_method(arg)
+        arg
+      end
+    end
+
+    class Baz < Bar
+      def calls_protected_method(arg)
+        protected_method(arg)
+      end
+    end
+
+  end
+end
+
+
+describe "CheapAdvice" do
+  attr_reader :tracing_advice
+  attr_reader :f, :b
+
+  before(:each) do
+    @tracing_advice = CheapAdvice.new(:around) do | ar, body |
+      ar.advice.log "  TRACE: before #{ar.rcvr.class}\##{ar.meth}(#{ar.args.join(", ")})"
+      ar.advice.log "         foo = #{@foo.inspect}"
+      ar.advice.log "         bar = #{@bar.inspect}"
+      result = body.call
+      ar.advice.log "  TRACE: after  #{ar.rcvr.class}\##{ar.meth}(#{ar.args.join(", ")}) => #{result.inspect}"
+      ar.result = "yo!"
+      ar.advice.log "  TRACE: return #{ar.result.inspect}"
+      "oy!" # Not relevant.
+    end
+    @tracing_advice.instance_eval do
+      def log msg = nil
+        return @log unless msg
+        (@log ||= [ ]) << msg.dup
+      end
+    end
+  end
+
+  it "handles simple tracing_advice example." do
+    @f = CheapAdvice::Test::Foo.new
+    @b = CheapAdvice::Test::Bar.new
+
+    assert_without_advice
+    tracing_advice.log.should == nil
+
+    tracing_advice.advise!( [CheapAdvice::Test::Foo, CheapAdvice::Test::Bar], [ :bar, :bar=, :baz ])
+    f.foo = 10
+    f.foo.should == 10
+    f.baz(10).should == "yo!"
+    b.bar = 101
+    b.bar.should == "yo!"
+    b.baz(10).should == "yo!"
+    tracing_advice.log.should_not == nil
+    tracing_advice.log.size.should == 20
+    
+    tracing_advice.unadvise!
+    assert_without_advice
+  end
+
+  def assert_without_advice
+    f.foo = 10
+    f.foo.should == 10
+    f.baz(10).should == 15
+    f._baz.should == 15
+    
+    b.bar = 101
+    b.bar.should == 101
+    b.baz(10).should == 17
+    b._baz.should == 17
+  end
+
+  it 'handles methods with blocks.' do
+    ars = [ ]
+    basic_advice = CheapAdvice.new(:before) do | ar |
+      ars << ar
+    end
+    basic_advice.advised.size.should == 0
+
+    @f = CheapAdvice::Test::Foo.new
+
+    assert_do_it f
+    ars.size.should == 0
+
+    basic_advice.advise! CheapAdvice::Test::Foo, 'do_it'
+
+    basic_advice.advised.size.should == 1
+    advised = basic_advice.advised.first
+    advised.mod.should == CheapAdvice::Test::Foo
+    advised.meth.should == :do_it
+    advised.enabled.should == true
+    
+    assert_do_it f
+    ars.size.should == 1
+
+    advised.unadvise!
+    advised.enabled.should == false
+
+    assert_do_it f
+    ars.size.should == 1
+  end
+
+  def assert_do_it f
+    arg = nil
+    result = f.do_it(10) do | _arg |
+      _arg.should == 17
+      arg = _arg
+    end
+    arg.should == 17
+    result.should == 19
+  end
+
+  it 'handles applying the same advice only once.' do
+    null_advice = CheapAdvice.new(:before) do | ar |
+    end
+    null_advice.advised.size.should == 0
+
+    advised = null_advice.advise! CheapAdvice::Test::Foo, :do_it
+    null_advice.advised.size.should == 1
+
+    advised_again = null_advice.advise! CheapAdvice::Test::Foo, :do_it
+    advised_again.object_id.should == advised.object_id
+
+    null_advice.advised.size.should == 1
+
+    advised = null_advice.advise! CheapAdvice::Test::Foo, :baz, :class
+    null_advice.advised.size.should == 2
+
+    advised_again = null_advice.advise! CheapAdvice::Test::Foo, :baz, :class
+    advised_again.object_id.should == advised.object_id
+
+    null_advice.advised.size.should == 2
+
+    advised.unadvise!
+  end
+
+  it 'handles String for class and method names.' do
+    advice_called = 0
+    null_advice = CheapAdvice.new(:before) do | ar |
+      advice_called += 1
+    end
+    null_advice.advised.size.should == 0
+
+
+    @f = CheapAdvice::Test::Foo.new
+
+    advice_called.should == 0
+    
+    advised = null_advice.advise!('CheapAdvice::Test::Foo', 'baz')
+    null_advice.advised.size.should == 1
+
+    @f.baz(5).should == 10
+    @f._baz.should == 10
+    advice_called.should == 1
+
+    advised.unadvise!
+  end
+
+  it 'handles Module instance method advice.' do
+    advice_called = 0
+    null_advice = CheapAdvice.new(:before) do | ar |
+      advice_called += 1
+    end
+    null_advice.advised.size.should == 0
+
+
+    @f = CheapAdvice::Test::Foo.new
+    @b = CheapAdvice::Test::Bar.new
+
+    advice_called.should == 0
+    
+    advised = null_advice.advise!('CheapAdvice::Test::M', 'm')
+    null_advice.advised.size.should == 1
+
+    @f.m(5).should == 6
+    @f._m.should == 6
+
+    @b.m(5).should == 6
+    @b._m.should == 6
+
+    advice_called.should == 2
+
+    advised.unadvise!
+  end
+
+  it 'handles Module singleton method advice.' do
+    advice_called = 0
+    null_advice = CheapAdvice.new(:before) do | ar |
+      advice_called += 1
+    end
+    null_advice.advised.size.should == 0
+
+    advice_called.should == 0
+    
+    advised = null_advice.advise!(CheapAdvice::Test::M, :mm, :module)
+    null_advice.advised.size.should == 1
+
+    CheapAdvice::Test::M.mm(5).should == 8
+
+    advice_called.should == 1
+
+    advised.unadvise!
+  end
+
+  it 'handles Class method advice.' do
+    advice_called = 0
+    null_advice = CheapAdvice.new(:before) do | ar |
+      advice_called += 1
+    end
+    null_advice.advised.size.should == 0
+
+
+    @f = CheapAdvice::Test::Foo.new
+
+    advice_called.should == 0
+    CheapAdvice::Test::Foo._baz.should == nil
+    
+    advised = null_advice.advise!(CheapAdvice::Test::Foo, :baz, :class)
+    null_advice.advised.size.should == 1
+
+    CheapAdvice::Test::Foo.baz(5).should == 8
+    CheapAdvice::Test::Foo._baz.should == 8
+    @f.baz(5).should == 10
+    @f._baz.should == 10
+    advice_called.should == 1
+
+    advised.unadvise!
+
+    CheapAdvice::Test::Foo.baz(7).should == 10
+    CheapAdvice::Test::Foo._baz.should == 10
+    @f.baz(5).should == 10
+    @f._baz.should == 10
+    advice_called.should == 1
+  end
+
+  it 'handles private method advice.' do
+    advice_called = 0
+    null_advice = CheapAdvice.new(:before) do | ar |
+      advice_called += 1
+    end
+    null_advice.advised.size.should == 0
+
+    advice_called.should == 0
+    
+    advised = null_advice.advise!(CheapAdvice::Test::Bar, :private_method)
+    advised.scope.should == :private
+    null_advice.advised.size.should == 1
+
+    @b = CheapAdvice::Test::Bar.new
+
+    @b.calls_private_method(5).should == 5
+    advice_called.should == 1
+
+    advised.unadvise!
+
+    @b.calls_private_method(5).should == 5
+    advice_called.should == 1
+  end
+
+
+  it 'handles protected method advice.' do
+    advice_called = 0
+    null_advice = CheapAdvice.new(:before) do | ar |
+      advice_called += 1
+    end
+    null_advice.advised.size.should == 0
+
+    advice_called.should == 0
+    
+    advised = null_advice.advise!(CheapAdvice::Test::Bar, :protected_method)
+    advised.scope.should == :protected
+    null_advice.advised.size.should == 1
+
+    @b = CheapAdvice::Test::Baz.new
+
+    @b.calls_protected_method(5).should == 5
+    advice_called.should == 1
+
+    advised.unadvise!
+
+    @b.calls_protected_method(5).should == 5
+    advice_called.should == 1
+  end
+
+end
+
+