object_inspector 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50466d066a40b772c3d98ff85d1be9934a3011e9699261de12da2b620bec1785
-  data.tar.gz: 6deb6b097b7ee1c6d553754242ecbcc0683b3768c5906c139c279a6e07e21da4
+  metadata.gz: fd42799a69895e8a918436eaa6688090722f4dde5d406f34b36eae201459f82a
+  data.tar.gz: 1ea233bec14fddd0b57ffb797da6009471f8f9f989fee45f204af8813b70f59e
 SHA512:
-  metadata.gz: fccec790066ab69fad5c25d737c04b3c5698860d6acca5bc828e0be0a1186260060ad328c183dffc58012c9461405259de1ffb27b763e370df1cc48aa08459d4
-  data.tar.gz: a20c43a5d28088cd5ca7c0da08e1c456f8d4e0433faf7a552401855b66267c8b596e1beb7885ec9a80e829ac9b2523287ef2e3139122ca4b961d3cc54a0072ab
+  metadata.gz: f30121bcdddfd33c7990197e4513eb44a84a487afc4f346a5823067760e2754aaf7ae0871ae58157ef45686de4a885e2db798e97e7a35671c5b0143fedafb11c
+  data.tar.gz: 4ed8d2ac33b52b4af28bc621a2e92fd429039c6951a2d8d10a38e866a9d101e2f18d24a60125fb189b367232293068c63a3ca0ec0bdaa1bb6df37119f26db5d0

data/README.md

@@ -5,7 +5,7 @@
 
 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 represent objects. Great for the console, logging, etc.
 
-Why? Because object inspection code should be uniform and easy to build, and its output should be easy to read! Consistency improves readability.
+Why? Because object inspection output should be uniform and easy to build, and its output should be easy to read! Consistency improves readability.
 
 If you'd like to just jump into an example: [Full Example](#full-example).
 
@@ -60,6 +60,7 @@ Global/default values for Object Inspector can be configured via the [ObjectInsp
 
 # Default values are shown. Customize to your liking.
 ObjectInspector.configure do |config|
+  config.enabled = true
   config.formatter_class = ObjectInspector::TemplatingFormatter
   config.inspect_method_prefix = "inspect"
   config.default_scope = ObjectInspector::Scope.new(:self)
@@ -84,7 +85,10 @@ class MyObject
   end
 end
 
-MyObject.new.inspect  # => "<MyObject>"
+MyObject.new.inspect # => "<MyObject>"
+
+MyObject.new # =>
+<MyObject>
 ```
 
 See: [Helper Usage](#helper-usage) for simpler usage.
@@ -106,8 +110,8 @@ class MyObject
   end
 end
 
-MyObject.new.inspect
-# => "<My Object(FLAG1 / FLAG2) !!ISSUE1!! INFO :: NAME>"
+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.
@@ -127,27 +131,28 @@ class MyObject
   def inspect_name = "NAME"  # Or: def display_name = "NAME"
 end
 
-MyObject.new.inspect
-# => "<My Object(FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>"
+MyObject.new # =>
+<My Object(FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>
 ```
 
 ## Helper Usage
 
-To save some typing, include ObjectInspector::InspectHelper into an object and `ObjectInspector::Inspector.inspect` will be called on `self` automatically.
+To save some typing, include ObjectInspector::InspectBehaviors into an object and `ObjectInspector::Inspector.inspect` will be called on `self` automatically.
 
 ```ruby
 class MyObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 end
 
-MyObject.new.inspect  # => "<MyObject>"
+MyObject.new # =>
+<MyObject>
 ```
 
 To access the ObjectInspector::Inspector's options via the helper, call into `super`.
 
 ```ruby
 class MyObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   def inspect
     super(identification: "My Object",
@@ -158,15 +163,15 @@ class MyObject
   end
 end
 
-MyObject.new.inspect
-# => "<My Object(FLAG1) !!ISSUE1 | ISSUE2!! INFO :: NAME>"
+MyObject.new # =>
+<My Object(FLAG1) !!ISSUE1 | ISSUE2!! INFO :: NAME>
 ```
 
 Or, define `inspect_identification`, `inspect_flags`, `inspect_info`, and/or `inspect_name` (or `display_name`) in Object.
 
 ```ruby
 class MyObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   private
 
@@ -177,8 +182,72 @@ class MyObject
   def inspect_name = "NAME"  # Or: def display_name = "NAME"
 end
 
-MyObject.new.inspect
-# => "<My Object(FLAG1) !!ISSUE1 | ISSUE2!! INFO :: NAME>"
+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
+
+Instead of including `ObjectInspector::InspectBehaviors` directly, it may be useful to define your own mix-in.
+
+```ruby
+module ObjectInspectionBehaviors
+  include ObjectInspector::InspectBehaviors
+
+  # For defining #inspect chains.
+  def introspect
+    # { self => ... }
+    self
+  end
+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
@@ -188,7 +257,7 @@ The default value is `ObjectInspector::Scope.new(:self)`.
 
 ### Scope Names
 
-ObjectInspector::Scope acts like [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). This is a prettier way to test for a given type of "scope" within objects.
 
 The ObjectInspector::Scope objects in these examples are the same as specifying `<scope_name>` like this:
 
@@ -216,9 +285,9 @@ 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
+scope.self?    # => false
+scope.verbose? # => true
+scope.complex? # => true
 ```
 
 #### The "Wild Card" Scope
@@ -227,20 +296,22 @@ 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
+scope.self?    # => true
+scope.verbose? # => true
+scope.complex? # => true
+scope.all?     # => true
 ```
 
+_**NOTE**_: Calling `#inspect!` on an object that mixes in `ObjectInspector::InspectBehaviors` is equivalent to passing in the "wild card" scope.
+
 ### Scope blocks
 
 Passing a block to a scope predicate falls back to the out-of-scope placeholder (`*` by default) if the scope does not match.
 
 ```ruby
 scope = ObjectInspector::Scope.new(:verbose)
-scope.verbose? { "MATCH" }  # => "MATCH"
-scope.complex? { "MATCH" }  # => "*"
+scope.verbose? { "MATCH" } # => "MATCH"
+scope.complex? { "MATCH" } # => "*"
 ```
 
 ### Scope Joiners
@@ -248,10 +319,10 @@ scope.complex? { "MATCH" }  # => "*"
 ObjectInspector::Scope also offers helper methods for uniformly joining inspect elements:
 
 ```ruby
-join_name   # Joins name parts with ` - ` by default
-join_flags  # Joins flags with ` / ` by default
-join_issues # Joins issues with ` | ` by default
-join_info   # Joins info items with ` | ` by default
+scope.join_name   # Joins name parts with ` - ` by default
+scope.join_flags  # Joins flags with ` / ` by default
+scope.join_issues # Joins issues with ` | ` by default
+scope.join_info   # Joins info items with ` | ` by default
 ```
 
 For example:
@@ -268,7 +339,7 @@ scope.join_info([1, 2, 3, nil])   # => "1 | 2 | 3"
 
 ```ruby
 class MyObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   attr_reader :name,
               :a2
@@ -347,17 +418,20 @@ my_object.inspect(scope: %i[self complex verbose])
 my_object.inspect(scope: :all)
 # => "<MyObject[2](DEFAULT_FLAG / AO1_FLAG1 / AO2_FLAG1) !!I1 | VI2!! Default Info | Complex Info | Verbose Info :: Name>"
 
+my_object.inspect! # 👀 Same as passing in `scope: :all`
+# => "<MyObject[2](DEFAULT_FLAG / AO1_FLAG1 / AO2_FLAG1) !!I1 | VI2!! Default Info | Complex Info | Verbose Info :: Name>"
+
 ObjectInspector.configuration.default_scope = :complex
-my_object.inspect
-# => "<MyObject[2](DEFAULT_FLAG / *) !!I1 | *!! Default Info | Complex Info | * :: Name>"
+my_object # =>
+<MyObject[2](DEFAULT_FLAG / *) !!I1 | *!! Default Info | Complex Info | * :: Name>
 
 ObjectInspector.configuration.default_scope = %i[self complex verbose]
-my_object.inspect
-# => "<MyObject[2](DEFAULT_FLAG / AO1_FLAG1 / AO2_FLAG1) !!I1 | VI2!! Default Info | Complex Info | Verbose Info :: Name>"
+my_object # =>
+<MyObject[2](DEFAULT_FLAG / AO1_FLAG1 / AO2_FLAG1) !!I1 | VI2!! Default Info | Complex Info | Verbose Info :: Name>
 
 ObjectInspector.configuration.default_scope = :all
-my_object.inspect
-# => "<MyObject[2](DEFAULT_FLAG / AO1_FLAG1 / AO2_FLAG1) !!I1 | VI2!! Default Info | Complex Info | Verbose Info :: Name>"
+my_object # =>
+<MyObject[2](DEFAULT_FLAG / AO1_FLAG1 / AO2_FLAG1) !!I1 | VI2!! Default Info | Complex Info | Verbose Info :: Name>
 ```
 
 ## Wrapped Objects
@@ -366,7 +440,7 @@ If the Object being inspected wraps another object--i.e. defines #to_model and #
 
 ```ruby
 class MyWrapperObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   def to_model
     @to_model ||= MyWrappedObject.new
@@ -375,19 +449,24 @@ class MyWrapperObject
   private
 
   def inspect_flags = "WRAPPER_FLAG1"
+  def inspect_issues(scope:) = scope.complex? { "CI1" }
 end
 
 class MyWrappedObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   private
 
   def inspect_flags = "FLAG1 / FLAG2"
   def inspect_info = "INFO"
+  def inspect_issues(scope:) = scope.complex? { "CI1" }
 end
 
-MyWrapperObject.new.inspect
-# => "<MyWrapperObject(WRAPPER_FLAG1)> ⇨ <MyWrappedObject(FLAG1 / FLAG2) INFO>"
+MyWrapperObject.new # =>
+<MyWrapperObject(WRAPPER_FLAG1) !!*!!>  ⇨  <MyWrappedObject(FLAG1 / FLAG2) !!*!! INFO>
+
+MyWrapperObject.new! # =>
+<MyWrapperObject(WRAPPER_FLAG1) !!CI1!!>  ⇨  <MyWrappedObject(FLAG1 / FLAG2) !!CI1!! INFO>
 ```
 
 This feature is recursive.
@@ -398,7 +477,7 @@ If the Object being inspected is wrapped by an object that delegates all unknown
 
 ```ruby
 class MyDelegatingWrapperObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   def initialize(my_object)
     @my_object = my_object
@@ -429,7 +508,7 @@ class MyDelegatingWrapperObject
 end
 
 class MyWrappedObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   def display_name
     "WRAPPED_OBJECT_NAME"
@@ -443,8 +522,8 @@ class MyWrappedObject
   def inspect_name = "NAME"
 end
 
-MyDelegatingWrapperObject.new(MyWrappedObject.new).inspect
-# => "<MyDelegatingWrapperObject>  ⇨  <MyWrappedObject(FLAG1) !!ISSUE1!! INFO :: NAME>"
+MyDelegatingWrapperObject.new(MyWrappedObject.new) # =>
+<MyDelegatingWrapperObject>  ⇨  <MyWrappedObject(FLAG1) !!ISSUE1!! INFO :: NAME>
 ```
 
 ## On-the-fly Inspect Methods
@@ -453,7 +532,7 @@ When passed as an option (as opposed to being called via an Object-defined metho
 
 ```ruby
 class MyObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   def my_method1 = "Result1"
   def my_method2 = "Result2"
@@ -461,9 +540,9 @@ class MyObject
   def inspect_info = :my_method2
 end
 
-MyObject.new.inspect(info: "my_method1")  # => "<MyObject my_method1>"
-MyObject.new.inspect(info: :my_method2)   # => "<MyObject Result2>"
-MyObject.new.inspect                      # => "<MyObject my_method2>"
+MyObject.new.inspect(info: "my_method1") # => "<MyObject my_method1>"
+MyObject.new.inspect(info: :my_method2)  # => "<MyObject Result2>"
+MyObject.new.inspect                     # => "<MyObject my_method2>"
 ```
 
 ## Clearing Output for Specified Inspect Method
@@ -472,7 +551,7 @@ Pass `nil` to any inspect method type to not display it:
 
 ```ruby
 class MyObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   def inspect_identification = "My Object"
   def inspect_info = "INFO"
@@ -501,7 +580,7 @@ class MyCustomFormatter < ObjectInspector::BaseFormatter
 end
 
 class MyObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   def inspect
     super(
@@ -513,8 +592,8 @@ class MyObject
   end
 end
 
-MyObject.new.inspect
-# => "[IDENTIFICATION Flags: FLAG1 / FLAG2 -- Info: INFO -- Name: NAME]"
+MyObject.new # =>
+[IDENTIFICATION Flags: FLAG1 / FLAG2 -- Info: INFO -- Name: NAME]
 ```
 
 See examples:
@@ -522,13 +601,42 @@ See examples:
 - [ObjectInspector::TemplatingFormatter]
 - [ObjectInspector::CombiningFormatter]
 
+## 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:
+
+```ruby
+class User < ApplicationRecord
+  include ObjectInspectionBehaviors # 👀 Defined above.
+
+  # ...
+end
+
+User.new # =>
+<User[1] :: John Smith>
+
+ObjectInspector.configuration.disable; # =>
+ -> ObjectInspector disabled
+
+User.new # =>
+#<User:0x0000000125ce9890
+ id: "6c6d6f4b-05fd-4d81-af3e-1947a6a38aa0",
+ first_name: "John",
+ last_name: "Smith",
+ time_zone: nil,
+ created_at: "2025-02-10 12:27:23.793833000 -0600",
+ updated_at: "2025-02-11 13:15:00.301991000 -0600">
+```
+
 ## Supporting Gems
 
 Object Inspector works great with the [Object Identifier](https://github.com/pdobb/object_identifier) gem.
 
 ```ruby
 class MyObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   def my_method1
     1
@@ -550,8 +658,50 @@ class MyObject
   def inspect_name = "NAME"
 end
 
-MyObject.new.inspect
-# => "<MyObject[my_method1:1, my_method2:2](FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>"
+MyObject.new # =>
+<MyObject[my_method1:1, my_method2:2](FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>
+```
+
+## Adding Utilities Methods to `.irbrc` / `.pryrc`
+
+One may wish to add some convenience methods to their project-local `.irbrc`/`.pryrc` file, and/or their global `~/.irbrc`/`~/.pryrc` file. For example:
+
+```ruby
+# OBJECT INSPECTOR GEM
+
+def toggle_object_inspector = ObjectInspector.configuration.toggle
+alias oit toggle_object_inspector
+
+def get_object_inspector_current_scope
+  ObjectInspector.configuration.default_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
+
+def set_object_inspector_scope_complex = set_object_inspector_scope(:complex)
+alias oic set_object_inspector_scope_complex
+
+def set_object_inspector_scope_verbose = set_object_inspector_scope(:verbose)
+alias oiv set_object_inspector_scope_verbose
+
+# Set :all (wild-card) inspection scope.
+def set_object_inspector_scope_all = set_object_inspector_scope(:all)
+alias oia set_object_inspector_scope_all
+
+# Set a custom scope or set of scopes.
+#
+# @example
+#   set_object_inspector_scope(:my_custom_scope)
+#   set_object_inspector_scope(:complex, :verbose)
+#   set_object_inspector_scope(%i[complex verbose my_custom_scope])
+def set_object_inspector_scope(*names)
+  ObjectInspector.configuration.default_scope = *names
+  get_object_inspector_current_scope
+end
+alias oiset set_object_inspector_scope
 ```
 
 ## Performance
@@ -590,13 +740,13 @@ load "script/benchmarking/formatters.rb"
 #
 # Comparison:
 # ObjectInspector::TemplatingFormatter:    65856.3 i/s
-# ObjectInspector::CombiningFormatter:    60920.0 i/s - 1.08x  slower
+# ObjectInspector::CombiningFormatter:    60920.0 i/s - 1.13x  slower
 # == Done
 ```
 
 #### Benchmarking Custom Formatters
 
-Custom Formatters may be similarly gauged for comparison by putting them into a constant `CUSTOM_FORMATTER_CLASSES` before playing the script in the IRB console for this gem.
+Custom Formatters may be similarly gauged for comparison by putting them into a constant `CUSTOM_FORMATTER_CLASSES` before loading the script in the IRB console for this gem.
 
 ```ruby
 CUSTOM_FORMATTER_CLASSES = [MyCustomFormatter]

data/lib/object_inspector/conversions.rb

@@ -1,17 +1,25 @@
 # frozen_string_literal: true
 
-# ObjectInspector::Conversions defines conversion functions used by
-# ObjectInspector.
+# Defines general conversion functions used by ObjectInspector.
 module ObjectInspector::Conversions
   module_function
 
+  # :reek:UncommunicativeMethodName
+
   # Convert the passed in value to an {ObjectInspector::Scope} object.
   # Just returns the passed in value if it already is an
   # {ObjectInspector::Scope} object.
   #
-  # @return [ObjectInspector::Scope]
+  # @example
+  #   ObjectInspector::Conversions.Scope("test")
+  #   # => <ObjectInspector::Scope :: ["test"]>
   #
-  # :reek:UncommunicativeMethodName
+  #   ObjectInspector::Conversions.Scope(
+  #     ObjectInspector::Scope.new(:my_custom_scope),
+  #   )
+  #   # => <ObjectInspector::Scope :: ["my_custom_scope"]>
+  #
+  # @return [ObjectInspector::Scope]
   def Scope(value) # rubocop:disable Naming/MethodName
     case value
     when ObjectInspector::Scope

data/lib/object_inspector/formatters/base_formatter.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-# ObjectInspector::BaseFormatter is 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.
+# 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.
 class ObjectInspector::BaseFormatter
   attr_reader :inspector
 
@@ -21,49 +20,49 @@ class ObjectInspector::BaseFormatter
 
   # Delegates to {Inspector#wrapped_object_inspection_result}.
   #
-  # @return [String] if given
-  # @return [NilClass] if not given
+  # @return [String] If given.
+  # @return [NilClass] If not given.
   def wrapped_object_inspection_result
     @wrapped_object_inspection_result ||=
-      @inspector.wrapped_object_inspection_result
+      inspector.wrapped_object_inspection_result
   end
 
   # Delegates to {Inspector#identification}.
   #
-  # @return [String] if given
+  # @return [String] If given.
   def identification
-    @identification ||= @inspector.identification
+    @identification ||= inspector.identification
   end
 
   # Delegates to {Inspector#flags}.
   #
-  # @return [String] if given
-  # @return [NilClass] if not given
+  # @return [String] If given.
+  # @return [NilClass] If not given.
   def flags
-    @flags ||= @inspector.flags
+    @flags ||= inspector.flags
   end
 
   # Delegates to {Inspector#issues}.
   #
-  # @return [String] if given
-  # @return [NilClass] if not given
+  # @return [String] If given.
+  # @return [NilClass] If not given.
   def issues
-    @issues ||= @inspector.issues
+    @issues ||= inspector.issues
   end
 
   # Delegates to {Inspector#info}.
   #
-  # @return [String] if given
-  # @return [NilClass] if not given
+  # @return [String] If given.
+  # @return [NilClass] If not given.
   def info
-    @info ||= @inspector.info
+    @info ||= inspector.info
   end
 
   # Delegates to {Inspector#name}.
   #
-  # @return [String] if given
-  # @return [NilClass] if not given
+  # @return [String] If given.
+  # @return [NilClass] If not given.
   def name
-    @name ||= @inspector.name
+    @name ||= inspector.name
   end
 end

data/lib/object_inspector/formatters/combining_formatter.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-# ObjectInspector::CombiningFormatter implements
-# {ObjectInspector::BaseFormatter} to return the standard/default inspect
-# output format by combining Strings.
+# Specializes on {ObjectInspector::BaseFormatter} to return the standard/default
+# inspect output format by combining Strings.
 #
 # @attr (see BaseFormatter)
 class ObjectInspector::CombiningFormatter < ObjectInspector::BaseFormatter

data/lib/object_inspector/formatters/templating_formatter.rb

@@ -4,9 +4,8 @@
 # :reek:TooManyMethods
 # rubocop:disable Metrics/ClassLength
 
-# ObjectInspector::TemplatingFormatter specializes on
-# {ObjectInspector::BaseFormatter} to return the standard/default inspect
-# output format via String templates.
+# Specializes on {ObjectInspector::BaseFormatter} to return the standard/default
+# inspect output format using String templates.
 #
 # @attr (see BaseFormatter)
 class ObjectInspector::TemplatingFormatter < ObjectInspector::BaseFormatter
@@ -52,8 +51,7 @@ class ObjectInspector::TemplatingFormatter < ObjectInspector::BaseFormatter
       "#{wrapped_object_inspection_result}"
   end
 
-  # rubocop:disable Metrics/MethodLength
-  def build_string
+  def build_string # rubocop:disable Metrics/MethodLength
     if flags
       build_string_with_flags_and_maybe_issues_and_info_and_name
     elsif issues
@@ -66,7 +64,6 @@ class ObjectInspector::TemplatingFormatter < ObjectInspector::BaseFormatter
       build_base_string
     end
   end
-  # rubocop:enable Metrics/MethodLength
 
   def build_string_with_flags_and_maybe_issues_and_info_and_name
     if issues

data/lib/object_inspector/inspect_behaviors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# ObjectInspector::InspectBehaviors can be included into any object to override
+# 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.
+  #
+  # @return [String]
+  def inspect(**)
+    return super() if ObjectInspector.configuration.disabled?
+
+    ObjectInspector::Inspector.inspect(self, **)
+  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.
+  #
+  # @return [String]
+  def inspect!(**)
+    ObjectInspector::Inspector.inspect(self, **, scope: :all)
+  end
+
+  private
+
+  # :reek:UtilityFunction
+
+  # Allow ActiveRecord::Core#pretty_print to produce the standard Pretty-printed
+  # output (vs just straight #inspect String) when ObjectInspector is disabled.
+  def custom_inspect_method_defined?
+    ObjectInspector.configuration.enabled?
+  end
+end

data/lib/object_inspector/inspector.rb

@@ -1,10 +1,20 @@
 # frozen_string_literal: true
 
-# ObjectInspector::Inspector organizes inspection of the associated {#object}
-# via the passed in options and via an {ObjectInspector::BaseFormatter}
-# instance.
-#
 # :reek:TooManyMethods
+
+# Organizes inspection of the associated {#object} via the passed in options and
+# via an {ObjectInspector::BaseFormatter} instance.
+#
+# @example
+#   ObjectInspector::Inspector.inspect(
+#     self,
+#     identification: self.class.name,
+#     flags: "FLAG1",
+#     issues: "ISSUE1",
+#     info: "INFO",
+#     name: "NAME",
+#   )
+#   # => "<Object(FLAG1) !!ISSUE1!! INFO :: NAME>"
 class ObjectInspector::Inspector
   attr_reader :object
 
@@ -12,9 +22,9 @@ class ObjectInspector::Inspector
   # required to use ObjectInspector::Inspector.
   #
   # @return [String]
-  def self.inspect(...)
-    new(...).to_s
-  end
+  def self.inspect(...) = new(...).to_s
+
+  # :reek:DuplicateMethodCall (ObjectInspecto.configuration)
 
   # @param object [Object] the object being inspected
   # @param scope [Symbol] Object inspection type. For example:
@@ -22,18 +32,17 @@ 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
-  #   to use for formatting the inspect String
-  # @param kwargs [Hash] options to be sent to {#object} via the
-  #   {ObjectInspector::ObjectInterrogator} when calling the `inspect_*`
-  #   methods
-  #
-  # :reek:DuplicateMethodCall (ObjectInspecto.configuration)
+  #   (ObjectInspector.configuration.formatter) 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_*`
+  #   methods.
   def initialize(
-        object,
-        scope: ObjectInspector.configuration.default_scope,
-        formatter: ObjectInspector.configuration.formatter_class,
-        **kwargs)
+    object,
+    scope: ObjectInspector.configuration.default_scope,
+    formatter: ObjectInspector.configuration.formatter_class,
+    **kwargs
+  )
     @object = object
     @scope = ObjectInspector::Conversions.Scope(scope)
     @formatter_class = formatter
@@ -47,10 +56,11 @@ class ObjectInspector::Inspector
     formatter.call
   end
 
-  # Generate the inspect String for the wrapped object, if present.
+  # Generate the inspect String for the wrapped object, if `self` is a wrapper
+  # object.
   #
-  # @return [String] if {#object_is_a_wrapper?}
-  # @return [NilClass] if not {#object_is_a_wrapper?}
+  # @return [String] If {#object_is_a_wrapper?}.
+  # @return [NilClass] If not {#object_is_a_wrapper?}.
   def wrapped_object_inspection_result
     return unless object_is_a_wrapper?
 
@@ -58,7 +68,8 @@ class ObjectInspector::Inspector
       extract_wrapped_object,
       scope: @scope,
       formatter: @formatter_class,
-      kwargs: @kwargs)
+      kwargs: @kwargs,
+    )
   end
 
   # Core object identification details, such as the {#object} class name and
@@ -66,62 +77,68 @@ class ObjectInspector::Inspector
   #
   # @return [String]
   def identification
-    (value(key: :identification) || @object.class).to_s
+    (value(key: :identification) || object.class).to_s
   end
 
   # Boolean flags/states applicable to {#object}.
   #
-  # @return [String] if given
-  # @return [NilClass] if not given
+  # @return [String] If given.
+  # @return [NilClass] If not given.
   def flags
     value(key: :flags)
   end
 
   # Issues/Warnings applicable to {#object}.
   #
-  # @return [String] if given
-  # @return [NilClass] if not given
+  # @return [String] If given.
+  # @return [NilClass] If not given.
   def issues
     value(key: :issues)
   end
 
   # Informational details applicable to {#object}.
   #
-  # @return [String] if given
-  # @return [NilClass] if not given
+  # @return [String] If given.
+  # @return [NilClass] If not given.
   def info
     value(key: :info)
   end
 
   # A human-friendly identifier for {#object}.
   #
-  # @return [String] if given
-  # @return [NilClass] if not given
+  # @return [String] If given.
+  # @return [NilClass] If not given.
   def name
     key = :name
 
     if @kwargs.key?(key)
-      value(key: key)
+      value(key:)
     else
       interrogate_object_inspect_method(key) ||
         interrogate_object(
-          method_name: :display_name, kwargs: object_method_keyword_arguments)
+          method_name: :display_name,
+          kwargs: object_method_keyword_arguments,
+        )
     end
   end
 
   private
 
+  attr_reader :scope,
+              :formatter_class,
+              :kwargs
+
   def formatter
-    @formatter_class.new(self)
+    formatter_class.new(self)
   end
 
-  # @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 [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}.
   def value(key:)
     return_value =
-      if @kwargs.key?(key)
-        evaluate_passed_in_value(@kwargs[key])
+      if kwargs.key?(key)
+        evaluate_passed_in_value(kwargs[key])
       else
         interrogate_object_inspect_method(key)
       end
@@ -132,10 +149,10 @@ class ObjectInspector::Inspector
   # Call `value` on {#object} if it responds to it and the result is not nil,
   # else just return `value`.
   #
-  # @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 [#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.
   def evaluate_passed_in_value(value)
     if value.is_a?(Symbol)
       interrogate_object(method_name: value) || value
@@ -146,47 +163,44 @@ class ObjectInspector::Inspector
 
   # Attempt to call `inspect_*` on {#object} based on the passed in `name`.
   #
-  # @return [String] if {#object} responds to
-  #   `#{object_inspection_method_name}` (e.g. `inspect_flags`)
-  # @return [NilClass] if not found on {#object}
+  # @return [String] If {#object} responds to
+  #   `#{object_inspection_method_name}` (e.g. `inspect_flags`).
+  # @return [NilClass] If not found on {#object}.
   def interrogate_object_inspect_method(
-        name,
-        prefix: ObjectInspector.configuration.inspect_method_prefix)
+    name,
+    prefix: ObjectInspector.configuration.inspect_method_prefix
+  )
     interrogate_object(
-      method_name: object_inspection_method_name(name, prefix: prefix),
-      kwargs: object_method_keyword_arguments)
+      method_name: object_inspection_method_name(name, prefix:),
+      kwargs: object_method_keyword_arguments,
+    )
   end
 
   def interrogate_object(method_name:, kwargs: {})
-    interrogator =
-      ObjectInspector::ObjectInterrogator.new(
-        object: @object,
-        method_name: method_name,
-        kwargs: kwargs)
-
-    interrogator.call
+    ObjectInspector::InterrogateObject.(object, method_name:, kwargs:)
   end
 
   # :reek:UtilityFunction
+
   def object_inspection_method_name(
-        name,
-        prefix: ObjectInspector.configuration.inspect_method_prefix)
+    name,
+    prefix: ObjectInspector.configuration.inspect_method_prefix
+  )
     "#{prefix}_#{name}"
   end
 
   def object_method_keyword_arguments
-    {
-      scope: @scope,
-    }
+    { scope: }
   end
 
   def extract_wrapped_object
-    @object.to_model
+    object.to_model
   end
 
   # :reek:ManualDispatch
+
   def object_is_a_wrapper?
-    @object.respond_to?(:to_model) &&
-      @object.to_model != @object
+    object.respond_to?(:to_model) &&
+      object.to_model != object
   end
 end

data/lib/object_inspector/{object_interrogator.rb → interrogate_object.rb}

@@ -1,25 +1,27 @@
 # frozen_string_literal: true
 
-# ObjectInspector::ObjectInterrogator collaborates with {#object} to return
-# Object#{#method_name} if {#object} responds to the method.
+# Collaborates with {#object} to return {#object}#{#method_name} if {#object}
+# responds to {#method_name}.
 #
-# If Object#{#method_name} accepts the supplied `kwargs` then they are passed
+# 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::ObjectInterrogator
+class ObjectInspector::InterrogateObject
+  def self.call(...) = new(...).call
+
   attr_reader :object,
               :method_name,
               :kwargs
 
-  def initialize(object:, method_name:, kwargs: {})
+  def initialize(object, method_name:, kwargs: {})
     @object = object
     @method_name = method_name
     @kwargs = kwargs
   end
 
-  # @return [String, ...] whatever type Object#{#method_name} returns
+  # @return [String, ...] Whatever type Object#{#method_name} returns.
   #
-  # @raise [ArgumentError] if Object#{#method_name} has an unexpected method
-  #   signature
+  # @raise [ArgumentError] If Object#{#method_name} has an unexpected method
+  #   signature.
   def call
     return unless object_responds_to_method_name?
 
@@ -40,6 +42,7 @@ class ObjectInspector::ObjectInterrogator
 
   # :reek:ManualDispatch
   # :reek:BooleanParameter
+
   def object_responds_to_method_name?(include_private: true)
     object.respond_to?(method_name, include_private)
   end

data/lib/object_inspector/scope.rb

@@ -2,9 +2,8 @@
 
 # :reek:TooManyMethods
 
-# ObjectInspector::Scope defines a predicate method that matches {#names} and
-# responds with `true`. This is a prettier way to test for a given type of
-# "scope" within objects.
+# Defines a predicate method that matches {#names} and responds with `true`.
+# This is a prettier way to test for a given type of "scope" within objects.
 #
 # It is possible to pass in multiple scope names to match on.
 #
@@ -13,6 +12,16 @@
 # Passing a block to a scope predicate falls back to the out-of-scope
 # placeholder (`*` by default) if the scope does not match.
 #
+# @example
+#   ObjectInspector::Scope.new
+#   # => <ObjectInspector::Scope :: ["self"]>
+#
+#   ObjectInspector::Scope.new(:my_custom_scope)
+#   # => <ObjectInspector::Scope :: ["my_custom_scope"]>
+#
+#   ObjectInspector::Scope.new(%w[verbose complex])
+#   # => <ObjectInspector::Scope :: ["complex", "verbose"]>
+#
 # @see ActiveSupport::StringInquirer
 #   http://api.rubyonrails.org/classes/ActiveSupport/StringInquirer.html
 #
@@ -20,8 +29,11 @@
 class ObjectInspector::Scope
   attr_reader :names
 
-  def initialize(names = %w[self])
-    @names = Array(names).map { |name| String(name) }
+  # :reek:FeatureEnvy
+
+  def initialize(*names)
+    names = names.empty? ? %w[self] : names.flatten
+    @names = names.map! { |name| String(name) }.sort!
   end
 
   # Join the passed in name parts with the passed in separator.
@@ -29,7 +41,9 @@ class ObjectInspector::Scope
   # @param parts [Array<#to_s>]
   # @param separator [#to_s] (ObjectInspector.configuration.flags_separator)
   def join_name(
-        parts, separator: ObjectInspector.configuration.name_separator)
+    parts,
+    separator: ObjectInspector.configuration.name_separator
+  )
     _join(parts, separator)
   end
 
@@ -38,7 +52,9 @@ class ObjectInspector::Scope
   # @param flags [Array<#to_s>]
   # @param separator [#to_s] (ObjectInspector.configuration.flags_separator)
   def join_flags(
-        flags, separator: ObjectInspector.configuration.flags_separator)
+    flags,
+    separator: ObjectInspector.configuration.flags_separator
+  )
     _join(flags, separator)
   end
 
@@ -47,7 +63,9 @@ class ObjectInspector::Scope
   # @param issues [Array<#to_s>]
   # @param separator [#to_s] (ObjectInspector.configuration.issues_separator)
   def join_issues(
-        issues, separator: ObjectInspector.configuration.issues_separator)
+    issues,
+    separator: ObjectInspector.configuration.issues_separator
+  )
     _join(issues, separator)
   end
 
@@ -56,19 +74,21 @@ class ObjectInspector::Scope
   # @param items [Array<#to_s>]
   # @param separator [#to_s] (ObjectInspector.configuration.info_separator)
   def join_info(
-        items, separator: ObjectInspector.configuration.info_separator)
+    items,
+    separator: ObjectInspector.configuration.info_separator
+  )
     _join(items, separator)
   end
 
   # Compare self with the passed in object.
   #
-  # @return [TrueClass] if self and `other` resolve to the same set of objects
-  # @return [FalseClass] if self and `other` resolve to a different set of
-  #   objects
+  # @return [TrueClass] If self and `other` resolve to the same set of objects.
+  # @return [FalseClass] If self and `other` resolve to a different set of
+  #   objects.
   def ==(other)
-    @names.sort == Array(other).map(&:to_s).sort!
+    names == Array(other).map(&:to_s).sort!
   end
-  alias_method :eql?, :==
+  alias eql? ==
 
   # @return [String] the contents of {#names}, joined by `, `.
   def to_s(separator: ", ")
@@ -80,6 +100,10 @@ class ObjectInspector::Scope
     names
   end
 
+  def inspect
+    "<#{self.class.name} :: #{names.inspect}>"
+  end
+
   private
 
   def method_missing(method_name, *args, &)
@@ -131,10 +155,11 @@ class ObjectInspector::Scope
   end
 
   def any_names_match?(other_name)
-    @names.any?(other_name)
+    names.any?(other_name)
   end
 
   # :reek:BooleanParameter
+
   def respond_to_missing?(method_name, include_private = false)
     method_name[-1] == "?" || super
   end

data/lib/object_inspector/version.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
+# :reek:IrresponsibleModule
+
 module ObjectInspector
   # The current ObjectInspector gem version.
-  VERSION = "0.9.0"
+  VERSION = "1.0.0"
+  public_constant :VERSION
 end

data/lib/object_inspector.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# ObjectInspector is the base namespace for all modules/classes related to the
+# Defines the base namespace for all modules/classes used by the
 # object_inspector gem.
 module ObjectInspector
   # Accessor for the {ObjectInspector::Configuration} object.
@@ -19,11 +19,11 @@ module ObjectInspector
     @configuration = Configuration.new
   end
 
+  # :reek:TooManyInstanceVariables
+
   # ObjectInspector::Configuration stores the default configuration options for
   # the ObjectInspector gem. Modification of attributes is possible at any time,
   # and values will persist for the duration of the running process.
-  #
-  # :reek:TooManyInstanceVariables
   class Configuration
     attr_reader :formatter_class,
                 :inspect_method_prefix,
@@ -36,7 +36,8 @@ module ObjectInspector
                 :issues_separator,
                 :info_separator
 
-    def initialize
+    def initialize # rubocop:disable Metrics/MethodLength
+      @enabled = true
       @formatter_class = TemplatingFormatter
       @inspect_method_prefix = "inspect"
       @default_scope = Scope.new(:self)
@@ -49,6 +50,21 @@ module ObjectInspector
       @info_separator = " | "
     end
 
+    def toggle = enabled? ? disable : enable
+    def enabled? = @enabled
+
+    def enable
+      @enabled = true
+      puts(" -> ObjectInspector enabled")
+    end
+
+    def disabled? = !enabled?
+
+    def disable
+      @enabled = false
+      puts(" -> ObjectInspector disabled")
+    end
+
     def formatter_class=(value)
       unless value.is_a?(Class)
         raise(TypeError, "Formatter must be a Class constant")
@@ -99,8 +115,8 @@ require "object_inspector/version"
 require "object_inspector/conversions"
 require "object_inspector/inspector"
 require "object_inspector/scope"
-require "object_inspector/inspectors_helper"
-require "object_inspector/object_interrogator"
+require "object_inspector/inspect_behaviors"
+require "object_inspector/interrogate_object"
 require "object_inspector/formatters/base_formatter"
 require "object_inspector/formatters/combining_formatter"
 require "object_inspector/formatters/templating_formatter"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: object_inspector
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Paul DobbinSchmaltz
 bindir: exe
 cert_chain: []
-date: 2025-03-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
@@ -82,9 +82,9 @@ files:
 - lib/object_inspector/formatters/base_formatter.rb
 - lib/object_inspector/formatters/combining_formatter.rb
 - lib/object_inspector/formatters/templating_formatter.rb
+- lib/object_inspector/inspect_behaviors.rb
 - lib/object_inspector/inspector.rb
-- lib/object_inspector/inspectors_helper.rb
-- lib/object_inspector/object_interrogator.rb
+- lib/object_inspector/interrogate_object.rb
 - lib/object_inspector/scope.rb
 - lib/object_inspector/version.rb
 homepage: https://github.com/pdobb/object_inspector
@@ -110,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Object Inspector builds uniformly formatted inspect output with customizable
   amounts of detail.

data/lib/object_inspector/inspectors_helper.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-# ObjectInspector::InspectorsHelper can be included into any object to
-# simplify the process of instantiating an ObjectInspector::Inspector and
-# generating the inspection output.
-module ObjectInspector::InspectorsHelper
-  # Calls {ObjectInspector::Inspector.inspect} on the passed in `object`,
-  # passing it the passed in `kwargs` (keyword arguments).
-  #
-  # @return [String]
-  def inspect(object = self, **)
-    ObjectInspector::Inspector.inspect(object, **)
-  end
-end