object_inspector 0.10.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1468942ef1aa4a276a2138a904f34329d8b1e9846b58e013c208fbfe4a9113da
-  data.tar.gz: a552ef57ab52b60f208bbe2fceac50f96be25a340cd3854864a5d6a54e3d886f
+  metadata.gz: fd42799a69895e8a918436eaa6688090722f4dde5d406f34b36eae201459f82a
+  data.tar.gz: 1ea233bec14fddd0b57ffb797da6009471f8f9f989fee45f204af8813b70f59e
 SHA512:
-  metadata.gz: 2d02eab73350615584726ada8923bcdea3d428cf61d8e95abf17778b4b76836f828b2c12389dadf1aebe85e369106b4396da1e8501f81fe4e74b44a3031171b8
-  data.tar.gz: 1d044028f4889d0b6bd5615d5f035e19e5bf6ce7e5a30a30ce54a686edb403dd89a826bf8cfd0c4a89781c862af798d4e50ce9a1ed0080012f33a99ec4e477e1
+  metadata.gz: f30121bcdddfd33c7990197e4513eb44a84a487afc4f346a5823067760e2754aaf7ae0871ae58157ef45686de4a885e2db798e97e7a35671c5b0143fedafb11c
+  data.tar.gz: 4ed8d2ac33b52b4af28bc621a2e92fd429039c6951a2d8d10a38e866a9d101e2f18d24a60125fb189b367232293068c63a3ca0ec0bdaa1bb6df37119f26db5d0

data/README.md

@@ -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,34 +182,74 @@ 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>
 ```
 
-### Helper Inclusion
+### Disabling ObjectInspector
 
-It may be useful to conditionally include ObjectInspector::InspectorsHelper, as well as other similar methods, via a mix-in.
+You may disable / re-enable Object Inspector output (via the included helper method) for the current session:
 
 ```ruby
-module ObjectInspectionBehaviors
-  extend ActiveSupport::Concern
+MyObject.new # =>
+<My Object(FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>
 
-  included do
-    # If you'd like to preserve the original inspect method, here is your
-    # chance to.
-    alias_method :__inspect__, :inspect
+ObjectInspector.configuration.disable # =>
+ -> ObjectInspector disabled
+MyObject.new # =>
+#<MyObject:0x000000012332c458>
 
-    include ObjectInspector::InspectorsHelper
-  end
+ObjectInspector.configuration.enable # =>
+ -> ObjectInspector enabled
+MyObject.new # =>
+<My Object(FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>
+```
 
-  # An example of another, similar style of method you may wish to utilize in
-  # this mix-in.
+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
 
 Use the `scope` option to define the scope of the `inspect_*` methods. The supplied value will be wrapped by the ObjectInspector::Scope helper object.
@@ -212,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:
 
@@ -240,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
@@ -251,13 +296,13 @@ 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::InspectorsHelper` is equivalent to passing in the "wild card" scope.
+_**NOTE**_: Calling `#inspect!` on an object that mixes in `ObjectInspector::InspectBehaviors` is equivalent to passing in the "wild card" scope.
 
 ### Scope blocks
 
@@ -265,8 +310,8 @@ Passing a block to a scope predicate falls back to the out-of-scope placeholder
 
 ```ruby
 scope = ObjectInspector::Scope.new(:verbose)
-scope.verbose? { "MATCH" }  # => "MATCH"
-scope.complex? { "MATCH" }  # => "*"
+scope.verbose? { "MATCH" } # => "MATCH"
+scope.complex? { "MATCH" } # => "*"
 ```
 
 ### Scope Joiners
@@ -274,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:
@@ -294,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
@@ -377,16 +422,16 @@ 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
@@ -395,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
@@ -408,7 +453,7 @@ class MyWrapperObject
 end
 
 class MyWrappedObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   private
 
@@ -417,11 +462,11 @@ class MyWrappedObject
   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.inspect!
-# => "<MyWrapperObject(WRAPPER_FLAG1) !!CI1!!>  ⇨  <MyWrappedObject(FLAG1 / FLAG2) !!CI1!! INFO>"
+MyWrapperObject.new! # =>
+<MyWrapperObject(WRAPPER_FLAG1) !!CI1!!>  ⇨  <MyWrappedObject(FLAG1 / FLAG2) !!CI1!! INFO>
 ```
 
 This feature is recursive.
@@ -432,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
@@ -463,7 +508,7 @@ class MyDelegatingWrapperObject
 end
 
 class MyWrappedObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   def display_name
     "WRAPPED_OBJECT_NAME"
@@ -477,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
@@ -487,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"
@@ -495,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
@@ -506,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"
@@ -535,7 +580,7 @@ class MyCustomFormatter < ObjectInspector::BaseFormatter
 end
 
 class MyObject
-  include ObjectInspector::InspectorsHelper
+  include ObjectInspector::InspectBehaviors
 
   def inspect
     super(
@@ -547,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:
@@ -556,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
@@ -584,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

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
@@ -50,8 +59,8 @@ class ObjectInspector::Inspector
   # 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?
 
@@ -59,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
@@ -67,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
@@ -133,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
@@ -147,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.10.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.10.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Paul DobbinSchmaltz
 bindir: exe
 cert_chain: []
-date: 2025-04-02 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,24 +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 through any keyword arguments.
-  #
-  # @return [String]
-  def inspect(object = self, **)
-    ObjectInspector::Inspector.inspect(object, **)
-  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!(object = self, **)
-    ObjectInspector::Inspector.inspect(object, **, scope: :all)
-  end
-end