object_inspector 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 695389e5c3a953c4bfd33d5fbe987008beb63c5a1235c4a8d3fdeb894b5727e5
-  data.tar.gz: a05becc6eec712e462d979fd6c23e4c6375cfb4bd2b9503e1752bd218bdf70ca
+  metadata.gz: 8f80de3b28fe43b95e5fb12538a371807689aa29da9bf7d8a91eb9c4b8b4086c
+  data.tar.gz: 775cecd797055357a8b4fb1c97d7c02a2821b8fbfbb0482f5a646f68da6a3710
 SHA512:
-  metadata.gz: 0c6023ee714bcdebbb198d7d3a1635d4c696f262a7112b7f457821c03fc889bb75c68f0112a94c95c5c8ae253c0c07ef8f920b8e0708bc809274c3d4f63d10ae
-  data.tar.gz: f9d07b12b361f774800f47805c357373b3e674c61cf74299f8672d4237bb953fa12e6e7238840df5f2afede96dbb7fad09d69b4115e760929b73613aa463fe91
+  metadata.gz: 3a0a0c78c42099cc7ea4b03276f6d06182ccad7e4ff657a4875cbe6690f7e277c3861fe7e5f00ebd8f7059516abb064f50ef78bf73ce26fd929f22a23143fddb
+  data.tar.gz: 136d08a468531350650e48585f4471948cfdbd877ea4d462d07c11acdb381b276855c9520367dd1fc00ed8a21924b96a561e32b06d7dd51292a8705127221378

data/.travis.yml

@@ -9,6 +9,8 @@ rvm:
   - 2.4.4
   - 2.5.1
   - ruby-head
+notifications:
+  email: false
 before_install: gem install bundler -v 1.16.1
 cache: bundler
 before_script:

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+#### TODO
+* Add "placeholder" symbol (*) for scope exclusions.
+* Add gem defaults configuration.
+
+
+### 0.2.0 - 2018-04-12
+
+* Automatically inspect wrapped Objects, if applicable.
+* Use `display_name` if defined on object, in place of `inspect_name`.
+* Add on-the-fly inspect methods when Symbols are passed in to #inspect.
+* Update the `flags` and `info` demarcation symbols.
+* Add ObjectInspector::TemplatingFormatter, and use it as the new default since it's faster.
+* Rename ObjectInspector::DefaultFormatter to ObjectInspector::CombiningFormatter.
+
+
 ### 0.1.0 - 2018-04-09
 
 * Initial release!

data/Gemfile.lock

@@ -6,12 +6,20 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    ansi (1.5.0)
+    benchmark-ips (2.7.2)
+    builder (3.2.3)
     byebug (10.0.2)
     coderay (1.1.2)
     docile (1.3.0)
     json (2.1.0)
     method_source (0.9.0)
     minitest (5.11.3)
+    minitest-reporters (1.2.0)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
     pry (0.11.3)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
@@ -19,6 +27,7 @@ GEM
       byebug (~> 10.0)
       pry (~> 0.10)
     rake (10.4.2)
+    ruby-progressbar (1.9.0)
     simplecov (0.16.1)
       docile (~> 1.1)
       json (>= 1.8, < 3)
@@ -29,9 +38,11 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  benchmark-ips (~> 2.7)
   bundler (~> 1.16)
   byebug (~> 10.0)
   minitest (~> 5.0)
+  minitest-reporters (~> 1.2)
   object_inspector!
   pry (~> 0.11)
   pry-byebug (~> 3.6)

data/README.md

@@ -1,11 +1,11 @@
 # ObjectInspector
 
