inspectable 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d68dedc3064ef8392cffa6200fa2f02c4ac228eb0665d7599fdf1a889d2e23bc
-  data.tar.gz: be155e34876e51bd71b6383300725d2e53b83b2c8d6e1abc5d034931e88c58c2
+  metadata.gz: f4a4c3c388c5294c596d5fa7a6a4bf4959ce29cbfae40563fcd4d3e3464d800e
+  data.tar.gz: 15475b71448155390f1ca1f374daea21d9efaed0ea8b27b763eea97fdcd35cf3
 SHA512:
-  metadata.gz: f1db3e293fa9b157135c0b09fe7ca17bf140340a0c8cdb32b75dd63771ddce1bd82c6a6fed336a4f8d67d568fb9b9c4393b16bc6a74572b8d0309882dd070d71
-  data.tar.gz: 31bf8b9a6030025c2140949b8a2aef9848bb5893abac4e98359723c97ea3d473894f3b3be11a954bbb299dafb78c3a1e10c095b6c2ba245fa6a7149f1feddefa
+  metadata.gz: 69c70eb5c696419513d64b18008a1880318e0b1fb31f42d27282a380d8ba6ae9119f5f3a8adc2ebcf4ee5c8256638d3bc1297bc313362054be7e2fc0bd9b0f6a
+  data.tar.gz: d6ebb06b52f577f2e2acc85c054d8b918aa5cd0dfdccf8f47ce051afcead6fbea2f7d0159462b1f439fad7d06628ffd3839d8ef0482843f462821bc454bdcd89

data/README.adoc

@@ -4,6 +4,7 @@
 
 :dry_schema_link: link:https://dry-rb.org/gems/dry-schema[Dry Schema]
 :object_inspection_link: link:https://alchemists.io/articles/ruby_object_inspection[Ruby Object Inspection]
+:rspec_link: link:https://rspec.info[RSpec]
 
 = Inspectable
 
@@ -13,9 +14,9 @@ toc::[]
 
 == Features
 
-- Allows you to customize and configure `Object#inspect` with minimal effort.
-- Allows you to exclude instance variables that are too verbose or undesired.
-- Allows you to register reusable transformers for more advanced behavior.
+* Allows you to customize and configure `Object#inspect` with minimal effort.
+* Allows you to exclude instance variables that are too verbose or undesired.
+* Allows you to register reusable transformers for more advanced behavior.
 
 == Requirements
 
@@ -125,46 +126,47 @@ Demo.new.inspect
 
 === Transformers
 
-This gem includes a few basic transformers that can help you hide sensitive information or reduce verbosity. To view them, use:
+This gem includes a few built-in transformers that can help you hide sensitive information or reduce verbosity. To view them, use:
 
 [source,ruby]
 ----
 Inspectable.transformers
+
 # {
-#   class: #<Proc:0x000000010e09dc10 inspectable/transformers/classifier.rb:6 (lambda)>,
-#   redact: #<Proc:0x000000010e09cf40 inspectable/transformers/redactor.rb:6 (lambda)>
+#   redact: Inspectable::Transformers::Redactor,
+#     type: Inspectable::Transformers::Typer
 # }
 ----
 
 Each is explained below.
 
-==== Classifier
-
-This is a simple transformer that always asks for the class of the instance variable's value.
+==== Redactor
 
-This transformer is most helpful for objects, like {dry_schema_link}, that are extremely verbose. With this transformer, you can see the type of schema without all of the additional details. This transformer is also handy when you only want type information in general.
+This transformer's sole purpose is to hide sensitive information and is most helpful for obscuring credentials, passwords, and secrets in general. When your instance variable's value is not `nil`, you'll see `"[REDACTED]"` as the value. Otherwise, if your instance variable's value is `nil`, you'll see `nil` instead.
 
 To use, supply the instance variable you want to transform as the key and the transformer's key (symbol) as the value. Example:
 
 [source,ruby]
 ----
-include Inspectable[demo: :class]
+include Inspectable[demo: :redact]
 ----
 
-==== Redactor
+==== Typer
 
