object_inspector 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3f1b53680d632fb88f63e951032b3be151ac352501620742cc091aaaf15a244
-  data.tar.gz: 4a059bdf8a0f6033d52bd05c1bb24ad83d33f7dde4d0b8ccd7ae010630566506
+  metadata.gz: 391dabb8dbbee7bad63ca6a701193227c2829affa135db1b58035153ced6d079
+  data.tar.gz: 9ce283422270b1dee3a517dfb39cb52438504867924061277732e16ac58347ca
 SHA512:
-  metadata.gz: 31eb8c71b23c092697db6b8f35b787581a472c13f6aded499602731546b2121fd07952650319e836af6368cf745f29f156ac2a31722a09a6d83cadb4c238e2d4
-  data.tar.gz: 6e605745d774bcca73bf93ccd6b818044bb10365832c2f3b2f182bb1884b4de145f0328d81d82ae78fdf65a4609053f51b242ba2790e6071ca083111f5becc7b
+  metadata.gz: 662abef818a3761fafcddbac8dfb7c1219afb3d4b49d9eff61fe9b843c5e45b9af9b3714ce75f62164157dbd9d01a6ff9ffa35a774fa88f1f029929bf8e27e0f
+  data.tar.gz: 8d8048b05386af2d81bea333827e9efadfba6b4de9bf62375e164ca46455773c962b798162e11671594048848c4904deb4ec0304cbcec2dba0ee1705aeec77b2

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2023 Paul DobbinSchmaltz
+Copyright (c) 2024 Paul DobbinSchmaltz
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,16 +1,15 @@
-# ObjectInspector
+# Object Inspector
 