-[![Gem Version](https://badge.fury.io/rb/object_inspector.png)](http://badge.fury.io/rb/object_inspector)
+[![Gem Version](https://badge.fury.io/rb/object_inspector.svg)](https://badge.fury.io/rb/object_inspector)
 [![Build Status](https://travis-ci.org/objects-on-rails/display-case.svg?branch=master)](https://travis-ci.org/objects-on-rails/display-case)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/34e821263d9e0c33d536/test_coverage)](https://codeclimate.com/github/pdobb/object_inspector/test_coverage)
 [![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, info, and/or a name along with a self-definable scope option to represent an object in the console, in logging, or otherwise.
+ObjectInspector takes Object#inspect to the next level. Specify any combination of identification attributes, flags, info, and/or a name along with an optional self-definable scope option to represent an object in the console, in logging, etc.
 
 
 ## Installation
@@ -36,19 +36,7 @@ Tested MRI Ruby Versions:
 
 ## Usage
 
-Given, an object of any type, call ObjectInspector::Inspect#to_s.
-
-```ruby
-class MyObject
-  def inspect
-    ObjectInspector::Inspector.new(self).to_s
-  end
-end
-
-MyObject.new.inspect  # => "<MyObject>"
-```
-
-Or, just use the ObjectInspector::Inspector.inspect method.
+Given, an object of any type, call ObjectInspector::Inspector.inspect.
 
 ```ruby
 class MyObject
@@ -65,24 +53,23 @@ See also [Helper Usage](#helper-usage) for an even simpler usage option.
 
 ### Output Customization
 
-Use ObjectInspector::Inspector#initialize options -- `identification`, `flags`, `info`, and `name` -- to customize inspect output.
+Use the `identification`, `flags`, `info`, and `name` options to customize inspect output.
 
 ```ruby
 class MyObject
   def inspect
-    ObjectInspector::Inspector.inspect(
-      self,
-      identification: "My Object",
-      flags: "FLAG1",
-      info: "INFO",
-      name: "NAME")
+    ObjectInspector::Inspector.inspect(self,
+                                       identification: "My Object",
+                                       flags: "FLAG1",
+                                       info: "INFO",
+                                       name: "NAME")
   end
 end
 
-MyObject.new.inspect  # => "<My Object[FLAG1] (INFO) :: NAME>"
+MyObject.new.inspect  # => "<My Object(FLAG1) INFO :: NAME>"
 ```
 
-Or, define `inspect_identification`, `inspect_flags`, `inspect_info`, and `inspect_name` in Object.
+Or, define `inspect_identification`, `inspect_flags`, `inspect_info`, and `inspect_name` as either public or private methods on Object.
 
 ```ruby
 class MyObject
@@ -92,30 +79,19 @@ class MyObject
 
 private
 
-  def inspect_identification
-    "My Object"
-  end
-
-  def inspect_flags
-    "FLAG1"
-  end
-
-  def inspect_info
-    "INFO"
-  end
-
-  def inspect_name
-    "NAME"
-  end
+  def inspect_identification; "My Object" end
+  def inspect_flags; "FLAG1" end
+  def inspect_info; "INFO" end
+  def inspect_name; "NAME" end
 end
 
-MyObject.new.inspect  # => "<My Object[FLAG1] (INFO) :: NAME>"
+MyObject.new.inspect  # => "<My Object(FLAG1) INFO :: NAME>"
 ```
 
 
 ## Helper Usage
 
-To save a little typing, include ObjectInspector::InspectHelper into an object and  ObjectInspector::Inspector#to_s will be called for you on `self`.
+To save some typing, include ObjectInspector::InspectHelper into an object and ObjectInspector::Inspector.inspect will be called on `self` automatically.
 
 ```ruby
 class MyObject
@@ -139,7 +115,7 @@ class MyObject
   end
 end
 
-MyObject.new.inspect  # => "<My Object[FLAG1] (INFO) :: NAME>"
+MyObject.new.inspect  # => "<My Object(FLAG1) INFO :: NAME>"
 ```
 
 Or, define `inspect_identification`, `inspect_flags`, `inspect_info`, and `inspect_name` in Object.
@@ -150,39 +126,46 @@ class MyObject
 
 private
 
-  def inspect_identification
-    "My Object"
-  end
+  def inspect_identification; "My Object" end
+  def inspect_flags; "FLAG1" end
+  def inspect_info; "INFO" end
+  def inspect_name; "NAME" end
+end
 
-  def inspect_flags
-    "FLAG1"
-  end
+MyObject.new.inspect  # => "<My Object(FLAG1) INFO :: NAME>"
+```
 
-  def inspect_info
-    "INFO"
-  end
 
-  def inspect_name
-    "NAME"
-  end
+## 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.
+
+```ruby
+class MyObject
+  include ObjectInspector::InspectorsHelper
+
+  def my_method1; "Result1" end
+  def my_method2; "Result2" end
+
+  def inspect_info; :my_method2 end
 end
 
-MyObject.new.inspect  # => "<My Object[FLAG1] (INFO) :: NAME>"
+MyObject.new.inspect(info: "my_method1")  # => "<MyObject my_method1>"
+MyObject.new.inspect(info: :my_method2)   # => "<MyObject Result2>"
+MyObject.new.inspect                      # => "<MyObject my_method2>"
 ```
 
 
 #### Scope
 
-Use the `scope` option to define the scope of the `inspect_` methods.
+Use the `scope` option to define the scope of the `inspect_*` methods.
 
 If ActiveSupport::StringInquirer is defined then the default `scope` is `"self".inquiry`.
 The default value is `:self` if ActiveSupport::StringInquirer is not defined.
 
 ```ruby
 class MyObject
-  def inspect(scope: :self)
-    ObjectInspector::Inspector.inspect(self, scope: scope)
-  end
+  include ObjectInspector::InspectorsHelper
 
   def inspect_flags(scope:, separator: " / ".freeze)
     flags = ["FLAG1"]
@@ -197,37 +180,52 @@ class MyObject
   end
 end
 
-MyObject.new.inspect  # => "<MyObject[FLAG1]>"
-MyObject.new.inspect(scope: :all)  # => "<MyObject[FLAG1 / FLAG2]>"
+MyObject.new.inspect               # => "<MyObject(FLAG1)>"
+MyObject.new.inspect(scope: :all)  # => "<MyObject(FLAG1 / FLAG2)>"
 ```
 
 
-## Custom Formatters
+## Wrapped Objects
 
-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/base_formatter.rb) and then passing that into ObjectInspector::Inspector.new.
+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 (⇨).
 
 ```ruby
-class MyCustomFormatter < ObjectInspector::BaseFormatter
-  def call
-    "(#{combine_strings})"
+class MyWrapperObject
+  include ObjectInspector::InspectorsHelper
+
+  def to_model
+    @to_model ||= MyWrappedObject.new
   end
 
 private
 
-  def build_identification_string(identification = self.identification)
-    identification.to_s
-  end
+  def inspect_flags; "WRAPPER_FLAG1" end
+end
 
-  def build_flags_string(flags = self.flags)
-    " #{flags}" if flags
-  end
+class MyWrappedObject
+  include ObjectInspector::InspectorsHelper
 
-  def build_info_string(info = self.info)
-    " (#{info})" if info
-  end
+private
+
+  def inspect_flags; "FLAG1" end
+  def inspect_info; "INFO" end
+end
+
+MyWrapperObject.new.inspect
+# => "<MyWrapperObject(WRAPPER_FLAG1)> ⇨ <MyWrappedObject(FLAG1) INFO>"
+```
+
+This feature is recursive.
+
+
+## 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) and then passing that into ObjectInspector::Inspector.new.
 
-  def build_name_string(name = self.name)
-    " -- #{name}" if name
+```ruby
+class MyCustomFormatter < ObjectInspector::BaseFormatter
+  def call
+    "[#{identification} Flags: #{flags} -- Info: #{info} -- Name: #{name}]"
   end
 end
 
@@ -235,35 +233,77 @@ class MyObject
   include ObjectInspector::InspectorsHelper
 
   def inspect
-    super(formatter: MyCustomFormatter)
+    super(formatter: MyCustomFormatter,
+          identification: "IDENTIFICATION",
+          flags: "FLAG1 | FLAG2",
+          info: "INFO",
+          name: "NAME")
   end
+end
 
-private
+MyObject.new.inspect
+# => "[IDENTIFICATION Flags: FLAG1 | FLAG2 -- Info: INFO -- Name: NAME]"
+```
 
-  def inspect_identification
-    "IDENTIFICATION"
-  end
+See also: [ObjectInspector::TemplatingFormatter].
+See also: [ObjectInspector::CombiningFormatter].
 
-  def inspect_flags
-    "FLAG1"
-  end
 
-  def inspect_info
-    "INFO"
-  end
+## Performance
 
-  def inspect_name
-    "NAME"
-  end
-end
+### Benchmarking ObjectInspector
+
+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.
 
-MyObject.new.inspect  # => "(IDENTIFICATION FLAG1 (INFO) -- NAME)"
+```ruby
+play scripts/benchmarking/object_inspector.rb
+# Comparison:
+#                 Ruby:    30382.2 i/s
+# ObjectInspector::Inspector:     7712.2 i/s - 3.94x  slower
 ```
 
-See also: [ObjectInspector::DefaultFormatter](https://github.com/pdobb/object_inspector/blob/master/lib/object_inspector/default_formatter.rb).
+
+### 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.
+
+```ruby
+play scripts/benchmarking/formatters.rb
+# == Averaged =============================================================
+# ...
+#
+# Comparison:
+# ObjectInspector::TemplatingFormatter:    45725.3 i/s
+# ObjectInspector::CombiningFormatter:    34973.9 i/s - 1.31x  slower
+#
+# == 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.
+
+```ruby
+custom_formatter_klasses = [MyCustomFormatter]
+
+play scripts/benchmarking/formatters.rb
+# == Averaged =============================================================
+# ...
+#
+# Comparison:
+#    MyCustomFormatter:    52001.2 i/s
+# ObjectInspector::TemplatingFormatter:    49854.2 i/s - same-ish: difference falls within error
+# ObjectInspector::CombiningFormatter:    38963.5 i/s - 1.33x  slower
+#
+# == Done
+```
 
 
-## Supporting Libraries
+## Supporting Gems
 
 ObjectInspector works great with the [ObjectIdentifier](https://github.com/pdobb/object_identifier) gem.
 
@@ -272,33 +312,23 @@ class MyObject
   include ObjectInspector::InspectorsHelper
 
   def my_method1
-    "R1"
+    "Result1"
   end
 
-  def my_method1
-    "R1"
+  def my_method2
+    "Result2"
   end
 
 private
 
-  def inspect_identification
-    identify(:m1, :m2)
-  end
-
-  def inspect_flags
-    "FLAG1"
-  end
-
-  def inspect_info
-    "INFO"
-  end
-
-  def inspect_name
-    "NAME"
-  end
+  def inspect_identification; identify(:my_method1, :my_method2) end
+  def inspect_flags; "FLAG1" end
+  def inspect_info; "INFO" end
+  def inspect_name; "NAME" end
 end
 
-MyObject.new.inspect  # => "<MyObject[m1:R1, m2:R2][FLAG1] (INFO) :: NAME>"
+MyObject.new.inspect
+# => "<MyObject[my_method1:Result1, my_method2:Result2](FLAG1) INFO :: NAME>"
 ```
 
 
@@ -317,3 +347,9 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/pdobb/
 ## 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

data/lib/object_inspector/{base_formatter.rb → formatters/base_formatter.rb}

@@ -6,6 +6,8 @@ module ObjectInspector
   #
   # @attr inspector [ObjectInspector::Inspector]
   class BaseFormatter
+    RIGHT_ARROW_ICON = [0x21E8].pack("U").freeze
+
     attr_reader :inspector
 
     def initialize(inspector)
@@ -19,11 +21,19 @@ module ObjectInspector
       raise NotImplementedError
     end
 
+    # Delegates to {Inspector#wrapped_object_inspection}.
+    #
+    # @return [String] if given
+    # @return [NilClass] if not given
+    def wrapped_object_inspection
+      @wrapped_object_inspection ||= inspector.wrapped_object_inspection
+    end
+
     # Delegates to {Inspector#identification}.
     #
     # @return [String] if given
     def identification
-      @inspector.identification
+      @identification ||= inspector.identification
     end
 
     # Delegates to {Inspector#flags}.
@@ -31,7 +41,7 @@ module ObjectInspector
     # @return [String] if given
     # @return [NilClass] if not given
     def flags
-      @inspector.flags
+      @flags ||= inspector.flags
     end
 
     # Delegates to {Inspector#info}.
@@ -39,7 +49,7 @@ module ObjectInspector
     # @return [String] if given
     # @return [NilClass] if not given
     def info
-      @inspector.info
+      @info ||= inspector.info
     end
 
     # Delegates to {Inspector#name}.
@@ -47,39 +57,7 @@ module ObjectInspector
     # @return [String] if given
     # @return [NilClass] if not given
     def name
-      @inspector.name
-    end
-
-  private
-
-    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
-
-    def build_identification_string(*)
-      raise NotImplementedError
-    end
-
-    def build_flags_string(*)
-      raise NotImplementedError
-    end
-
-    def build_info_string(*)
-      raise NotImplementedError
-    end
-
-    def build_name_string(*)
-      raise NotImplementedError
+      @name ||= inspector.name
     end
   end
 end

data/lib/object_inspector/formatters/combining_formatter.rb

@@ -0,0 +1,59 @@
+module ObjectInspector
+  # ObjectInspector::CombiningFormatter implements
+  # {ObjectInspector::BaseFormatter} to return the standard/default inspect
+  # output format by combining Strings.
+  #
+  # @attr (see BaseFormatter)
+  class CombiningFormatter < BaseFormatter
+    # Perform the formatting routine.
+    #
+    # @return [String]
+    def call
+      if wrapped_object_inspection
+        build_wrapped_object_string
+      else
+        build_string
+      end
+    end
+
+  private
+
+    def build_wrapped_object_string
+      "#{build_string} #{RIGHT_ARROW_ICON} #{wrapped_object_inspection}"
+    end
+
+    def build_string
+      "<#{combine_strings}>"
+    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
+
+    def build_identification_string
+      identification.to_s
+    end
+
+    def build_flags_string
+      "(#{flags.to_s.upcase})" if flags
+    end
+
+    def build_info_string
+      " #{info}" if info
+    end
+
+    def build_name_string
+      " :: #{name}" if name
+    end
+  end
+end

data/lib/object_inspector/formatters/templating_formatter.rb

@@ -0,0 +1,143 @@
+module ObjectInspector
+  # ObjectInspector::TemplatingFormatter implements
+  # {ObjectInspector::BaseFormatter} to return the standard/default inspect
+  # output format via String templates.
+  #
+  # @attr (see BaseFormatter)
+  class TemplatingFormatter < BaseFormatter
+    def self.base_template
+      @base_template ||= "<%s>".freeze
+    end
+
+    def self.name_template
+      @name_template ||= "<%s :: %s>".freeze
+    end
+
+    def self.flags_and_name_template
+      @flags_and_name_template ||= "<%s(%s) :: %s>".freeze
+    end
+
+    def self.info_and_name_template
+      @info_and_name_template ||= "<%s %s :: %s>".freeze
+    end
+
+    def self.flags_and_info_template
+      @flags_and_info_template ||= "<%s(%s) %s>".freeze
+    end
+
+    def self.flags_and_info_and_name_template
+      @flags_and_info_and_name_template ||= "<%s(%s) %s :: %s>".freeze
+    end
+
+    def self.flags_template
+      @flags_template ||= "<%s(%s)>".freeze
+    end
+
+    def self.info_template
+      @info_template ||= "<%s %s>".freeze
+    end
+
+    # Perform the formatting routine.
+    #
+    # @return [String]
+    def call
+      if wrapped_object_inspection
+        build_wrapped_object_string
+      else
+        build_string
+      end
+    end
+
+  private
+
+    def build_wrapped_object_string
+      "#{build_string} #{RIGHT_ARROW_ICON} #{wrapped_object_inspection}"
+    end
+
+    def build_string
+      if flags
+        if info
+          if name
+            build_flags_and_info_and_name_string
+          else
+            build_flags_and_info_string
+          end
+        elsif name
+          build_flags_and_name_string
+        else
+          build_flags_string
+        end
+      elsif info
+        if name
+          build_info_and_name_string
+        else
+          build_info_string
+        end
+      elsif name
+        build_name_string
+      else
+        build_base_string
+      end
+    end
+
+    def build_flags_and_info_and_name_string
+      self.class.flags_and_info_and_name_template % [
+        identification,
+        flags,
+        info,
+        name
+      ]
+    end
+
+    def build_flags_and_info_string
+      self.class.flags_and_info_template % [
+        identification,
+        flags,
+        info
+      ]
+    end
+
+    def build_flags_and_name_string
+      self.class.flags_and_name_template % [
+        identification,
+        flags,
+        name
+      ]
+    end
+
+    def build_info_and_name_string
+      self.class.info_and_name_template % [
+        identification,
+        info,
+        name
+      ]
+    end
+
+    def build_name_string
+      self.class.name_template % [
+        identification,
+        name
+      ]
+    end
+
+    def build_flags_string
+      self.class.flags_template % [
+        identification,
+        flags
+      ]
+    end
+
+    def build_info_string
+      self.class.info_template % [
+        identification,
+        info
+      ]
+    end
+
+    def build_base_string
+      self.class.base_template % [
+        identification
+      ]
+    end
+  end
+end

data/lib/object_inspector/inspector.rb

@@ -1,6 +1,7 @@
 module ObjectInspector
-  # ObjectInspector organizes inspection of the associated {#object} via the
-  # passed in options and via a {ObjectInspector::BaseFormatter} instance.
+  # ObjectInspector::Inspector organizes inspection of the associated {#object}
+  # via the passed in options and via a {ObjectInspector::BaseFormatter}
+  # instance.
   #
   # @attr object [Object] the object being inspected
   # @attr scope [Symbol] Object inspection type. For example:
@@ -20,7 +21,7 @@ module ObjectInspector
 
     # The prefix for all methods called on {#object} for inspect
     # details/strings.
-    def self.object_method_prefix
+    def self.object_inspect_method_prefix
       "inspect".freeze
     end
 
@@ -35,11 +36,16 @@ module ObjectInspector
     def initialize(
           object,
           scope: :self,
-          formatter: DefaultFormatter,
+          formatter: TemplatingFormatter,
           **kargs)
       @object = object
       @formatter_klass = formatter
-      @scope = "".respond_to?(:inquiry) ? scope.to_s.inquiry : scope.to_sym
+      @scope =
+        if ObjectInspector.use_string_inquirers?
+          scope.to_s.inquiry
+        else
+          scope.to_sym
+        end
       @kargs = kargs
     end
 
@@ -50,6 +56,19 @@ module ObjectInspector
       formatter.call
     end
 
+    # Generate the inspect String for a wrapped object, if applicable.
+    #
+    # @return [String] if {#object_is_a_wrapper}
+    # @return [NilClass] if not {#object_is_a_wrapper}
+    def wrapped_object_inspection
+      if object_is_a_wrapper?
+        self.class.inspect(
+          extract_wrapped_object,
+          scope: scope,
+          formatter: formatter_klass)
+      end
+    end
+
     # Core object identification details, such as the {#object} class name and
     # any core-level attributes.
     #
@@ -75,10 +94,13 @@ module ObjectInspector
     end
 
     # The generally human-friendly unique identifier for {#object}.
+    #
     # @return [String] if given
     # @return [NilClass] if not given
     def name
-      value(key: :name)
+      value(key: :name) ||
+        interrogate_object(method_name: :display_name,
+                           kargs: object_method_keyword_arguments)
     end
 
   private
@@ -88,33 +110,61 @@ module ObjectInspector
     end
 
     # @return [String] if `key` is found in {#kargs} or if {#object} responds to
-    #   `#{object_method_prefix}_#{key}` (e.g. `inspect_flags`)
+    #   `#{object_inspect_method_prefix}_#{key}` (e.g. `inspect_flags`)
     # @return [NilClass] if not found in {#kargs} or {#object}
     def value(key:)
-      result = kargs.fetch(key) { interrogate_object(key) }
+      return_value =
+        if (passed_in_value = kargs[key])
+          evaluate_passed_in_value(passed_in_value)
+        else
+          interrogate_object_inspect_method(key)
+        end
+
+      return_value.to_s if return_value
+    end
 
-      result.to_s if result
+    # 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
+    def evaluate_passed_in_value(value)
+      if value.is_a?(Symbol)
+        interrogate_object(method_name: value) || value
+      else
+        value
+      end
     end
 
-    # @return [String] if {#object} responds to `#{object_method_prefix}_#{key}`
-    #   (e.g. `inspect_flags`)
+    # Attempt to call `inspect_*` on {#object} based on the passed in `name`.
+    #
+    # @return [String] if {#object} responds to
+    #   `#{object_inspect_method_prefix}_#{name}` (e.g. `inspect_flags`)
     # @return [NilClass] if not found on {#object}
-    def interrogate_object(key)
+    def interrogate_object_inspect_method(name)
+      interrogate_object(
+        method_name: build_inspet_method_name(name),
+        kargs: object_method_keyword_arguments)
+    end
+
+    def interrogate_object(method_name:, kargs: {})
       interrogator =
         ObjectInterrogator.new(
           object: object,
-          method_name: build_method_name(key),
-          kargs: object_method_keyword_arguments)
+          method_name: method_name,
+          kargs: kargs)
 
       interrogator.call
     end
 
-    def build_method_name(key)
-      "#{object_method_prefix}_#{key}"
+    def build_inspet_method_name(name)
+      "#{object_inspect_method_prefix}_#{name}"
     end
 
-    def object_method_prefix
-      self.class.object_method_prefix
+    def object_inspect_method_prefix
+      self.class.object_inspect_method_prefix
     end
 
     def object_method_keyword_arguments
@@ -122,5 +172,14 @@ module ObjectInspector
         scope: scope,
       }
     end
+
+    def extract_wrapped_object
+      object.to_model
+    end
+
+    def object_is_a_wrapper?
+      object.respond_to?(:to_model) &&
+        object.to_model != object
+    end
   end
 end

data/lib/object_inspector/version.rb

@@ -1,3 +1,3 @@
 module ObjectInspector
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/object_inspector.rb

@@ -1,11 +1,21 @@
-require "object_inspector/version"
-
 # ObjectInspector is the base namespace for all modules/classes related to the
 # object_inspector gem.
 module ObjectInspector
-  autoload :Inspector, "object_inspector/inspector"
-  autoload :ObjectInterrogator, "object_inspector/object_interrogator"
-  autoload :BaseFormatter, "object_inspector/base_formatter"
-  autoload :DefaultFormatter, "object_inspector/default_formatter"
-  autoload :InspectorsHelper, "object_inspector/inspectors_helper"
+  @@use_string_inquirers = nil
+
+  def self.use_string_inquirers?
+    if @@use_string_inquirers.nil?
+      @@use_string_inquirers = !!defined?(ActiveSupport::StringInquirer)
+    else
+      @@use_string_inquirers
+    end
+  end
 end
+
+require "object_inspector/version"
+require "object_inspector/inspector"
+require "object_inspector/inspectors_helper"
+require "object_inspector/object_interrogator"
+require "object_inspector/formatters/base_formatter"
+require "object_inspector/formatters/combining_formatter"
+require "object_inspector/formatters/templating_formatter"

data/object_inspector.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["paul.dobbins@icloud.com"]
 
   spec.summary       = %q{ObjectInspector generates uniformly formatted inspect output with customizable amounts of detail.}
-  spec.description   = %q{ObjectInspector takes Object#inspect to the next level. Specify any combination of identification attributes, flags, info, and/or a name along with a self-definable scope option to represent an object in the console, in logging, or otherwise.}
+  spec.description   = %q{ObjectInspector takes Object#inspect to the next level. Specify any combination of identification attributes, flags, info, and/or a name along with an optional self-definable scope option to represent an object in the console, in logging, etc.}
   spec.homepage      = "https://github.com/pdobb/object_inspector"
   spec.license       = "MIT"
 
@@ -37,4 +37,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "byebug", "~> 10.0"
   spec.add_development_dependency "pry", "~> 0.11"
   spec.add_development_dependency "pry-byebug", "~> 3.6"
+  spec.add_development_dependency "benchmark-ips", "~> 2.7"
+  spec.add_development_dependency "minitest-reporters", "~> 1.2"
+  # spec.add_development_dependency "object_identifier", "~> 0.1"  # Add when new version is released
 end

data/scripts/benchmarking/formatters.rb

@@ -0,0 +1,118 @@
+# Play from the console with:
+#   play scripts/benchmarking/formatters.rb
+
+require "ostruct"
+require "benchmark/ips"
+
+custom_formatter_klasses ||= []
+
+formatter_klasses = [
+  ObjectInspector::TemplatingFormatter,
+  ObjectInspector::CombiningFormatter,
+  *Array(custom_formatter_klasses),
+]
+
+INSPECTOR_WITH_FLAGS_AND_INFO_AND_NAME ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    flags: "FLAG1 | FLAG2",
+    info: "INFO",
+    name: "NAME")
+INSPECTOR_WITH_FLAGS_AND_INFO ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    flags: "FLAG1 | FLAG2",
+    info: "INFO")
+INSPECTOR_WITH_FLAGS_AND_NAME ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    flags: "FLAG1 | FLAG2",
+    name: "NAME")
+INSPECTOR_WITH_INFO_AND_NAME ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    info: "INFO",
+    name: "NAME")
+INSPECTOR_WITH_NAME ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    name: "NAME")
+INSPECTOR_WITH_FLAGS ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    flags: "FLAG1 | FLAG2")
+INSPECTOR_WITH_INFO ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    info: "INFO")
+INSPECTOR_WITH_BASE ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION")
+
+
+puts "== Averaged ============================================================="
+Benchmark.ips { |x|
+  formatter_klasses.each do |formatter_klass|
+    x.report(formatter_klass) {
+      formatter_klass.new(INSPECTOR_WITH_FLAGS_AND_INFO_AND_NAME).call
+      formatter_klass.new(INSPECTOR_WITH_FLAGS_AND_INFO).call
+      formatter_klass.new(INSPECTOR_WITH_FLAGS_AND_NAME).call
+      formatter_klass.new(INSPECTOR_WITH_INFO_AND_NAME).call
+      formatter_klass.new(INSPECTOR_WITH_NAME).call
+      formatter_klass.new(INSPECTOR_WITH_FLAGS).call
+      formatter_klass.new(INSPECTOR_WITH_INFO).call
+      formatter_klass.new(INSPECTOR_WITH_BASE).call
+    }
+  end
+
+  x.compare!
+};
+puts "== Done"
+
+
+puts "== Individualized ======================================================="
+Benchmark.ips { |x|
+  formatter_klasses.each do |formatter_klass|
+    x.report("#{formatter_klass} - Flags and Info and Name") {
+      formatter_klass.new(INSPECTOR_WITH_FLAGS_AND_INFO_AND_NAME).call
+    }
+  end
+  formatter_klasses.each do |formatter_klass|
+    x.report("#{formatter_klass} - Flags and Info") {
+      formatter_klass.new(INSPECTOR_WITH_FLAGS_AND_INFO).call
+    }
+  end
+  formatter_klasses.each do |formatter_klass|
+    x.report("#{formatter_klass} - Flags and Name") {
+      formatter_klass.new(INSPECTOR_WITH_FLAGS_AND_NAME).call
+    }
+  end
+  formatter_klasses.each do |formatter_klass|
+    x.report("#{formatter_klass} - Info and Name") {
+      formatter_klass.new(INSPECTOR_WITH_INFO_AND_NAME).call
+    }
+  end
+  formatter_klasses.each do |formatter_klass|
+    x.report("#{formatter_klass} - Name") {
+      formatter_klass.new(INSPECTOR_WITH_NAME).call
+    }
+  end
+  formatter_klasses.each do |formatter_klass|
+    x.report("#{formatter_klass} - Flags") {
+      formatter_klass.new(INSPECTOR_WITH_FLAGS).call
+    }
+  end
+  formatter_klasses.each do |formatter_klass|
+    x.report("#{formatter_klass} - Info") {
+      formatter_klass.new(INSPECTOR_WITH_INFO).call
+    }
+  end
+  formatter_klasses.each do |formatter_klass|
+    x.report("#{formatter_klass} - Base") {
+      formatter_klass.new(INSPECTOR_WITH_BASE).call
+    }
+  end
+
+  x.compare!
+};
+puts "== Done"

data/scripts/benchmarking/object_inspector.rb

@@ -0,0 +1,73 @@
+# Play from the console with:
+#   play scripts/benchmarking/object_inspector.rb
+
+require "ostruct"
+require "benchmark/ips"
+
+inspector_klass = ObjectInspector::Inspector
+
+OBJECT_WITH_FLAGS_AND_INFO_AND_NAME ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    flags: "FLAG1 | FLAG2",
+    info: "INFO",
+    name: "NAME")
+OBJECT_WITH_FLAGS_AND_INFO ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    flags: "FLAG1 | FLAG2",
+    info: "INFO")
+OBJECT_WITH_FLAGS_AND_NAME ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    flags: "FLAG1 | FLAG2",
+    name: "NAME")
+OBJECT_WITH_INFO_AND_NAME ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    info: "INFO",
+    name: "NAME")
+OBJECT_WITH_NAME ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    name: "NAME")
+OBJECT_WITH_FLAGS ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    flags: "FLAG1 | FLAG2")
+OBJECT_WITH_INFO ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION",
+    info: "INFO")
+OBJECT_WITH_BASE ||=
+  OpenStruct.new(
+    identification: "IDENTIFICATION")
+
+
+puts "== Averaged ============================================================="
+Benchmark.ips { |x|
+  x.report(inspector_klass) {
+    inspector_klass.inspect(OBJECT_WITH_FLAGS_AND_INFO_AND_NAME)
+    inspector_klass.inspect(OBJECT_WITH_FLAGS_AND_INFO)
+    inspector_klass.inspect(OBJECT_WITH_FLAGS_AND_NAME)
+    inspector_klass.inspect(OBJECT_WITH_INFO_AND_NAME)
+    inspector_klass.inspect(OBJECT_WITH_NAME)
+    inspector_klass.inspect(OBJECT_WITH_FLAGS)
+    inspector_klass.inspect(OBJECT_WITH_INFO)
+    inspector_klass.inspect(OBJECT_WITH_BASE)
+  }
+
+  x.report("Ruby") {
+    OBJECT_WITH_FLAGS_AND_INFO_AND_NAME.inspect
+    OBJECT_WITH_FLAGS_AND_INFO.inspect
+    OBJECT_WITH_FLAGS_AND_NAME.inspect
+    OBJECT_WITH_INFO_AND_NAME.inspect
+    OBJECT_WITH_NAME.inspect
+    OBJECT_WITH_FLAGS.inspect
+    OBJECT_WITH_INFO.inspect
+    OBJECT_WITH_BASE.inspect
+  }
+
+  x.compare!
+};
+puts "== Done"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: object_inspector
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Paul Dobbins
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-10 00:00:00.000000000 Z
+date: 2018-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -108,9 +108,37 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
 description: ObjectInspector takes Object#inspect to the next level. Specify any combination
