object_inspector 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd42799a69895e8a918436eaa6688090722f4dde5d406f34b36eae201459f82a
-  data.tar.gz: 1ea233bec14fddd0b57ffb797da6009471f8f9f989fee45f204af8813b70f59e
+  metadata.gz: b814c9a90935be0339c6bf2ce1e2e0547b5ccb4b59a26feb40d91082cd9c7b2a
+  data.tar.gz: 6f024e9206a497fa173a3e7aff23ae9334b1eacd8cacb4559675ae5db5c3aa1f
 SHA512:
-  metadata.gz: f30121bcdddfd33c7990197e4513eb44a84a487afc4f346a5823067760e2754aaf7ae0871ae58157ef45686de4a885e2db798e97e7a35671c5b0143fedafb11c
-  data.tar.gz: 4ed8d2ac33b52b4af28bc621a2e92fd429039c6951a2d8d10a38e866a9d101e2f18d24a60125fb189b367232293068c63a3ca0ec0bdaa1bb6df37119f26db5d0
+  metadata.gz: 41a2fc9fa580c3ce169bfb5dd8b110d5c9d66635d85cde16c689e42ff91354dbbdd042a7bd45f57381c46e04de6938d91310b79f79a64a56dbd53f6d7f81e37b
+  data.tar.gz: 9ab9384c13706f95f8a1ced4fdf2d0e2162dbad989a709f226026ff6d0be89844392eaf182044fb62d314eac9a2f645a3bacf1ba351a95821b555960fb8d38fa

data/README.md

@@ -66,108 +66,33 @@ ObjectInspector.configure do |config|
   config.default_scope = ObjectInspector::Scope.new(:self)
   config.wild_card_scope = "all"
   config.out_of_scope_placeholder = "*"
-  config.presenter_inspect_flags = " ⇨ "
+  config.presented_object_separator = " ⇨ "
   config.name_separator = " - "
   config.flags_separator = " / "
   config.issues_separator = " | "
   config.info_separator = " | "
