state_inspector 0.8.2 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 11c918b3bbe97063aa8b36861f654cdaf140e48f
-  data.tar.gz: 2569e2b7650a72d046ed13de7abbf52459704081
+  metadata.gz: 7e7bd7bd17c476a6dc4860357ebfc4a827b2d7ed
+  data.tar.gz: 8d046a1fa6385c108e45b321c50a3a8091ff6602
 SHA512:
-  metadata.gz: 77a143fabe9ef4ac580d0e7a63e269fce0e62bc84e20a50ec04cc6c9bba3725e292bf9df64e84b768b8e4e32b0031581c8db1f741a9a719f443fc7b925d59827
-  data.tar.gz: ab042bd6d6a00d6e30c9563b2d2a085a0d76c65cde4325c4d7b6cef2fc4c9700f089b68548ad030ab065880c9c166ee16983799a954f2c08ede016ef5a403d3d
+  metadata.gz: 5b4210564e7f9fee7f03d54cb8d2bcd779d616844940a6cc82b592b3fb35737e4ed9928008b891cb076ab900d5e2aab939cf690addf052ff3dc1b4fef5d18623
+  data.tar.gz: 1540ec589c07d4c6cf5dc14f3887d833244a3b6d0cb8063606759b88c743629e0ea1f4ac74406536f5d36e2b66a001d22ab0c3227571ef4f0640c01ff8807c9c

data/README.md