-This transformer's sole purpose is to hide sensitive information and is most helpful for obscuring credentials, passwords, and secrets in general. When your instance variable's value is not `nil`, you'll see `"[REDACTED]"` as the value. Otherwise, if your instance variable's value is `nil`, you'll see `nil` instead.
+This transformer always computes the instance variable's type.
+
+This transformer is most helpful for objects, like {dry_schema_link}, that are extremely verbose. With this transformer, you can see the type of schema without all of the additional details. This transformer is also handy when you only want type information in general.
 
 To use, supply the instance variable you want to transform as the key and the transformer's key (symbol) as the value. Example:
 
 [source,ruby]
 ----
-include Inspectable[demo: :redact]
+include Inspectable[demo: :type]
 ----
 
 ==== Overrides
 
-Should you not like default transformer behavior, you can override an existing transformer with your own. For example, maybe you'd like the `Redactor` transform to use `"[FILTERED]"` instead of `"[REDACTED]"`. Here's how you do that:
+Should you not like default transformer behavior, you can override an existing transformer with your own. For example, maybe you'd like the `Redactor` transformer to use `"[FILTERED]"` instead of `"[REDACTED]"`. Here's how you do that:
 
 [source,ruby]
 ----
@@ -175,7 +177,7 @@ The above will override default behavior with your own functionality.
 
 ==== Custom
 
-You can add as many transformers as you like by using the `.add_transformer` method. Several examples have been presented already but here are the guidelines for customization:
+You can add as many transformers as you like by using the `.add_transformer` method. Here are the guidelines for customization:
 
 * Use only a string or symbol for the first argument (a symbol is preferred). This allows you to quickly identify and use your transformer when applying custom inspection behavior to your objects.
 * Use a lambda for the second argument. The lambda must accept a value as the first positional parameter. How you transform the value is up to you but you'll want to adhere to default {object_inspection_link} behavior.
@@ -191,6 +193,96 @@ The above would strip hexes from the output. Notice the guard to check if the `v
 
 ℹ️ In most cases, you _must_ send the `#inspect` message to the transformed value. In situations, where you are dealing with a constant, you'll want to avoid sending the `#inspect` message because constants shouldn't be quoted. All of this is important when adhering to default {object_inspection_link} behavior.
 
+=== Native
+
+As of Ruby 4.0.0, limited native support is provided via the _private_ `instance_variables_to_inspect` instance method. This method is not compatible with this gem because this gem makes `instance_variables_to_inspect` redundant and will fail with a `NoMethodError` exception. Example:
+
+[source,ruby]
+----
+Class.new do
+  include Inspectable(:name)
+
+  def initialize name = "test"
+    @name = name
+  end
+
+  private
+
+  def instance_variables_to_inspect = [:@name]
+end
+
+# undefined method 'Inspectable' for class (NoMethodError)
+----
+
+To resolve the above exception, remove `instance_variables_to_inspect` and let this gem handle everything for you.
+
+=== RSpec
+
+To aid in your testing, you can use the `match_inspection` RSpec matcher by requiring it in your spec helper:
+
+[source,ruby]
+----
+# spec_helper.rb
+
+require "inspectable/rspec/matchers/match_inspection"
+----
+
+Once required, you can use the matcher by supplying the expected attributes as follows:
+
+[source,ruby]
+----
+RSpec.describe Demo do
+  subject(:demo) { described_class.new }
+
+  describe "#inspect" do
+    it "has inspected attributes" do
+      expect(demo.inspect).to match_inspection(label: "Demo", name: :demo)
+    end
+  end
+end
+----
+
+You can also customize the matcher by providing a `by` hash _before_ any expected attributes consisting of the following attributes:
+
+* `prefix`: The prefix of your attribute names. Default: `"@"`.
+* `delimiter`: The delimiter between each attribute name and value. Default: `"="`.
+* `separator`: The separator between each attribute. Default: `", "`.
+
+For example, the following is an explicit demonstration of what the matcher implicitly provides for you by default:
+
+[source,ruby]
+----
+RSpec.describe Demo do
+  subject(:demo) { described_class.new }
+
+  describe "#inspect" do
+    it "has inspected attributes" do
+      expect(demo.inspect).to match_inspection(
+        by: {prefix: "@", delimiter: "=", separator: ", "},
+        label: "Demo",
+        name: :demo
+      )
+    end
+  end
+end
+----
+
+In situations where the spec fails, you’ll get a formatted error to help you quickly resolve and fix the issue:
+
+----
+expected (using prefix: "@", delimiter: "=", and separator: ", "):
+
+"#<Demo:0x00000000000014d0
+@label="Demo",
+@name=:demo
+@email="demo@demo.io"
+
+to match:
+
+@label="Demo",
+@name=:demo
+----
+
 == Development
 
 To contribute, run:

data/inspectable.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "inspectable"
-  spec.version = "0.6.0"
+  spec.version = "1.0.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/inspectable"
@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.signing_key = Gem.default_key_path
   spec.cert_chain = [Gem.default_cert_path]
 
-  spec.required_ruby_version = ">= 3.4"
+  spec.required_ruby_version = ">= 4.0"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
   spec.files = Dir["*.gemspec", "lib/**/*"]

data/lib/inspectable/builder.rb

@@ -15,6 +15,12 @@ module Inspectable
     end
 
     def included descendant
+      descendant.define_singleton_method :method_added do |name|
+        return super(name) unless name == :instance_variables_to_inspect
+
+        fail NoMethodError, "Defining method :instance_variables_to_inspect is disabled."
+      end
+
       case descendant
         when Class, Struct, Data then super
         else fail TypeError, "Use Class, Struct, or Data."
@@ -59,7 +65,7 @@ module Inspectable
 
     def render instance, type
       container.fetch(type) { fail TypeError, "Unknown type. Use Class, Struct, or Data." }
-               .then { |serializer| serializer.call(instance, *excludes, **transformers) }
+               .then { |sanitizer| sanitizer.call(instance, *excludes, **transformers) }
     end
   end
 end

data/lib/inspectable/registry.rb

@@ -4,8 +4,8 @@ module Inspectable
   # Provides global regsitry for further customization.
   module Registry
     def self.extended descendant
-      descendant.add_transformer(:class, Inspectable::Transformers::Classifier)
-                .add_transformer :redact, Inspectable::Transformers::Redactor
+      descendant.add_transformer(:redact, Inspectable::Transformers::Redactor)
+                .add_transformer(:type, Inspectable::Transformers::Typer)
     end
 
     def add_transformer key, function