+  config.error_handler = ->(exception, object:) {}
 end
 ```
 
 ## Usage
 
-Pass an object of any type into `ObjectInspector::Inspector.inspect`.
-
-```ruby
-class MyObject
-  def inspect
-    ObjectInspector::Inspector.inspect(self)
-  end
-end
-
-MyObject.new.inspect # => "<MyObject>"
-
-MyObject.new # =>
-<MyObject>
-```
-
-See: [Helper Usage](#helper-usage) for simpler usage.
-
-### Output Customization
-
-Use the `identification`, `flags`, `issues`, `info`, and/or `name` options to customize inspect output.
-
-```ruby
-class MyObject
-  def inspect
-    ObjectInspector::Inspector.inspect(
-      self,
-      identification: "My Object",
-      flags: "FLAG1 / FLAG2",
-      issues: "ISSUE1",
-      info: "INFO",
-      name: "NAME")
-  end
-end
-
-MyObject.new # =>
-<My Object(FLAG1 / FLAG2) !!ISSUE1!! INFO :: NAME>
-```
-
-Or, define `inspect_identification`, `inspect_flags`, `inspect_issues`, `inspect_info`, and/or `inspect_name` (or `display_name`) as either public or private methods on Object.
-
-```ruby
-class MyObject
-  def inspect
-    ObjectInspector::Inspector.inspect(self)
-  end
-
-  private
-
-  def inspect_identification = "My Object"
-  def inspect_flags = "FLAG1 / FLAG2"
-  def inspect_issues = "ISSUE1 | ISSUE2"
-  def inspect_info = "INFO"
-  def inspect_name = "NAME"  # Or: def display_name = "NAME"
-end
-
-MyObject.new # =>
-<My Object(FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>
-```
-
-## Helper Usage
-
-To save some typing, include ObjectInspector::InspectBehaviors into an object and `ObjectInspector::Inspector.inspect` will be called on `self` automatically.
+Including `ObjectInspector::InspectBehaviors` into an object will cause `ObjectInspector::Inspector.inspect` to be called on `self` automatically.
 
 ```ruby
 class MyObject
   include ObjectInspector::InspectBehaviors
 end
 
-MyObject.new # =>
-<MyObject>
-```
-
-To access the ObjectInspector::Inspector's options via the helper, call into `super`.
-
-```ruby
-class MyObject
-  include ObjectInspector::InspectBehaviors
-
-  def inspect
-    super(identification: "My Object",
-          flags: "FLAG1",
-          issues: "ISSUE1 | ISSUE2",
-          info: "INFO",
-          name: "NAME")
-  end
-end
+MyObject.new.inspect # =>
+"<MyObject>"
 
+# NOTE: IRB's Pretty Print processor calls `inspect` and unwraps the quotes:
 MyObject.new # =>
-<My Object(FLAG1) !!ISSUE1 | ISSUE2!! INFO :: NAME>
+<MyObject>
 ```
 
-Or, define `inspect_identification`, `inspect_flags`, `inspect_info`, and/or `inspect_name` (or `display_name`) in Object.
+Build out the inspect String by defining any of: `inspect_identification`, `inspect_flags`, `inspect_issues`, `inspect_info`, and `inspect_name` (or `display_name`).
 
 ```ruby
 class MyObject
@@ -182,40 +107,11 @@ class MyObject
   def inspect_name = "NAME"  # Or: def display_name = "NAME"
 end
 
-MyObject.new # =>
-<My Object(FLAG1) !!ISSUE1 | ISSUE2!! INFO :: NAME>
-```
-
-### Disabling ObjectInspector
-
-You may disable / re-enable Object Inspector output (via the included helper method) for the current session:
-
-```ruby
-MyObject.new # =>
-<My Object(FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>
-
-ObjectInspector.configuration.disable # =>
- -> ObjectInspector disabled
-MyObject.new # =>
-#<MyObject:0x000000012332c458>
-
-ObjectInspector.configuration.enable # =>
- -> ObjectInspector enabled
 MyObject.new # =>
 <My Object(FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>
 ```
 
-Or, toggle current state:
-
-```ruby
-ObjectInspector.configuration.toggle; # =>
- -> ObjectInspector disabled
-
-ObjectInspector.configuration.toggle; # =>
- -> ObjectInspector enabled
-```
-
-### Helper Inclusion
+### Customizing `ObjectInspector::InspectBehaviors`
 
 Instead of including `ObjectInspector::InspectBehaviors` directly, it may be useful to define your own mix-in.
 
@@ -231,52 +127,41 @@ module ObjectInspectionBehaviors
 end
 ```
 
-#### Usage:
-
-```ruby
-class MyObject
-  include ObjectInspectionBehaviors # 👀 Defined above.
-
-  private
-
-  def inspect_identification = "My Object"
-  def inspect_flags = "FLAG1 / FLAG2"
-  def inspect_issues = "ISSUE1 | ISSUE2"
-  def inspect_info = "INFO"
-  def inspect_name = "NAME"  # Or: def display_name = "NAME"
-end
-
-MyObject.new # =>
-<My Object(FLAG1) !!ISSUE1 | ISSUE2!! INFO :: NAME>
-```
-
 ## Scopes
 
-Use the `scope` option to define the scope of the `inspect_*` methods. The supplied value will be wrapped by the ObjectInspector::Scope helper object.
-The default value is `ObjectInspector::Scope.new(:self)`.
+Use the `scope` option to define when each of the `inspect_*` methods should be included. The default scope is `:self`, or `ObjectInspector::Scope.new(:self)`.
 
 ### Scope Names
 
-ObjectInspector::Scope acts like an [ActiveSupport::StringInquirer](http://api.rubyonrails.org/classes/ActiveSupport/StringInquirer.html). This is a prettier way to test for a given type of "scope" within objects.
+ObjectInspector::Scope acts like an [ActiveSupport::StringInquirer](http://api.rubyonrails.org/classes/ActiveSupport/StringInquirer.html).
 
-The ObjectInspector::Scope objects in these examples are the same as specifying `<scope_name>` like this:
+Call `inspect` with a scope name like:
 
 ```ruby
 my_object.inspect(scope: <scope_name>)
 ```
 
-Options:
+#### Default Scope Names:
+
+The default scope is: `:self`.
 
-- `:self` (Default)--Is meant to confine object interrogation to self (don't interrogate neighboring objects).
-- `:all`--Is meant to match on all scopes, regardless of their name.
-- `<custom>`--Anything else that makes sense for the object to key on.
+- `:self` (Default): Is meant to restrict object interrogation to self.
+
+#### Custom Scope Names:
+
+Beyond just `:self`, any name can be used to define any scope that makes sense for your project. No need to provision them up front, just start using them! Suggested additional scope names include:
+
+- `:verbose`: For extra detail that may not normally be needed.
+- `:complex`: For revealing collaborating objects (used to prevent n+1 queries in the normal case)
 
 ```ruby
-scope = ObjectInspector::Scope.new
-scope.self?       # => true
-scope.verbose?    # => false
-scope.complex?    # => false
-scope.<anything>? # => false
+def inspect(scope:)
+  scope.inspect     # => <ObjectInspector::Scope :: ["self"]>
+  scope.self?       # => true
+  scope.verbose?    # => false
+  scope.complex?    # => false
+  scope.<anything>? # => false
+end
 ```
 
 #### Multiple Scope Names
@@ -284,10 +169,12 @@ scope.<anything>? # => false
 It is also possible to pass in multiple scope names to match on.
 
 ```ruby
-scope = ObjectInspector::Scope.new(%i[verbose complex])
-scope.self?    # => false
-scope.verbose? # => true
-scope.complex? # => true
+def inspect(scope: %i[verbose complex])
+  scope.inspect  # => <ObjectInspector::Scope :: ["complex", "verbose"]>
+  scope.self?    # => false
+  scope.verbose? # => true
+  scope.complex? # => true
+end
 ```
 
 #### The "Wild Card" Scope
@@ -295,11 +182,13 @@ scope.complex? # => true
 Finally, `:all` is a "wild card" scope name, and will match on all scope names.
 
 ```ruby
-scope = ObjectInspector::Scope.new(:all)
-scope.self?    # => true
-scope.verbose? # => true
-scope.complex? # => true
-scope.all?     # => true
+def inspect(scope: :all)
+  scope.inspect  # => <ObjectInspector::Scope :: ["all"]>
+  scope.self?    # => true
+  scope.verbose? # => true
+  scope.complex? # => true
+  scope.all?     # => true
+end
 ```
 
 _**NOTE**_: Calling `#inspect!` on an object that mixes in `ObjectInspector::InspectBehaviors` is equivalent to passing in the "wild card" scope.
@@ -365,7 +254,8 @@ class MyObject
   private
 
   def inspect_identification
-    identify(:a2)
+    # Or use `identify(:a2)` from the Object Identifier gem (see Supporting Gems).
+    "#{self.class.name}[#{a2}]"
   end
 
   def inspect_flags(scope:)
@@ -463,10 +353,10 @@ class MyWrappedObject
 end
 
 MyWrapperObject.new # =>
-<MyWrapperObject(WRAPPER_FLAG1) !!*!!>  ⇨  <MyWrappedObject(FLAG1 / FLAG2) !!*!! INFO>
+<MyWrapperObject(WRAPPER_FLAG1) !!*!!> ⇨ <MyWrappedObject(FLAG1 / FLAG2) !!*!! INFO>
 
-MyWrapperObject.new! # =>
-<MyWrapperObject(WRAPPER_FLAG1) !!CI1!!>  ⇨  <MyWrappedObject(FLAG1 / FLAG2) !!CI1!! INFO>
+MyWrapperObject.new.inspect! # =>
+<MyWrapperObject(WRAPPER_FLAG1) !!CI1!!> ⇨ <MyWrappedObject(FLAG1 / FLAG2) !!CI1!! INFO>
 ```
 
 This feature is recursive.
@@ -523,7 +413,7 @@ class MyWrappedObject
 end
 
 MyDelegatingWrapperObject.new(MyWrappedObject.new) # =>
-<MyDelegatingWrapperObject>  ⇨  <MyWrappedObject(FLAG1) !!ISSUE1!! INFO :: NAME>
+<MyDelegatingWrapperObject> ⇨ <MyWrappedObject(FLAG1) !!ISSUE1!! INFO :: NAME>
 ```
 
 ## On-the-fly Inspect Methods
@@ -568,6 +458,38 @@ MyObject.new.inspect(identification: nil, info: nil, flags: nil, issues: nil, na
 # => "<MyObject>"
 ```
 
+## Temporarily Disabling ObjectInspector
+
+To disable / re-enable Object Inspector output for the current session:
+
+```ruby
+MyObject.new # =>
+<My Object(FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>
+
+ObjectInspector.configuration.disable # =>
+ -> ObjectInspector disabled
+MyObject.new # =>
+#<MyObject:0x000000012332c458>
+
+ObjectInspector.configuration.enable # =>
+ -> ObjectInspector enabled
+MyObject.new # =>
+<My Object(FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>
+```
+
+Or, simply toggle the current state:
+
+```ruby
+ObjectInspector.configuration.toggle; # =>
+ -> ObjectInspector disabled
+
+ObjectInspector.configuration.toggle; # =>
+ -> ObjectInspector enabled
+```
+
+_**NOTE**_: `#inspect!` ignores the enabled/disabled setting and still invokes Object
+Inspector -- using the wild-card (`:all`) scope.
+
 ## Custom Formatters
 
 A custom inspect formatter can be defined by implementing the interface defined by [ObjectInspector::BaseFormatter](https://github.com/pdobb/object_inspector/blob/master/lib/object_inspector/formatters/base_formatter.rb). Then, either override the ObjectInspector::Configuration#formatter_class value (see [Configuration](#configuration)) or just pass your custom class name into ObjectInspector::Inspector.new.
@@ -601,11 +523,29 @@ See examples:
 - [ObjectInspector::TemplatingFormatter]
 - [ObjectInspector::CombiningFormatter]
 
+## Handling Errors
+
+When `#inspect` raises any `StandardError`, Object Inspector falls back to the original `#inspect` method and records the error in `ObjectInspector.last_error`:
+
+```ruby
+user = User.select(:id).first
+user.inspect
+# => #<User id: 1>
+
+ObjectInspector.last_error
+# => #<ActiveModel::MissingAttributeError: missing attribute: ...>
+puts ObjectInspector.last_error.full_message
+# ...: undefined local variable or method 'asdf' for an instance of Game (NameError)
+# ...
+
+ObjectInspector.clear_error
+```
+
 ## Help
 
 ### How can I see the original inspect output on ActiveRecord objects?
 
-Simply [disable Object Inspector](#disabling-object-inspector) and you'll see ActiveRecord's Pretty Print formatting shine through again. For example:
+Simply [disable Object Inspector](#temporarily-disabling-objectinspector) and you'll see ActiveRecord's Pretty Print formatting shine through again. For example:
 
 ```ruby
 class User < ApplicationRecord
@@ -677,9 +617,9 @@ def get_object_inspector_current_scope
 end
 alias oi get_object_inspector_current_scope
 
-# :simple is the default inspection scope.
-def set_object_inspector_scope_simple = set_object_inspector_scope(:simple)
-alias ois set_object_inspector_scope_simple
+# :self is the gem's default inspection scope.
+def set_object_inspector_scope_self = set_object_inspector_scope(:self)
+alias ois set_object_inspector_scope_self
 
 def set_object_inspector_scope_complex = set_object_inspector_scope(:complex)
 alias oic set_object_inspector_scope_complex
@@ -704,11 +644,28 @@ end
 alias oiset set_object_inspector_scope
 ```
 
+## Default State
+
+> [!IMPORTANT]
+> ObjectInspector defaults to `enabled`. However, this implies an increased chance of causing additional queries/processing based on your usage.
+
+If your inspect methods reference other ActiveRecord models, you will be introducing Database queries into basic object inspection. While you can control this through careful use of `complex` scopes, you may wish to default ObjectInspector to be `disabled` by default e.g. in production:
+
+```ruby
+# config/initializers/object_inspector.rb
+ObjectInspector.configure do |config|
+  config.enabled = !Rails.env.production?
+
+  # OR:
+  config.enabled = Rails.configuration.x.object_inspector.enabled
+end
+```
+
 ## Performance
 
 ### Benchmarking Object Inspector
 
-ObjectInspetor is ~2.75x slower than Ruby's default inspect, in Ruby v3.4.
+ObjectInspector is ~2.75x slower than Ruby's default inspect, in Ruby v3.4.
 
 Performance of Object Inspector can be tested by playing the [Object Inspector Benchmarking Script](https://github.com/pdobb/object_inspector/blob/master/script/benchmarking/object_inspector.rb) in the IRB console for this gem.
 
@@ -795,7 +752,7 @@ To release a new version of this gem to RubyGems:
 
 1. Update the version number in `version.rb`
 2. Update `CHANGELOG.md`
-3. Run `bundle` to update Gemfile.lock with the latest version info
+3. Run `bundle install` to update Gemfile.lock with the latest version info
 4. Commit the changes. e.g. `Bump to vX.Y.Z`
 5. Run `rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
@@ -817,6 +774,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/pdobb/
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
+[ObjectInspector::Configuration]: https://github.com/pdobb/object_inspector/blob/master/lib/object_inspector.rb
 [ObjectInspector::TemplatingFormatter]: https://github.com/pdobb/object_inspector/blob/master/lib/object_inspector/formatters/templating_formatter.rb
 [ObjectInspector::CombiningFormatter]: https://github.com/pdobb/object_inspector/blob/master/lib/object_inspector/formatters/combining_formatter.rb
 [Object Inspector Benchmarking Scripts]: https://github.com/pdobb/object_inspector/blob/master/script/benchmarking/object_inspector.rb

data/lib/object_inspector/formatters/base_formatter.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # An abstract base class that interfaces with {ObjectInspector::Inspector}
-# objects to combine the supplied {#identification}, {#flags}, {#info}, and
-# {#name} strings into a friendly "inspect" String.
+# objects to combine the supplied {#identification}, {#flags}, {#issues},
+# {#info}, and {#name} Strings into a friendly "inspect" String.
 class ObjectInspector::BaseFormatter
   attr_reader :inspector
 
@@ -21,7 +21,7 @@ class ObjectInspector::BaseFormatter
   # Delegates to {Inspector#wrapped_object_inspection_result}.
   #
   # @return [String] If given.
-  # @return [NilClass] If not given.
+  # @return [nil] If not given.
   def wrapped_object_inspection_result
     @wrapped_object_inspection_result ||=
       inspector.wrapped_object_inspection_result
@@ -37,7 +37,7 @@ class ObjectInspector::BaseFormatter
   # Delegates to {Inspector#flags}.
   #
   # @return [String] If given.
-  # @return [NilClass] If not given.
+  # @return [nil] If not given.
   def flags
     @flags ||= inspector.flags
   end
@@ -45,7 +45,7 @@ class ObjectInspector::BaseFormatter
   # Delegates to {Inspector#issues}.
   #
   # @return [String] If given.
-  # @return [NilClass] If not given.
+  # @return [nil] If not given.
   def issues
     @issues ||= inspector.issues
   end
@@ -53,7 +53,7 @@ class ObjectInspector::BaseFormatter
   # Delegates to {Inspector#info}.
   #
   # @return [String] If given.
-  # @return [NilClass] If not given.
+  # @return [nil] If not given.
   def info
     @info ||= inspector.info
   end
@@ -61,7 +61,7 @@ class ObjectInspector::BaseFormatter
   # Delegates to {Inspector#name}.
   #
   # @return [String] If given.
-  # @return [NilClass] If not given.
+  # @return [nil] If not given.
   def name
     @name ||= inspector.name
   end

data/lib/object_inspector/formatters/combining_formatter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# Specializes on {ObjectInspector::BaseFormatter} to return the standard/default
-# inspect output format by combining Strings.
+# Specializes on {ObjectInspector::BaseFormatter} to build inspect output by
+# combining Strings (as opposed to {ObjectInspector::TemplatingFormatter}).
 #
 # @attr (see BaseFormatter)
 class ObjectInspector::CombiningFormatter < ObjectInspector::BaseFormatter
@@ -19,8 +19,8 @@ class ObjectInspector::CombiningFormatter < ObjectInspector::BaseFormatter
   private
 
   def build_wrapped_object_string
-    "#{build_string} "\
-      "#{ObjectInspector.configuration.presented_object_separator} "\
+    "#{build_string}"\
+      "#{ObjectInspector.configuration.presented_object_separator}"\
       "#{wrapped_object_inspection_result}"
   end
 

data/lib/object_inspector/formatters/templating_formatter.rb

@@ -4,8 +4,8 @@
 # :reek:TooManyMethods
 # rubocop:disable Metrics/ClassLength
 
-# Specializes on {ObjectInspector::BaseFormatter} to return the standard/default
-# inspect output format using String templates.
+# Specializes on {ObjectInspector::BaseFormatter} to build the default inspect
+# output format using String templates.
 #
 # @attr (see BaseFormatter)
 class ObjectInspector::TemplatingFormatter < ObjectInspector::BaseFormatter
@@ -46,8 +46,8 @@ class ObjectInspector::TemplatingFormatter < ObjectInspector::BaseFormatter
   private
 
   def build_wrapped_object_string
-    "#{build_string} "\
-      "#{ObjectInspector.configuration.presented_object_separator} "\
+    "#{build_string}"\
+      "#{ObjectInspector.configuration.presented_object_separator}"\
       "#{wrapped_object_inspection_result}"
   end
 

data/lib/object_inspector/inspect_behaviors.rb

@@ -4,24 +4,47 @@
 # the default `#inspect` method for that object to instead call
 # {ObjectInspector::Inspector.inspect}.
 module ObjectInspector::InspectBehaviors
-  # Calls {ObjectInspector::Inspector.inspect} on the passed in `object`,
-  # passing through any keyword arguments.
+  # :reek:TooManyStatements
+
+  # Calls {ObjectInspector::Inspector.inspect} on `self`, passing through any
+  # keyword arguments.
+  #
+  # If building the gem inspect String raises a {StandardError}, records the
+  # error via {ObjectInspector.record_error} and falls back to the ancestor
+  # `#inspect` via `super` (Object / ActiveRecord / etc.).
   #
   # @return [String]
   def inspect(**)
     return super() if ObjectInspector.configuration.disabled?
 
-    ObjectInspector::Inspector.inspect(self, **)
+    ObjectInspector::Inspector.inspect(self, **).tap {
+      ObjectInspector.clear_error
+    }
+  rescue => ex
+    ObjectInspector.record_error(ex, object: self)
+    super()
   end
 
-  # Like {#inspect} but forces scope to `:all`. This (the bang (!) version) is
-  # considered the "more dangerous" version of {#inspect} in the sense that the
-  # `:all` scope may result in additional queries or extra processing--depending
-  # on how the inspect hooks are setup.
+  # Like {#inspect} but:
+  # - Ignores the enabled/disabled state of ObjectInspector
+  # - Forces scope to `:all`
+  #
+  # This (the bang (!) version) is considered the "more dangerous" version of
+  # {#inspect} since the `:all` scope may result in additional queries or extra
+  # processing--depending on how the inspect hooks are setup.
+  #
+  # On {StandardError}, records the error and falls back to {#inspect} (which
+  # then falls back to the original ancestor `#inspect` if needed).
   #
   # @return [String]
   def inspect!(**)
-    ObjectInspector::Inspector.inspect(self, **, scope: :all)
+    ObjectInspector::Inspector.inspect(self, **, scope: :all).tap {
+      ObjectInspector.clear_error
+    }
+  rescue => ex
+    ObjectInspector.record_error(ex, object: self)
+
+    inspect
   end
 
   private

data/lib/object_inspector/inspector.rb

@@ -24,7 +24,7 @@ class ObjectInspector::Inspector
   # @return [String]
   def self.inspect(...) = new(...).to_s
 
-  # :reek:DuplicateMethodCall (ObjectInspecto.configuration)
+  # :reek:DuplicateMethodCall
 
   # @param object [Object] the object being inspected
   # @param scope [Symbol] Object inspection type. For example:
@@ -32,7 +32,7 @@ class ObjectInspector::Inspector
   #   <custom>        -- Anything else that makes sense for {#object} to key
   #                      on
   # @param formatter [ObjectInspector::BaseFormatter]
-  #   (ObjectInspector.configuration.formatter) The formatter object type
+  #   (ObjectInspector.configuration.formatter_class) The formatter object type
   #   to use for formatting the inspect String.
   # @param kwargs [Hash] Options to be sent to {#object} via
   #   {ObjectInspector::InterrogateObject} when calling the `inspect_*`
@@ -60,7 +60,7 @@ class ObjectInspector::Inspector
   # object.
   #
   # @return [String] If {#object_is_a_wrapper?}.
-  # @return [NilClass] If not {#object_is_a_wrapper?}.
+  # @return [nil] If not {#object_is_a_wrapper?}.
   def wrapped_object_inspection_result
     return unless object_is_a_wrapper?
 
@@ -83,7 +83,7 @@ class ObjectInspector::Inspector
   # Boolean flags/states applicable to {#object}.
   #
   # @return [String] If given.
-  # @return [NilClass] If not given.
+  # @return [nil] If not given.
   def flags
     value(key: :flags)
   end
@@ -91,7 +91,7 @@ class ObjectInspector::Inspector
   # Issues/Warnings applicable to {#object}.
   #
   # @return [String] If given.
-  # @return [NilClass] If not given.
+  # @return [nil] If not given.
   def issues
     value(key: :issues)
   end
@@ -99,7 +99,7 @@ class ObjectInspector::Inspector
   # Informational details applicable to {#object}.
   #
   # @return [String] If given.
-  # @return [NilClass] If not given.
+  # @return [nil] If not given.
   def info
     value(key: :info)
   end
@@ -107,7 +107,7 @@ class ObjectInspector::Inspector
   # A human-friendly identifier for {#object}.
   #
   # @return [String] If given.
-  # @return [NilClass] If not given.
+  # @return [nil] If not given.
   def name
     key = :name
 
@@ -134,7 +134,7 @@ class ObjectInspector::Inspector
 
   # @return [String] If `key` is found in {#kwargs} or if {#object} responds to
   #   `#{object_inspection_method_name}` (e.g. `inspect_flags`).
-  # @return [NilClass] If not found in {#kwargs} or {#object}.
+  # @return [nil] If not found in {#kwargs} or {#object}.
   def value(key:)
     return_value =
       if kwargs.key?(key)
@@ -151,8 +151,8 @@ class ObjectInspector::Inspector
   #
   # @return [#to_s] If {#object} responds to `value` and if the call result
   #   isn't nil.
-  # @return [#nil] If {#object} doesn't respond to `value` or if the call
-  #   result is nil.
+  # @return [nil] If {#object} doesn't respond to `value` or if the call result
+  #   is nil.
   def evaluate_passed_in_value(value)
     if value.is_a?(Symbol)
       interrogate_object(method_name: value) || value
@@ -165,7 +165,7 @@ class ObjectInspector::Inspector
   #
   # @return [String] If {#object} responds to
   #   `#{object_inspection_method_name}` (e.g. `inspect_flags`).
-  # @return [NilClass] If not found on {#object}.
+  # @return [nil] If not found on {#object}.
   def interrogate_object_inspect_method(
     name,
     prefix: ObjectInspector.configuration.inspect_method_prefix

data/lib/object_inspector/interrogate_object.rb

@@ -6,6 +6,7 @@
 # If {#object}#{#method_name} accepts the supplied `kwargs` then they are passed
 # in as well. If not, then any supplied `kwargs` will be ignored.
 class ObjectInspector::InterrogateObject
+  # @return (see #call)
   def self.call(...) = new(...).call
 
   attr_reader :object,
@@ -18,9 +19,10 @@ class ObjectInspector::InterrogateObject
     @kwargs = kwargs
   end
 
-  # @return [String, ...] Whatever type Object#{#method_name} returns.
+  # @return [Object, nil] The result of calling {#method_name} on {#object},
+  #   or `nil` if {#object} does not respond to {#method_name}.
   #
-  # @raise [ArgumentError] If Object#{#method_name} has an unexpected method
+  # @raise [ArgumentError] If {#object}#{#method_name} has an unexpected method
   #   signature.
   def call
     return unless object_responds_to_method_name?

data/lib/object_inspector/scope.rb

@@ -22,6 +22,9 @@
 #   ObjectInspector::Scope.new(%w[verbose complex])
 #   # => <ObjectInspector::Scope :: ["complex", "verbose"]>
 #
+#   ObjectInspector::Scope.new(:verbose, :self)
+#   # => <ObjectInspector::Scope :: ["self", "verbose"]>
+#
 # @see ActiveSupport::StringInquirer
 #   http://api.rubyonrails.org/classes/ActiveSupport/StringInquirer.html
 #
@@ -39,7 +42,7 @@ class ObjectInspector::Scope
   # Join the passed in name parts with the passed in separator.
   #
   # @param parts [Array<#to_s>]
-  # @param separator [#to_s] (ObjectInspector.configuration.flags_separator)
+  # @param separator [#to_s] (ObjectInspector.configuration.name_separator)
   def join_name(
     parts,
     separator: ObjectInspector.configuration.name_separator
@@ -100,6 +103,7 @@ class ObjectInspector::Scope
     names
   end
 
+  # @return [String] A pretty representation of the scope and its {#names}.
   def inspect
     "<#{self.class.name} :: #{names.inspect}>"
   end

data/lib/object_inspector/version.rb

@@ -4,6 +4,6 @@
 
 module ObjectInspector
   # The current ObjectInspector gem version.
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
   public_constant :VERSION
 end

data/lib/object_inspector.rb

@@ -3,6 +3,9 @@
 # Defines the base namespace for all modules/classes used by the
 # object_inspector gem.
 module ObjectInspector
+  LAST_ERROR_THREAD_KEY = :object_inspector_last_error
+  private_constant :LAST_ERROR_THREAD_KEY
+
   # Accessor for the {ObjectInspector::Configuration} object.
   def self.configuration
     @configuration ||= Configuration.new
@@ -11,6 +14,8 @@ module ObjectInspector
   # @yieldparam configuration [ObjectInspector::Configuration]
   def self.configure
     yield(configuration)
+
+    configuration
   end
 
   # Reset the current configuration settings memoized by
@@ -19,7 +24,41 @@ module ObjectInspector
     @configuration = Configuration.new
   end
 
-  # :reek:TooManyInstanceVariables
+  # Remember the given exception--which will have caused inspect to fall back to
+  # the original `#inspect`. Stored per-thread/fiber so concurrent use does not
+  # clobber it.
+  #
+  # Calls {Configuration#error_handler} with `exception, object:` after
+  # recording.
+  #
+  # @param exception [Exception]
+  # @param object [Object, nil] The object being inspected, when known.
+  #
+  # @return [Exception]
+  def self.record_error(exception, object: nil)
+    Thread.current[LAST_ERROR_THREAD_KEY] = exception
+
+    configuration.error_handler.(exception, object:)
+
+    exception
+  end
+
+  # The most recent exception passed to {record_error} on this thread/fiber.
+  # Cleared by {clear_error} (including after a successful gem inspect).
+  #
+  # @return [Exception, nil]
+  def self.last_error
+    Thread.current[LAST_ERROR_THREAD_KEY]
+  end
+
+  # Clear {#last_error} for the current thread/fiber.
+  #
+  # @return [nil]
+  def self.clear_error
+    Thread.current[LAST_ERROR_THREAD_KEY] = nil
+  end
+
+  # :reek:TooManyInstanceVariables, :reek:TooManyMethods
 
   # ObjectInspector::Configuration stores the default configuration options for
   # the ObjectInspector gem. Modification of attributes is possible at any time,
@@ -34,34 +73,63 @@ module ObjectInspector
                 :name_separator,
                 :flags_separator,
                 :issues_separator,
-                :info_separator
-
-    def initialize # rubocop:disable Metrics/MethodLength
-      @enabled = true
-      @formatter_class = TemplatingFormatter
-      @inspect_method_prefix = "inspect"
-      @default_scope = Scope.new(:self)
-      @wild_card_scope = "all"
-      @out_of_scope_placeholder = "*"
-      @presented_object_separator = " #{[0x21E8].pack("U")} "
-      @name_separator = " - "
-      @flags_separator = " / "
-      @issues_separator = " | "
-      @info_separator = " | "
+                :info_separator,
+                :error_handler
+
+    # :reek:LongParameterList, :reek:BooleanParameter
+    def initialize( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+      enabled: true,
+      formatter_class: TemplatingFormatter,
+      inspect_method_prefix: "inspect",
+      default_scope: Scope.new(:self),
+      wild_card_scope: "all",
+      out_of_scope_placeholder: "*",
+      presented_object_separator: " #{[0x21E8].pack("U")} ", # This is: " ⇨ "
+      name_separator: " - ",
+      flags_separator: " / ",
+      issues_separator: " | ",
+      info_separator: " | ",
+      error_handler: ->(exception, object:) {}
+    )
+      @enabled = enabled
+      @formatter_class = formatter_class
+      @inspect_method_prefix = inspect_method_prefix
+      @default_scope = default_scope
+      @wild_card_scope = wild_card_scope
+      @out_of_scope_placeholder = out_of_scope_placeholder
+      @presented_object_separator = presented_object_separator
+      @name_separator = name_separator
+      @flags_separator = flags_separator
+      @issues_separator = issues_separator
+      @info_separator = info_separator
+      self.error_handler = error_handler
     end
 
+    # @param value [Object] Coerced to a Boolean with `!!value`.
+    def enabled=(value)
+      @enabled = !!value
+    end
+
+    # Toggles between {#enable} and {#disable} based on {#enabled?}.
     def toggle = enabled? ? disable : enable
+
+    # @return [Boolean]
     def enabled? = @enabled
 
+    # Enable Object Inspector for the current process and print a status
+    # message to `$stdout`.
     def enable
-      @enabled = true
+      self.enabled = true
       puts(" -> ObjectInspector enabled")
     end
 
+    # @return [Boolean]
     def disabled? = !enabled?
 
+    # Disable Object Inspector for the current process and print a status
+    # message to `$stdout`.
     def disable
-      @enabled = false
+      self.enabled = false
       puts(" -> ObjectInspector disabled")
     end
 
@@ -108,6 +176,21 @@ module ObjectInspector
     def info_separator=(value)
       @info_separator = value.to_s.freeze
     end
+
+    # :reek:ManualDispatch
+
+    # A callable, invoked by {ObjectInspector.record_error}.
+    #
+    # Expected signature: `->(exception, object:) { ... }`.
+    #
+    # @param value [#call]
+    def error_handler=(value)
+      unless value.respond_to?(:call)
+        raise(TypeError, "error_handler must be callable")
+      end
+
+      @error_handler = value
+    end
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: object_inspector
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Paul DobbinSchmaltz
@@ -67,7 +67,7 @@ dependencies:
         version: '0'
 description: Object Inspector takes Object#inspect to the next level. Specify any
   combination of identification attributes, flags, issues, info, and/or a name along
-  with an optional, self-definable scope option to represents objects. Great for the
+  with an optional, self-definable scope option to represent objects. Great for the
   console, logging, etc.
 email:
 - p.dobbinschmaltz@icloud.com