@@ -1,11 +1,10 @@
 # StateInspector
 [![Gem Version](https://badge.fury.io/rb/state_inspector.svg)](http://badge.fury.io/rb/state_inspector)
 [![Build Status](https://travis-ci.org/danielpclark/state_inspector.svg?branch=master)](https://travis-ci.org/danielpclark/state_inspector)
+[![SayThanks.io](https://img.shields.io/badge/SayThanks.io-%E2%98%BC-1EAEDB.svg)](https://saythanks.io/to/danielpclark)
 
-The original purpose of this project is to log state change on target objects.  This will expand
-further into additional introspection as new versions are made available.
-
-**Currently this project depends on attr hooks.**
+The original purpose of this project is to log state change on target objects.  This now can fully
+inform on method calls with parameters as well as instance variables.
 
 This project uses a variation of the observer pattern.  There is a hash of Reporters where you can
 mark the key as a class instance or the class itself and point it to an Observer object.  Three
@@ -47,7 +46,14 @@ end
 StateInspector::Reporter[MyClass] = SessionLoggerObserver
 
 MyClass.toggle_informant
+
+m = MyClass.new
+m.thing = :a
+
+StateInspector::Reporter[MyClass].values
+# => [["#<MyClass:0x005571fde5e498>", "@thing", nil, :a]]
 ```
+SessionLoggerObserver will by default log reports to `log/state_inspector/`.
 
 Now everytime the setter method is used for `thing` a new line will be entered into a log file
 of the object, method, old value, and new value.  So you will see what is changed from where in
@@ -59,6 +65,44 @@ on the class itself then simply execute that method on the instances you want to
 
 If you want to see the expected results of the current observer/reporters then see [test/reporter_test.rb](https://github.com/danielpclark/state_inspector/blob/master/test/reporter_test.rb).
 
+If you want to only toggle an informant for a small area you may use a helper method to toggle the
+observer on and off for you.
+
+```ruby
+require 'state_inspector/helper'
+include Helper
+
+# instead of doing MyClass.toggle_informant as above, do this.
+
+m = MyClass.new
+toggle_snoop(m) do
+  # put your own code here
+end
+```
+
+When writing tests for code and using StateInspector it's very important to ensure the informant is
+untoggled.  Otherwise you will have sporatic behavior in your tests.  You may use the helpers provided
+here for your tests to ensure you won't have glitchy tests as a result of using informants.
+
+To include it in Minitest you would do:
+
+```ruby
+# test/test_helper.rb or test/minitest_helper.rb
+
+require 'state_inspector/helper'
+class Minitest::Test
+  include StateInspector::Helper
+end
+```
+
+The default behavior for toggling on an informant for the first time is to inject code to observe all
+setter methods.  This is true for both the Object method `toggle_informant` and the helper method
+`toggle_snoop`.  If you would like to avoid injecting all setter methods for reporting you may either
+use `state_inspector.skip_setter_snoops` (before any toggling) or the helper `toggle_snoop_clean` which
+will cleanly remove its anti-setter hook once done (meaning the next `toggle_informant` will inject the
+informant code into all setters).
+
+
 ## Observers
 
 To include all Observers into scope you can do:
@@ -112,15 +156,64 @@ And to register this observer to a target class you simply write:
 StateInspector::Reporter[MyTargetClass] = ExampleObserver
 ```
 
+## Manually Create Informers
+
+To manually create informant methods use `state_inspector.snoop_setters :a=, :b=` and
+`state_inspector.snoop_methods :a, :b`.  
+
+```ruby
+require 'state_inspector'
+require 'state_inspector/observers/internal_observer'
+include StateInspector::Observers
+
+class MyClass
+  attr_writer :a, :b, :c
+  def x *args; end
+end
+
+# InternalObserver (it can be used with many classes and hold all of the data)
+# InternalObserver.new (will hold data for only the specific reporter object pointing to it)
+StateInspector::Reporter[MyClass] = InternalObserver
+
+# This will allow us to manually define which setter methods to inform on
+MyClass.state_inspector.skip_setter_snoops
+
+m = MyClass.new
+m.toggle_informant
+m.state_inspector.snoop_setters :b=, :c=
+m.state_inspector.snoop_methods :x
+m.a= 1
+m.b= 2
+m.c= 3
+m.x 4, 5, 6
+
+StateInspector::Reporter[MyClass].values
+# => [
+#      [#<MyClass:0x005608eb9aead0 @informant=true, @a=1, @b=2, @c=3>, "@b", nil, 2],
+#      [#<MyClass:0x005608eb9aead0 @informant=true, @a=1, @b=2, @c=3>, "@c", nil, 3],
+#      [#<MyClass:0x005608eb9aead0 @informant=true, @a=1, @b=2, @c=3>, :x, 4, 5, 6]
+#    ]
+```
+The nils in the values above represent the previous value the instance variable returned.
+
+## Reporter Legend
+
+The format of a report sent will always start with the object that sent it; aka `self`.  Next you will
+have either a string representing and instance variable of a symbol representing a method call.  If it's
+an instance variable then the next value will be the old value for that instance variable, and the next
+value is the value given to the method to be set as the value for that instance variable.  If the second
+item is a symbol then every item after that is the parameters sent to that method.
+
 
-## Road Map
+LEGEND FOR SETTER| _ | _ | _
+-----------------|---|---|---
+`self` | `@instance_variable` | `:old_value` | `:new_value_given`
 
-* 0.8.0 State inspection of all flagged objects on setter methods.
-Includes logger observer, internal observer, and null observer.
 
-* 0.9.0 Sweep for missed setter methods and prepend inspection behavior.
+LEGEND FOR METHOD| _ | _ 
+-----------------|---|---
+`self` | `:method_name` | `:arguments`
 
-* 1.0.0 Optional reporting on all/target method calls
 
 ## Development
 

data/lib/state_inspector/helper.rb

@@ -0,0 +1,21 @@
+module StateInspector
+  module Helper
+    def toggle_snoop(obj)
+      obj.toggle_informant
+      yield
+    ensure
+      obj.toggle_informant
+    end
+
+    def toggle_snoop_clean(obj)
+      obj.state_inspector.skip_setter_snoops
+      obj.toggle_informant
+      yield
+    ensure
+      obj.toggle_informant
+      obj.instance_exec {@state_inspector = nil} if obj.
+        instance_variable_get(:@state_inspector).
+        tap {|h| h.is_a?(Hash) ? h.empty? : h}
+    end
+  end
+end

data/lib/state_inspector/snoop.rb

@@ -7,39 +7,24 @@ module StateInspector
       base.include ClassMethods
     end
 
-    def attr_writer *attr_names
-      attr_names.each do |attr_name|
-        define_method("#{attr_name}=") do |value|
-          tell_si __method__.to_s.chop,
-            instance_variable_get("@#{attr_name.to_s}"),
-            value 
-
-          instance_variable_set("@#{attr_name.to_s}", value)
-        end
-      end
-      nil
-    end
-
-    def attr_accessor *attr_names
-      attr_names.each do |attr_name|
-        define_method("#{attr_name}") do
-          instance_variable_get("@#{attr_name.to_s}")
-        end
-
-        self.attr_writer(attr_name)
-      end
-    end
-
     module ClassMethods
       def state_inspector
-        StateInspector
+        StateInspector.new(self)
       end
 
-      def tell_si what, old, new
-        state_inspector.report( self, "@#{what.to_s}", old, new ) if informant?
+      def tell_si *args, &block
+        if informant?
+          key = self.respond_to?(:class_eval) ? self : self.class
+          Reporter[key].update(self, *args, &block)
+        end
       end
 
       def toggle_informant
+        state_inspector.snoop_setters(
+          *(self.respond_to?(:class_eval) ? self : self.class).
+          instance_methods.grep(/=\z/) - Object.methods
+        ) unless @state_inspector || self.class.instance_variable_get(:@state_inspector)
+
         @informant = !@informant
       end
 

data/lib/state_inspector/state_inspector.rb

@@ -1,8 +1,56 @@
 module StateInspector
   class StateInspector
-    def self.report who, what, old, new
-      key = who.respond_to?(:class_eval) ? who : who.class
-      Reporter[key].update who, what, old, new
+    def initialize base, **opts
+      @base = base # pass in self
+    end
+
+    def snoop_setters *setters
+      base.class_exec do
+        setters.
+          delete_if {|m| (@state_inspector ||= {}).fetch(m){ nil } }.
+          each do |m|
+            (@state_inspector ||= {})[m] = __method__
+            single = singleton_methods.include? m
+            original_method = (single ? singleton_method(m) : instance_method(m))
+            send((single ? :define_singleton_method : :define_method), m) do |*args, &block|
+              var = "@#{__method__.to_s.chop}"
+              tell_si var, instance_variable_get(var), *args, &block
+              original_method = (single ? original_method.unbind : original_method)
+              original_method.bind(self).call(*args, &block)
+            end
+          end
+      end
+    end
+
+    def snoop_methods *meth0ds
+      base.class_exec do
+        meth0ds.
+          delete_if {|m| (@state_inspector ||= {}).fetch(m){ nil } }.
+          each do |m|
+            (@state_inspector ||= {})[m] = __method__
+            single = singleton_methods.include? m
+            original_method = (single ? singleton_method(m) : instance_method(m))
+            send((single ? :define_singleton_method : :define_method), m) do |*args, &block|
+              tell_si __method__, *args, &block
+              original_method = (single ? original_method.unbind : original_method)
+              original_method.bind(self).call(*args, &block)
+            end
+          end
+      end
+    end
+
+    def skip_setter_snoops
+      base.instance_variable_set(:@state_inspector, Hash.new) unless base.
+        instance_variable_defined? :@state_inspector
+    end
+
+    private
+    def base
+      if @base.respond_to? :class_eval
+        @base
+      else
+        @base.class
+      end
     end
   end
 end

data/lib/state_inspector/version.rb

@@ -1,3 +1,3 @@
 module StateInspector
-  VERSION = "0.8.2"
+  VERSION = "1.0.0.rc1"
 end

data/state_inspector.gemspec

@@ -24,4 +24,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.13"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "minitest-reporters", "~> 1.1"
+  spec.add_development_dependency "color_pound_spec_reporter", "~> 0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: state_inspector
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Daniel P. Clark
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-01-20 00:00:00.000000000 Z
+date: 2017-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: color_pound_spec_reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
 description: Introspection tool for reporting state change.  Instance varialbes and
   method call debugging.
 email:
@@ -69,6 +97,7 @@ files:
 - bin/console
 - bin/setup
 - lib/state_inspector.rb
+- lib/state_inspector/helper.rb
 - lib/state_inspector/observers.rb
 - lib/state_inspector/observers/internal_observer.rb
 - lib/state_inspector/observers/null_observer.rb
@@ -94,9 +123,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.8