-[![Gem Version](https://badge.fury.io/rb/object_inspector.svg)](https://badge.fury.io/rb/object_inspector)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/34e821263d9e0c33d536/test_coverage)](https://codeclimate.com/github/pdobb/object_inspector/test_coverage)
+[![Gem Version](https://img.shields.io/github/v/release/pdobb/object_inspector)](https://img.shields.io/github/v/release/pdobb/object_inspector)
+[![CI Actions](https://github.com/pdobb/object_inspector/actions/workflows/ci.yml/badge.svg)](https://github.com/pdobb/object_inspector/actions)
 [![Maintainability](https://api.codeclimate.com/v1/badges/34e821263d9e0c33d536/maintainability)](https://codeclimate.com/github/pdobb/object_inspector/maintainability)
 
-ObjectInspector 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.
+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, easy to build, and its output should be easy to read!
 
 If you'd like to just jump into an example: [Full Example](#full-example).
 
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -27,24 +26,19 @@ Or install it yourself:
 
     $ gem install object_inspector
 
-
 ## Compatibility
 
 Tested MRI Ruby Versions:
-* 2.3
-* 2.4
-* 2.5
-* 2.6
-* 2.7
-* 3.1
-* 3.2
 
-ObjectInspector has no other dependencies.
+- 3.1
+- 3.2
+- 3.3
 
+Object Inspector has no other dependencies.
 
 ## Configuration
 
-Global/default values for ObjectInspector can be configured via the ObjectInspector::Configuration object.
+Global/default values for Object Inspector can be configured via the ObjectInspector::Configuration object.
 
 _Note: In a Rails app, the following would go in e.g. `config/initializers/object_inspector.rb`_
 
@@ -64,7 +58,6 @@ ObjectInspector.configure do |config|
 end
 ```
 
-
 ## Usage
 
 Given, an object of any type, call ObjectInspector::Inspector.inspect.
@@ -81,7 +74,6 @@ MyObject.new.inspect  # => "<MyObject>"
 
 See also [Helper Usage](#helper-usage) for an even simpler usage option.
 
-
 ### Output Customization
 
 Use the `identification`, `flags`, `info`, and/or `name` options to customize inspect output.
@@ -122,7 +114,6 @@ MyObject.new.inspect
 # => "<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.
@@ -173,13 +164,11 @@ MyObject.new.inspect
 # => "<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)`.
 
-
 ### 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.
@@ -190,8 +179,8 @@ The ObjectInspector::Scope objects in these examples are the same as specifying
 my_object.inspect(scope: <scope_name>)
 ```
 
-
 Options:
+
 - `: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.
@@ -203,7 +192,6 @@ scope.verbose?  # => false
 scope.complex?  # => false
 ```
 
-
 #### Multiple Scope Names
 
 It is also possible to pass in multiple scope names to match on.
@@ -215,7 +203,6 @@ scope.verbose?  # => true
 scope.complex?  # => true
 ```
 
-
 #### The "Wild Card" Scope
 
 Finally, `:all` is a "wild card" scope name, and will match on all scope names.
@@ -227,7 +214,6 @@ scope.verbose?  # => true
 scope.complex?  # => true
 ```
 
-
 ### 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.
@@ -238,7 +224,6 @@ scope.verbose? { "MATCH" }  # => "MATCH"
 scope.complex? { "MATCH" }  # => "*"
 ```
 
-
 ### Scope Joiners
 
 ObjectInspector::Scope also offers helper methods for uniformly joining inspect elements:
@@ -256,7 +241,6 @@ scope.join_info([1, 2, 3])   # => "1 | 2 | 3"
 scope.join_info([1, 2, 3, nil])   # => "1 | 2 | 3"
 ```
 
-
 ## Full Example
 
 ```ruby
@@ -347,7 +331,6 @@ my_object.inspect
 # => "<MyObject[a2:2](DEFAULT_FLAG / AO1_FLAG1 / AO2_FLAG1) !!!!WARNING!!!! Default Info | Complex Info | Verbose Info :: Name>"
 ```
 
-
 ## Wrapped Objects
 
 If the Object being inspected wraps another object -- i.e. defines #to_model and #to_model returns an object other than self -- the inspect output will re-inspect the wrapped object. The wrapper points to the wrapped object with an arrow (⇨).
@@ -380,7 +363,6 @@ MyWrapperObject.new.inspect
 
 This feature is recursive.
 
-
 ### Wrapped Delegators
 
 If the Object being inspected is wrapped by an object that delegates all unknown methods to the wrapped object, then inspect flags will be doubled up. To get around this, redefine the `inspect` method in the Wrapper object e.g. like:
@@ -393,13 +375,13 @@ class MyDelegatingWrapperObject
     @my_object = my_object
   end
 
-  def inspect(**kargs)
+  def inspect(**kwargs)
     super(identification: self.class.name,
           name: nil,
           flags: nil,
           info: nil,
           issues: nil,
-          **kargs)
+          **kwargs)
   end
 
   def to_model
@@ -436,7 +418,6 @@ MyDelegatingWrapperObject.new(MyWrappedObject.new).inspect
 # => "<MyDelegatingWrapperObject>  ⇨  <MyWrappedObject(FLAG1) !!ISSUE1!! INFO :: NAME>"
 ```
 
-
 ## On-the-fly Inspect Methods
 
 When passed as an option (as opposed to being called via an Object-defined method) symbols will be called/evaluated on Object on the fly.
@@ -478,7 +459,6 @@ MyObject.new.inspect(identification: nil, info: nil, flags: nil, issues: nil)
 # => "<MyObject>"
 ```
 
-
 ## 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.
@@ -507,13 +487,13 @@ MyObject.new.inspect
 ```
 
 See examples:
+
 - [ObjectInspector::TemplatingFormatter]
 - [ObjectInspector::CombiningFormatter]
 
-
 ## Supporting Gems
 
-ObjectInspector works great with the [ObjectIdentifier](https://github.com/pdobb/object_identifier) gem.
+Object Inspector works great with the [Object Identifier](https://github.com/pdobb/object_identifier) gem.
 
 ```ruby
 class MyObject
@@ -543,31 +523,29 @@ MyObject.new.inspect
 # => "<MyObject[my_method1:1, my_method2:2](FLAG1 / FLAG2) !!ISSUE1 | ISSUE2!! INFO :: NAME>"
 ```
 
-
 ## Performance
 
-### Benchmarking ObjectInspector
+### Benchmarking Object Inspector
 
 ObjectInspetor is ~4x slower than Ruby's default inspect.
 
-Performance of ObjectInspect can be tested by playing the [ObjectInspector Benchmarking Scripts] in the pry console for this gem.
+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.
 
 ```ruby
-play scripts/benchmarking/object_inspector.rb
+load "script/benchmarking/object_inspector.rb"
 # Comparison:
 #                 Ruby:    30382.2 i/s
 # ObjectInspector::Inspector:     7712.2 i/s - 3.94x  slower
 ```
 
-
 ### Benchmarking Formatters
 
 [ObjectInspector::TemplatingFormatter] -- which is the default Formatter -- outperforms [ObjectInspector::CombiningFormatter] by about 30% on average.
 
-Performance of Formatters can be tested by playing the [Formatters Benchmarking Scripts] in the pry console for this gem.
+Performance of Formatters can be tested by playing the [Formatters Benchmarking Scripts](https://github.com/pdobb/object_inspector/blob/master/script/benchmarking/formatters.rb) in the IRB console for this gem.
 
 ```ruby
-play scripts/benchmarking/formatters.rb
+load "script/benchmarking/formatters.rb"
 # == Averaged =============================================================
 # ...
 #
@@ -578,7 +556,6 @@ play scripts/benchmarking/formatters.rb
 # == Done
 ```
 
-
 #### Benchmarking Custom Formatters
 
 Custom Formatters may be similarly gauged for comparison by adding them to the `custom_formatter_klasses` array before playing the script.
@@ -586,7 +563,7 @@ Custom Formatters may be similarly gauged for comparison by adding them to the `
 ```ruby
 custom_formatter_klasses = [MyCustomFormatter]
 
-play scripts/benchmarking/formatters.rb
+play script/benchmarking/formatters.rb
 # == Averaged =============================================================
 # ...
 #
@@ -598,27 +575,60 @@ play scripts/benchmarking/formatters.rb
 # == Done
 ```
 
-
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. Or, run `rake` to run the tests plus linters as well as `yard` (to confirm proper YARD documentation practices). You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
-To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Testing
+
+To test this gem (gemwork):
+
+```bash
+rake
+```
+
+#### Linters
+
+```bash
+rubocop
+
+reek
 
+npx prettier . --check
+npx prettier . --write
+```
+
+### Releases
+
+To release a new version of object_inspector 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
+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).
+
+### Documentation
+
+[YARD documentation](https://yardoc.org/index.html) can be generated and viewed live:
+
+1. Install YARD: `gem install yard`
+2. Run the YARD server: `yard server --reload`
+3. Open the live documentation site: `open http://localhost:8808`
+
+While the YARD server is running, documentation in the live site will be auto-updated on source code save (and site reload).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/pdobb/object_inspector.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-
 [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
-[ObjectInspector Benchmarking Scripts]: https://github.com/pdobb/object_inspector/blob/master/scripts/benchmarking/object_inspector.rb
-[Formatters Benchmarking Scripts]: https://github.com/pdobb/object_inspector/blob/master/scripts/benchmarking/formatters.rb
+[Object Inspector Benchmarking Scripts]: https://github.com/pdobb/object_inspector/blob/master/script/benchmarking/object_inspector.rb
+[Formatters Benchmarking Scripts]: https://github.com/pdobb/object_inspector/blob/master/script/benchmarking/formatters.rb

data/lib/object_inspector/conversions.rb

@@ -1,23 +1,23 @@
 # frozen_string_literal: true
 
-module ObjectInspector
-  # ObjectInspector::Conversions defines conversion functions used by
-  # ObjectInspector.
-  module Conversions
-    module_function
+# ObjectInspector::Conversions defines conversion functions used by
+# ObjectInspector.
+module ObjectInspector::Conversions
+  module_function
 
-    # Convert the passed in value to an {ObjectInspector::Scope} object.
-    # Just returns the pass in value if it already is an
-    # {ObjectInspector::Scope} object.
-    #
-    # @return [ObjectInspector::Scope]
-    def Scope(value) # rubocop:disable Naming/MethodName
-      case value
-      when ObjectInspector::Scope
-        value
-      else
-        ObjectInspector::Scope.new(value)
-      end
+  # 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]
+  #
+  # :reek:UncommunicativeMethodName
+  def Scope(value) # rubocop:disable Naming/MethodName
+    case value
+    when ObjectInspector::Scope
+      value
+    else
+      ObjectInspector::Scope.new(value)
     end
   end
 end

data/lib/object_inspector/formatters/base_formatter.rb

@@ -1,71 +1,69 @@
 # frozen_string_literal: true
 
-module ObjectInspector
-  # 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.
-  class BaseFormatter
-    attr_reader :inspector
+# 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.
+class ObjectInspector::BaseFormatter
+  attr_reader :inspector
 
-    # @param inspector [ObjectInspector::Inspector]
-    def initialize(inspector)
-      @inspector = inspector
-    end
+  # @param inspector [ObjectInspector::Inspector]
+  def initialize(inspector)
+    @inspector = inspector
+  end
 
-    # Perform the formatting routine.
-    #
-    # @return [String]
-    def call
-      raise NotImplementedError
-    end
+  # Perform the formatting routine.
+  #
+  # @return [String]
+  def call
+    raise NotImplementedError
+  end
 
-    # Delegates to {Inspector#wrapped_object_inspection_result}.
-    #
-    # @return [String] if given
-    # @return [NilClass] if not given
-    def wrapped_object_inspection_result
-      @wrapped_object_inspection_result ||=
-        @inspector.wrapped_object_inspection_result
-    end
+  # Delegates to {Inspector#wrapped_object_inspection_result}.
+  #
+  # @return [String] if given
+  # @return [NilClass] if not given
+  def wrapped_object_inspection_result
+    @wrapped_object_inspection_result ||=
+      @inspector.wrapped_object_inspection_result
+  end
 
-    # Delegates to {Inspector#identification}.
-    #
-    # @return [String] if given
-    def identification
-      @identification ||= @inspector.identification
-    end
+  # Delegates to {Inspector#identification}.
+  #
+  # @return [String] if given
+  def identification
+    @identification ||= @inspector.identification
+  end
 
-    # Delegates to {Inspector#flags}.
-    #
-    # @return [String] if given
-    # @return [NilClass] if not given
-    def flags
-      @flags ||= @inspector.flags
-    end
+  # Delegates to {Inspector#flags}.
+  #
+  # @return [String] if given
+  # @return [NilClass] if not given
+  def flags
+    @flags ||= @inspector.flags
+  end
 
-    # Delegates to {Inspector#issues}.
-    #
-    # @return [String] if given
-    # @return [NilClass] if not given
-    def issues
-      @issues ||= @inspector.issues
-    end
+  # Delegates to {Inspector#issues}.
+  #
+  # @return [String] if given
+  # @return [NilClass] if not given
+  def issues
+    @issues ||= @inspector.issues
+  end
 
-    # Delegates to {Inspector#info}.
-    #
-    # @return [String] if given
-    # @return [NilClass] if not given
-    def info
-      @info ||= @inspector.info
-    end
+  # Delegates to {Inspector#info}.
+  #
+  # @return [String] if given
+  # @return [NilClass] if not given
+  def info
+    @info ||= @inspector.info
+  end
 
-    # Delegates to {Inspector#name}.
-    #
-    # @return [String] if given
-    # @return [NilClass] if not given
-    def name
-      @name ||= @inspector.name
-    end
+  # Delegates to {Inspector#name}.
+  #
+  # @return [String] if given
+  # @return [NilClass] if not given
+  def name
+    @name ||= @inspector.name
   end
 end

data/lib/object_inspector/formatters/combining_formatter.rb

@@ -1,63 +1,61 @@
 # frozen_string_literal: true
 
-module ObjectInspector
-  # ObjectInspector::CombiningFormatter implements
-  # {ObjectInspector::BaseFormatter} to return the standard/default inspect
-  # output format by combining Strings.
+# ObjectInspector::CombiningFormatter implements
+# {ObjectInspector::BaseFormatter} to return the standard/default inspect
+# output format by combining Strings.
+#
+# @attr (see BaseFormatter)
+class ObjectInspector::CombiningFormatter < ObjectInspector::BaseFormatter
+  # Perform the formatting routine.
   #
-  # @attr (see BaseFormatter)
-  class CombiningFormatter < BaseFormatter
-    # Perform the formatting routine.
-    #
-    # @return [String]
-    def call
-      if wrapped_object_inspection_result
-        build_wrapped_object_string
-      else
-        build_string
-      end
+  # @return [String]
+  def call
+    if wrapped_object_inspection_result
+      build_wrapped_object_string
+    else
+      build_string
     end
+  end
 
-    private
+  private
 
-    def build_wrapped_object_string
-      "#{build_string} "\
+  def build_wrapped_object_string
+    "#{build_string} "\
       "#{ObjectInspector.configuration.presented_object_separator} "\
       "#{wrapped_object_inspection_result}"
-    end
+  end
 
-    def build_string
-      "<#{combine_strings}>"
-    end
+  def build_string
+    "<#{combine_strings}>"
+  end
 
-    def combine_strings
-      strings.join
-    end
+  def combine_strings
+    strings.join
+  end
 
-    # Override in subclasses as needed.
-    def strings
-      [
-        build_identification_string,
-        build_flags_string,
-        build_info_string,
-        build_name_string
-      ].compact
-    end
+  # Override in subclasses as needed.
+  def strings
+    [
+      build_identification_string,
+      build_flags_string,
+      build_info_string,
+      build_name_string,
+    ].compact
+  end
 
-    def build_identification_string
-      identification.to_s
-    end
+  def build_identification_string
+    identification.to_s
+  end
 
-    def build_flags_string
-      "(#{flags.to_s.upcase})" if flags
-    end
+  def build_flags_string
+    "(#{flags.to_s.upcase})" if flags
+  end
 
-    def build_info_string
-      " #{info}" if info
-    end
+  def build_info_string
+    " #{info}" if info
+  end
 
-    def build_name_string
-      " :: #{name}" if name
-    end
+  def build_name_string
+    " :: #{name}" if name
   end
 end