-  of identification attributes, flags, info, and/or a name along with a self-definable
-  scope option to represent an object in the console, in logging, or otherwise.
+  of identification attributes, flags, info, and/or a name along with an optional
+  self-definable scope option to represent an object in the console, in logging, etc.
 email:
 - paul.dobbins@icloud.com
 executables: []
@@ -128,13 +156,16 @@ files:
 - bin/console
 - bin/setup
 - lib/object_inspector.rb
-- lib/object_inspector/base_formatter.rb
-- lib/object_inspector/default_formatter.rb
+- lib/object_inspector/formatters/base_formatter.rb
+- lib/object_inspector/formatters/combining_formatter.rb
+- lib/object_inspector/formatters/templating_formatter.rb
 - lib/object_inspector/inspector.rb
 - lib/object_inspector/inspectors_helper.rb
 - lib/object_inspector/object_interrogator.rb
 - lib/object_inspector/version.rb
 - object_inspector.gemspec
+- scripts/benchmarking/formatters.rb
+- scripts/benchmarking/object_inspector.rb
 homepage: https://github.com/pdobb/object_inspector
 licenses:
 - MIT

data/lib/object_inspector/default_formatter.rb

@@ -1,33 +0,0 @@
-module ObjectInspector
-  # ObjectInspector::DefaultFormatter implements
-  # {ObjectInspector::BaseFormatter} to return a standard/default inspect output
-  # format.
-  #
-  # @attr (see BaseFormatter)
-  class DefaultFormatter < BaseFormatter
-    # Perform the formatting routine.
-    #
-    # @return [String]
-    def call
-      "<#{combine_strings}>"
-    end
-
-  private
-
-    def build_identification_string(identification = self.identification)
-      identification.to_s
-    end
-
-    def build_flags_string(flags = self.flags)
-      "[#{flags.to_s.upcase}]" if flags
-    end
-
-    def build_info_string(info = self.info)
-      " (#{info})" if info
-    end
-
-    def build_name_string(name = self.name)
-      " :: #{name}" if name
-    end
-  end
-end