data/lib/inspectable/rspec/matchers/match_inspection.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :match_inspection do |by: {}, **|
+  match do |actual|
+    defaults = {prefix: "@", delimiter: "=", separator: ", "}
+    @prefix, @delimiter, @separator = defaults.merge!(by).values_at(*defaults.keys)
+    @content = expected.map { |key, value| "#{@prefix}#{key}#{@delimiter}#{value}" }
+                       .join @separator
+
+    actual.match?(/#{@content}/)
+  end
+
+  failure_message do |actual|
+    using = "using prefix: #{@prefix.inspect}, " \
+            "delimiter: #{@delimiter.inspect}, and " \
+            "separator: #{@separator.inspect}"
+
+    <<~MESSAGE
+      expected (#{using}):
+
+      #{actual.inspect.gsub @separator, "#{@separator}\n"}
+
+      to match:
+
+      #{@content.gsub @separator, "#{@separator}\n"}
+    MESSAGE
+  end
+end

data/lib/inspectable/sanitizers/{dater.rb → data.rb}

@@ -3,7 +3,7 @@
 module Inspectable
   module Sanitizers
     # Excludes and transforms data members.
-    class Dater
+    class Data
       def initialize pattern: "#<data%<class>s %<body>s>", inspector: INSPECTOR
         @pattern = pattern
         @inspector = inspector
@@ -23,7 +23,11 @@ module Inspectable
       def exclude_and_transform instance, excludes, transformers
         (instance.members - excludes).reduce(+"") do |body, member|
           value = instance.public_send member
-          body << "#{member}=#{transformers.fetch(member, inspector).call value}, "
+          transformer = transformers.fetch member, inspector
+
+          fail ArgumentError, "Invalid transformer registered for: #{member}." unless transformer
+
+          body << "#{member}=#{transformer.call value}, "
         end
       end
     end

data/lib/inspectable/sanitizers/{structer.rb → struct.rb}

@@ -3,7 +3,7 @@
 module Inspectable
   module Sanitizers
     # Excludes and transforms struct members.
-    class Structer
+    class Struct
       def initialize pattern: "#<struct%<class>s %<body>s>", inspector: Inspectable::INSPECTOR
         @pattern = pattern
         @inspector = inspector
@@ -22,7 +22,11 @@ module Inspectable
 
       def exclude_and_transform instance, excludes, transformers
         (instance.members - excludes).reduce(+"") do |body, member|
-          body << "#{member}=#{transformers.fetch(member, inspector).call instance[member]}, "
+          transformer = transformers.fetch member, inspector
+
+          fail ArgumentError, "Invalid transformer registered for: #{member}." unless transformer
+
+          body << "#{member}=#{transformer.call instance[member]}, "
         end
       end
     end

data/lib/inspectable/sanitizers/{classer.rb → type.rb}

@@ -2,8 +2,8 @@
 
 module Inspectable
   module Sanitizers
-    # Excludes and transforms class instance variables.
-    class Classer
+    # Excludes and transforms object types.
+    class Type
       def initialize pattern: "#<%<class>s:%<id>#018x %<body>s>", inspector: INSPECTOR
         @pattern = pattern
         @inspector = inspector
@@ -26,9 +26,11 @@ module Inspectable
       def exclude_and_transform instance, variables, transformers
         variables.reduce(+"") do |body, variable|
           key = variable.to_s.delete_prefix("@").to_sym
-          value = instance.instance_variable_get variable
+          transformer = transformers.fetch key, inspector
 
-          body << "#{variable}=#{transformers.fetch(key, inspector).call value}, "
+          fail ArgumentError, "Invalid transformer registered for: #{key}." unless transformer
+
+          body << "#{variable}=#{transformer.call instance.instance_variable_get(variable)}, "
         end
       end
     end

data/lib/inspectable/transformers/redactor.rb

@@ -3,6 +3,10 @@
 module Inspectable
   module Transformers
     # Redacts sensitive information.
-    Redactor = -> value { "[REDACTED]".inspect if value }
+    module Redactor
+      module_function
+
+      def call(value) = ("[REDACTED]".inspect if value)
+    end
   end
 end

data/lib/inspectable/transformers/typer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Inspectable
+  module Transformers
+    # Answers object's type.
+    module Typer
+      module_function
+
+      def call(value) = value.class.name
+    end
+  end
+end

data/lib/inspectable.rb

@@ -2,11 +2,11 @@
 
 require "inspectable/builder"
 require "inspectable/registry"
-require "inspectable/sanitizers/classer"
-require "inspectable/sanitizers/dater"
-require "inspectable/sanitizers/structer"
-require "inspectable/transformers/classifier"
+require "inspectable/sanitizers/data"
+require "inspectable/sanitizers/struct"
+require "inspectable/sanitizers/type"
 require "inspectable/transformers/redactor"
+require "inspectable/transformers/typer"
 
 # Main namespace.
 module Inspectable
@@ -16,9 +16,9 @@ module Inspectable
 
   CONTAINER = {
     registry: self,
-    class: Sanitizers::Classer.new,
-    data: Sanitizers::Dater.new,
-    struct: Sanitizers::Structer.new
+    class: Sanitizers::Type.new,
+    data: Sanitizers::Data.new,
+    struct: Sanitizers::Struct.new
   }.freeze
 
   def self.[](*, **) = Builder.new(*, **)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inspectable
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -49,11 +49,12 @@ files:
 - lib/inspectable.rb
 - lib/inspectable/builder.rb
 - lib/inspectable/registry.rb
-- lib/inspectable/sanitizers/classer.rb
-- lib/inspectable/sanitizers/dater.rb
-- lib/inspectable/sanitizers/structer.rb
-- lib/inspectable/transformers/classifier.rb
+- lib/inspectable/rspec/matchers/match_inspection.rb
+- lib/inspectable/sanitizers/data.rb
+- lib/inspectable/sanitizers/struct.rb
+- lib/inspectable/sanitizers/type.rb
 - lib/inspectable/transformers/redactor.rb
+- lib/inspectable/transformers/typer.rb
 homepage: https://alchemists.io/projects/inspectable
 licenses:
 - Hippocratic-2.1
@@ -72,14 +73,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A customizable object inspector.
 test_files: []

data/lib/inspectable/transformers/classifier.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module Inspectable
-  module Transformers
-    # Answers value's class.
-    Classifier = -> value { value.class.name }
-  end
-end