{"id":16687959,"url":"https://github.com/danielpclark/state_inspector","last_synced_at":"2025-10-09T00:41:03.115Z","repository":{"id":59156374,"uuid":"79502781","full_name":"danielpclark/state_inspector","owner":"danielpclark","description":"State change \u0026 method call logger.  A debugging tool for instance variables and method calls.","archived":false,"fork":false,"pushed_at":"2018-12-20T15:08:19.000Z","size":70,"stargazers_count":25,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-03T05:46:15.635Z","etag":null,"topics":["debug","decorators","feature-complete","hooks","introspect","log","observable","observer","observer-pattern","reporting","ruby","ruby-gem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielpclark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-19T22:44:20.000Z","updated_at":"2024-10-16T12:00:05.000Z","dependencies_parsed_at":"2022-09-13T20:10:19.747Z","dependency_job_id":null,"html_url":"https://github.com/danielpclark/state_inspector","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/danielpclark/state_inspector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielpclark%2Fstate_inspector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielpclark%2Fstate_inspector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielpclark%2Fstate_inspector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielpclark%2Fstate_inspector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielpclark","download_url":"https://codeload.github.com/danielpclark/state_inspector/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielpclark%2Fstate_inspector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278561274,"owners_count":26006954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debug","decorators","feature-complete","hooks","introspect","log","observable","observer","observer-pattern","reporting","ruby","ruby-gem"],"created_at":"2024-10-12T15:26:08.185Z","updated_at":"2025-10-09T00:41:03.098Z","avatar_url":"https://github.com/danielpclark.png","language":"Ruby","readme":"# StateInspector\n\n[![Gem Version](https://badge.fury.io/rb/state_inspector.svg)](http://badge.fury.io/rb/state_inspector)\n[![Build Status](https://travis-ci.org/danielpclark/state_inspector.svg?branch=master)](https://travis-ci.org/danielpclark/state_inspector)\n[![SayThanks.io](https://img.shields.io/badge/SayThanks.io-%E2%98%BC-1EAEDB.svg)](https://saythanks.io/to/danielpclark)\n\nThis 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.\n\nThis project uses a variation of the observer pattern.  There is a hash of Reporters where you can\nmark the key as a class instance or the class itself and point it to an Observer object.  Three\nobservers are included for you to use under StateInspector::Observers which are NullObserver (default),\nInternalObserver, and SessionLoggerObserver.  When you toggle on an \"informant\" on a class instance or\nclass then each time a setter method is called it will pass that information on to the relevant observer\nwhich handles the behavior you want to occur with that information.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'state_inspector'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install state_inspector\n\n## Complex Usage\n\nThe preferred usage is to pick what classes you want to track state change in and have them logged to\na session logger.  To do this you would need to do the following.\n\n```ruby\nrequire 'state_inspector'\nrequire 'state_inspector/observers/session_logger_observer'\ninclude StateInspector::Observers\n\nclass MyClass\n  attr_writer :thing\nend\n\nStateInspector::Reporter[MyClass] = SessionLoggerObserver\n\nMyClass.toggle_informant\n\nm = MyClass.new\nm.thing = :a\n\nStateInspector::Reporter[MyClass].values\n# =\u003e [[\"#\u003cMyClass:0x005571fde5e498\u003e\", \"@thing\", nil, :a]]\n```\nSessionLoggerObserver will by default log reports to `log/state_inspector/`.\n\nNow everytime the setter method is used for `thing` a new line will be entered into a log file\nof the object, method, old value, and new value.  So you will see what is changed from where in\nthe order that the changed occurred.  This session logger will grab as many objects state changes\nas you want and give you a nice ordered history of what has occurred.\n\nIf you don't want to inform on all instances of a class then instead of running `toggle_informant`\non the class itself then simply execute that method on the instances you want to observe.\n\nIf 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).\n\n## Simple Usage\n\nIf you want to only toggle an informant for a small area you may use a helper method to toggle the\nobserver on and off for you.\n\nWhen you include `StateInspector::Helper` it handles requiring the existing observers and bringing them\ninto scope.  You are free to pass in an observer as a second paramater to the `toggle_snoop` helper method\nwhich will only be assigned for the scope of the block of code.\n\n```ruby\nrequire 'state_inspector/helper'\ninclude StateInspector::Helper\n\n# instead of doing MyClass.toggle_informant as above, do this.\n\nclass MyClass\n  attr_writer :thing\nend\n\nm = MyClass.new\nobserver = InternalObserver.new\n\n# observer parameter optional.  Assign beforehand if not provided here.\ntoggle_snoop(m, observer) do\n  m.thing = 4\nend\n\n# look at the results\nobserver.values\n# =\u003e [[#\u003cMyClass:0x00562f969dee48 @informant=false, @thing=4\u003e, \"@thing\", nil, 4]]\n```\n\nWhen writing tests for code and using StateInspector it's very important to ensure the informant is\nuntoggled.  Otherwise you will have sporatic behavior in your tests.  You may use the helpers provided\nhere for your tests to ensure you won't have glitchy tests as a result of using informants.\n\nTo include it in Minitest you would do:\n\n```ruby\n# test/test_helper.rb or test/minitest_helper.rb\n\nrequire 'state_inspector/helper'\nclass Minitest::Test\n  include StateInspector::Helper\nend\n```\n\nThe default behavior for toggling on an informant for the first time is to inject code to observe all\nsetter methods.  This is true for both the Object method `toggle_informant` and the helper method\n`toggle_snoop`.  If you would like to avoid injecting all setter methods for reporting you may either\nuse `state_inspector.skip_setter_snoops` (before any toggling) or the helper `toggle_snoop_clean` which\nwill cleanly remove its anti-setter hook once done (meaning the next `toggle_informant` will inject the\ninformant code into all setters).\n\nThe helper block also pipes in the current observer for the object you're toggling. So you may access\nit within the block by pipe assigning it to a variable.\n\n```ruby\ntoggle_snoop(m) do |observer|\n  observer # Whatever observer happens to be assigned to this object or its class\nend\n\n```\n\n## Observers\n\nTo include all Observers into scope you can do:\n\n```ruby\nrequire 'state_inspector/observers'\ninclude StateInspector::Observers\n```\n\nYou may look at the available observers in [state_inspector/observers](https://github.com/danielpclark/state_inspector/tree/master/lib/state_inspector/observers).\n\nObservers will have a few methods they each have in common.\n\n```ruby\nmodule Observer\n  def update *vals\n    values() \u003c\u003c vals\n  end\n\n  def display\n    values.join \" \"\n  end\n\n  def values\n    @values ||= []\n  end\n\n  def purge\n    @values = []\n  end\nend\n```\n\nWhen you're writing your own observer you'll include this Observer onto a module's instance and\noverwrite whatever methods you want there.\n\n```ruby\nmodule ExampleObserver\n  class \u003c\u003c self\n    include Observer\n    def display\n      \"Custom display code here\"\n    end\n  end\nend\n```\n\nAnd to register this observer to a target class you simply write:\n\n```ruby\nStateInspector::Reporter[MyTargetClass] = ExampleObserver\n```\n\n## Manually Create or Remove Informers\n\nTo manually create informant methods use `state_inspector.snoop_setters :a=, :b=` and\n`state_inspector.snoop_methods :a, :b`.  \n\n```ruby\nrequire 'state_inspector'\nrequire 'state_inspector/observers/internal_observer'\ninclude StateInspector::Observers\n\nclass MyClass\n  attr_writer :a, :b, :c\n  def x *args; end\nend\n\n# InternalObserver (it can be used with many classes and hold all of the data)\n# InternalObserver.new (will hold data for only the specific reporter object pointing to it)\nStateInspector::Reporter[MyClass] = InternalObserver\n\n# This will allow us to manually define which setter methods to inform on\nMyClass.state_inspector.skip_setter_snoops\n\nm = MyClass.new\nm.toggle_informant\nm.state_inspector.snoop_setters :b=, :c=\nm.state_inspector.snoop_methods :x\nm.a= 1\nm.b= 2\nm.c= 3\nm.x 4, 5, 6\n\nStateInspector::Reporter[MyClass].values\n# =\u003e [\n#      [#\u003cMyClass:0x005608eb9aead0 @informant=true, @a=1, @b=2, @c=3\u003e, \"@b\", nil, 2],\n#      [#\u003cMyClass:0x005608eb9aead0 @informant=true, @a=1, @b=2, @c=3\u003e, \"@c\", nil, 3],\n#      [#\u003cMyClass:0x005608eb9aead0 @informant=true, @a=1, @b=2, @c=3\u003e, :x, 4, 5, 6]\n#    ]\n```\nThe nils in the values above represent the previous value the instance variable returned.\n\n#### Remove Informers\n\nTo remove informers simply use `state_inspector.restore_methods`.  This takes out the hook from\neach method that waits for the `informer?` method to be true.\n\n```ruby\n# continuing from the above example\n\nm.state_inspector.restore_methods :b=, :c=, :x\n```\n\n## Reporter Legend\n\nThe format of a report sent will always start with the object that sent it; aka `self`.  Next you will\nhave either a string representing and instance variable of a symbol representing a method call.  If it's\nan instance variable then the next value will be the old value for that instance variable, and the next\nvalue is the value given to the method to be set as the value for that instance variable.  If the second\nitem is a symbol then every item after that is the parameters sent to that method.\n\n\nLEGEND FOR SETTER| _ | _ | _\n-----------------|---|---|---\n`self` | `@instance_variable` | `:old_value` | `:new_value_given`\n\n\nLEGEND FOR METHOD| _ | _ \n-----------------|---|---\n`self` | `:method_name` | `:arguments`\n\n\n## Session Logger\n\nThe session logger is an observer that saves all output to a log file.  A default log file is saved to `log/state_inspector/\u003ctimestamp\u003e.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).\n\nHere's an example that catches all setter method calls from constants within the `Gem` class.  _Placed at start of file to observe._\n\n```ruby\nrequire 'state_inspector'\nrequire 'state_inspector/observers/session_logger_observer'\ninclude StateInspector::Observers\n\nSessionLoggerObserver.file = \"/home/myhomedir/dev/rubygems/log/output.log\"\nStateInspector::Reporter.default SessionLoggerObserver\nGem.constants.each {|c| a = eval(\"Gem::#{c}\"); if a.is_a? Class; a.toggle_informant end}\n```\nThis 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.\n\nI'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).\n\n## Development\n\nAfter 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.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/danielpclark/state_inspector.\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielpclark%2Fstate_inspector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielpclark%2Fstate_inspector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielpclark%2Fstate_inspector/lists"}