state_inspector 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 3d15f153b234a84d1a55dfcdabf0da072a54525b3f4e002264903886dffcbe0f
-  data.tar.gz: 5dfc62c1219a7eed867d36b08bf00e03c954ca4f505dd26dc1b64d4bee6998d9
+SHA1:
+  metadata.gz: fe629c67e180cfa586f4543e4d0bb416fa1694e1
+  data.tar.gz: 14cf88964e95a255333b1890aac132ca45df850f
 SHA512:
-  metadata.gz: 1270b6929c3ff8ba30e83ddb07aebf41f1ba3d60f0b33feac2b4275fe3f3b8b48c2f25bb9e6ba9ebb6ec6ef22acf31599e560d0bb2a2a2c93e02ccd719b74d25
-  data.tar.gz: 46e4b286c61f4232dc01acd8ae7bc1876d2c77923af2099070f85d38bc22f071cc00c754acdb17c947fcd3ff089f01f2589afd300da907671d148bc7877f5f00
+  metadata.gz: 6499a6c6fd0b6d43e0b14e9b9677fd57ed5a7e185e845ff910f7a563221f9b08974cc38a8add1199af3c70dc4cb6b61970f15158db0aca072c69c7fbcb280032
+  data.tar.gz: c7af11123487b76d83de3c3653869275e2cbda55c0dacfc3ced4fd5e4a9e175ba53b6a7d08034c7a566fcbbef81890fa5512009c82009af9d5b1aac0d339d543

data/README.md

@@ -1,10 +1,10 @@
+<img src="https://s23.postimg.org/4iiqow7xn/observer_hooks3.png" alt="Observer Hooks" align="right" width="50" height="44" />
 # 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 now can fully
-inform on method calls with parameters as well as instance variables.
+This can fully inform on object method calls and parameters as well as instance variables before and after (when called via a setter method).  In short this utilizes the decorator patttern and the observer pattern to hook and report when a method is called.  In simple terms it will wrap any methods you choose with a hook that sends off all the details of the method call when it is executed to a reporter/observer of your choosing.
 
 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
@@ -29,7 +29,7 @@ Or install it yourself as:
 
     $ gem install state_inspector
 
-## Usage
+## Complex Usage
 
 The preferred usage is to pick what classes you want to track state change in and have them logged to
 a session logger.  To do this you would need to do the following.
@@ -65,19 +65,31 @@ 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).
 
+## Simple Usage
+
 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.
 
+When you include `StateInspector::Helper` it handles requiring the existing observers and bringing them
+into scope.  You are free to pass in an observer as a second paramater to the `toggle_snoop` helper method
+which will only be assigned for the scope of the block of code.
+
 ```ruby
 require 'state_inspector/helper'
-include Helper
+include StateInspector::Helper
 
 # instead of doing MyClass.toggle_informant as above, do this.
 
 m = MyClass.new
-toggle_snoop(m) do
+observer = InternalObserver.new
+
+# observer parameter optional.  Assign beforehand if not provided here.
+toggle_snoop(m, observer) do
   # put your own code here
 end
+
+# look at the results
+observer.values
 ```
 
 When writing tests for code and using StateInspector it's very important to ensure the informant is
@@ -226,6 +238,25 @@ LEGEND FOR METHOD| _ | _
 `self` | `:method_name` | `:arguments`
 
 
+## Session Logger
+
+The session logger is an observer that saves all output to a log file.  A default log file is saved to `log/state_inspector/<timestamp>.log`.  You can manually set a log file with the `file=` method on the SessionLoggerObserver which may be helpful for situations where the code runs in a temporary directory and vanishes upon completion (like the rubygems test suite).
+
+Here's an example that catches all setter method calls from constants within the `Gem` class.  _Placed at start of file to observe._
+
+```ruby
+require 'state_inspector'
+require 'state_inspector/observers/session_logger_observer'
+include StateInspector::Observers
+
+SessionLoggerObserver.file = "/home/myhomedir/dev/rubygems/log/output.log"
+StateInspector::Reporter.default SessionLoggerObserver
+Gem.constants.each {|c| a = eval("Gem::#{c}"); if a.is_a? Class; a.toggle_informant end}
+```
+This example is a very expensive one as we set the default observer/reporter to `SessionLoggerObserver` which means it catches **all reports not previously assigned**.  The last line simply finds all class objects within the Gem namespace and toggles-on the informants (which by default hooks in listeners to each setter method).  The `file=` method used here overwrites the default and guarantees where the data will be written.
+
+I've tried the above code in the rubygems test suite on one file `test/rubygems/test_gem_dependency_installer.rb`.  When running this file it records 7756 lines worth of information.  This is clearly too much information to parse manually which is why I highly recommend using the scoped helper methods to toggle on and off the behavior around the code you are specifically interested in.  You can still toggle informers on many classes like what was done above, but the more objects you do the more I recommend you narrow down the scope of what you're capturing (like to one specific test in a test suite).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -241,3 +272,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/daniel
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
+

data/lib/state_inspector/helper.rb

@@ -1,20 +1,38 @@
+require 'state_inspector'
+require 'state_inspector/observers'
 module StateInspector
   module Helper
-    def toggle_snoop(obj)
+    def self.included(base)
+      base.include Observers
+    end
+
+    def toggle_snoop(obj, observer=nil)
+      if observer
+        old_observer = Reporter.has_observer?(obj) ? Reporter[obj] : nil
+        Reporter[obj] = observer
+      end
       obj.toggle_informant
-      yield
+      value = yield Reporter[obj]
     ensure
       obj.toggle_informant
+      (old_observer.nil? ? Reporter.drop(obj) : Reporter[obj] = old_observer) if observer
+      value
     end
 
-    def toggle_snoop_clean(obj)
+    def toggle_snoop_clean(obj, observer=nil)
       obj.state_inspector.skip_setter_snoops
+      if observer
+        old_observer = Reporter.has_observer?(obj) ? Reporter[obj] : nil
+        Reporter[obj] = observer
+      end
       obj.toggle_informant
-      yield
+      value = yield Reporter[obj]
     ensure
       obj.toggle_informant
       (obj.respond_to?(:class_eval) ? obj : obj.class).
         remove_instance_variable(:@state_inspector) 
+      (old_observer.nil? ? Reporter.drop(obj) : Reporter[obj] = old_observer) if observer
+      value
     end
   end
 end

data/lib/state_inspector/reporter.rb

@@ -13,6 +13,19 @@ module StateInspector
         reporters[key] = value
       end
 
+      def has_key? key
+        reporters.has_key?(key)
+      end
+
+      def has_observer? key
+        class_key = key.respond_to?(:class_eval) ? key : key.class
+        reporters.has_key?(key) || reporters.has_key?(class_key)
+      end
+
+      def drop key
+        reporters.delete key
+      end
+
       def default observer=nil
         @default = observer if observer
         reporters.default = @default 

data/lib/state_inspector/snoop.rb

@@ -15,6 +15,7 @@ module StateInspector
       def tell_si *args, &block
         if informant?
           key = self.respond_to?(:class_eval) ? self : self.class
+          key = Reporter.has_key?(key) ? key : self
           Reporter[key].update(self, *args, &block)
         end
       end

data/lib/state_inspector/version.rb

@@ -1,3 +1,3 @@
 module StateInspector
-  VERSION = "1.0.2"
+  VERSION = "1.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: state_inspector
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Daniel P. Clark
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-01-27 00:00:00.000000000 Z
+date: 2017-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler