inspectable 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f839f2848c735ffa79fdb9a4cd6200f2965715a02ada73150d21c928af88b69
-  data.tar.gz: 39f6d038705e0fa23d8c7bf5f919b30a739c908aa87258491249ce9d629fe7ab
+  metadata.gz: d50d892f3952f220f43f2d9fc8bcd6392858b8a9e0ceca693130ca22e0565237
+  data.tar.gz: 310797e4d5718b4a163a4aef1663b0b8a1bd0e6e3600eeef79f5f5a6e2394f6f
 SHA512:
-  metadata.gz: 9d70a034f1cb6c1b81ff71d4d97878fb11e8a46a1491dab16636355af12344c17776c5d638c62f2c33ada6f135fd468759e0a3135330645b29dc0841c36fd36a
-  data.tar.gz: 2f02e2922f22ac16a1db43952c7c6b049999cbbc7b1bc6e6c5821f61d643e2f210fa0b24379150d27a80ceefd974e7872dd18af29538461712f21446db984eaa
+  metadata.gz: 7970ff2fdcdd799dc27b5ddaa2d60c4b5448446dc12895d755aa36541e412100ba4213bb931d959ddf913291b31c9c0da2e039220502fc547763dbd96ea8c010
+  data.tar.gz: 7f22626efddf742879582386d0732026865377ee2ecf3ef91b2703f52afe8bb88cd1d8c54ba1640c5a2295cc668909157022918dc5ef856583c858d13511d151

data/README.adoc

@@ -7,7 +7,7 @@
 
 = Inspectable
 
-A customizable object inspector which enhances {object_inspection_link} behavior beyond what is provided by default. You can always implement your own `#inspect` method but this becomes tedious when you need to exclude or transform the same instance variables across multiple objects.
+Inspectable is a customizable object inspector which enhances {object_inspection_link} behavior beyond what is provided by default. You can always implement your own `#inspect` method but this becomes tedious when you need to exclude or transform the same instance variables across multiple objects.
 
 toc::[]
 
@@ -56,7 +56,7 @@ require "inspectable"
 
 == Usage
 
-By default, `Object#inspect` is designed to include all instance variables so this gem is designed to exclude what you don't need. Otherwise, you don't need this gem at all. Take the following, for example:
+By default, `Object#inspect` includes all instance variables so this gem is designed to exclude what you don't need or transform variables before being inspected. Otherwise, you don't need this gem at all. Take the following, for example:
 
 [source,ruby]
 ----
@@ -136,7 +136,7 @@ Inspectable.transformers
 # }
 ----
 
-Continue reading to learn how each of these work and how you can provide your own transformers.
+Each is explained below.
 
 ==== Classifier
 
@@ -153,7 +153,7 @@ include Inspectable[demo: :class]
 
 ==== Redactor
 
-This transformer's sole purpose is to hide sensitive information. This 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'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:
 
@@ -178,18 +178,18 @@ The above will override default behavior with your own functionality.
 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:
 
 * 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.
+* 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.
 
-Let's say you don't like hex digests showing up when inspecting object, you could register a custom transformer for this:
+Let's say you need to remove hex values from showing up when inspecting a variable value, you could register a custom transformer for this:
 
 [source,ruby]
 ----
-Inspectable.add_transformer :dehexer, -> value { value.sub(/\h+/, "") if value }
+Inspectable.add_transformer :dehexer, -> value { value.sub(/\h+/, "").inspect if value }
 ----
 
 The above would strip hexes from the output. Notice the guard to check if the `value` exists before performing the transformation. This is good to have when your value might be `nil` so you don't have exceptions.
 
-ℹ️ Please note that the value of all transformers will always be sent the `#inspect` message as found with default {object_inspection_link} behavior. This means you don't have to worry about doing this yourself when building custom transformers.
+ℹ️ 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.
 
 == Development
 

data/inspectable.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "inspectable"
-  spec.version = "0.2.0"
+  spec.version = "0.3.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/inspectable"

data/lib/inspectable/builder.rb

@@ -3,59 +3,63 @@
 module Inspectable
   # Provides custom object inspection behavior.
   class Builder < Module
-    def initialize *excludes, registry: Inspectable, **transformers
+    def initialize *excludes, container: CONTAINER, **transformers
       super()
-      @excludes = excludes.map { :"@#{it}" }
-      @transformers = resolve transformers, registry
+      @excludes = excludes
+      @container = container
+      @transformers = resolve transformers
 
       validate
       define_inspect
       freeze
     end
 
-    private
-
-    attr_reader :excludes, :transformers
+    def included descendant
+      case descendant
+        when Class, Struct, Data then super
+        else fail TypeError, "Use Class, Struct, or Data."
+      end
+    end
 
-    def validate
-      return unless excludes.empty? && transformers.empty?
+    private
 
-      fail ArgumentError, "Excludes or transformers are required."
-    end
+    attr_reader :excludes, :container, :transformers
 
-    def define_inspect body_builder: method(:build_body)
-      define_method :inspect do
-        format %(#<%<class>s:%<id>#018x #{body_builder.call(self).chomp ", "}>),
-               class: self.class,
-               id: object_id << 1
+    def resolve transformers
+      transformers.each.with_object({}) do |(variable, object), collection|
+        collection[variable] = acquire object
       end
     end
 
-    def build_body instance
-      exclude_and_transform(instance).reduce(+"") do |body, (variable, value)|
-        body << "#{variable}=#{value}, "
+    def acquire object
+      case object
+        when Proc then object
+        when Symbol then container.fetch(:registry).transformers[object]
+        else fail TypeError, "Invalid transformer: #{object.inspect}. Use Proc or Symbol."
       end
     end
 
-    def exclude_and_transform instance
-      (instance.instance_variables - excludes).each.with_object({}) do |variable, attributes|
-        value = instance.instance_variable_get variable
-        transform = transformers[variable].call(value) if transformers.key? variable
+    def validate
+      return unless excludes.empty? && transformers.empty?
 
-        attributes[variable] = (transform || value).inspect
-      end
+      fail ArgumentError, "Excludes or transformers are required."
     end
 
-    def resolve transformers, registry
-      transformers.each.with_object({}) do |(key, object), collection|
-        value = case object
-                  when Proc then object
-                  when Symbol then registry.transformers[object]
-                  else fail TypeError, "Invalid transformer: #{object.inspect}. Use Proc or Symbol."
-                end
+    def define_inspect renderer: method(:render)
+      define_method :inspect do
+        klass = self.class
 
-        collection[:"@#{key}"] = value
+        if klass < Struct then renderer.call self, :struct
+        elsif klass < Data then renderer.call self, :data
+        elsif klass.is_a? Class then renderer.call self, :class
+        else renderer.call self, :unknown
+        end
       end
     end
+
+    def render instance, type
+      container.fetch(type) { fail TypeError, "Unknown type. Use Class, Struct, or Data." }
+               .then { |serializer| serializer.call(instance, *excludes, **transformers) }
+    end
   end
 end

data/lib/inspectable/sanitizers/classer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Inspectable
+  module Sanitizers
+    # Excludes and transforms class instance variables.
+    class Classer
+      def initialize pattern: "#<%<class>s:%<id>#018x %<body>s>", inspector: INSPECTOR
+        @pattern = pattern
+        @inspector = inspector
+        freeze
+      end
+
+      def call instance, *excludes, **transformers
+        variables = instance.instance_variables - excludes.map { :"@#{it}" }
+
+        format pattern,
+               class: instance.class,
+               id: object_id << 1,
+               body: exclude_and_transform(instance, variables, transformers).chomp(", ")
+      end
+
+      private
+
+      attr_reader :pattern, :inspector
+
+      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
+
+          body << "#{variable}=#{transformers.fetch(key, inspector).call value}, "
+        end
+      end
+    end
+  end
+end

data/lib/inspectable/sanitizers/dater.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Inspectable
+  module Sanitizers
+    # Excludes and transforms data members.
+    class Dater
+      def initialize pattern: "#<data%<class>s %<body>s>", inspector: INSPECTOR
+        @pattern = pattern
+        @inspector = inspector
+        freeze
+      end
+
+      def call instance, *excludes, **transformers
+        format pattern,
+               class: instance.class.name.then { " #{it}" if it },
+               body: exclude_and_transform(instance, excludes, transformers).chomp(", ")
+      end
+
+      private
+
+      attr_reader :pattern, :inspector
+
+      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}, "
+        end
+      end
+    end
+  end
+end

data/lib/inspectable/sanitizers/structer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Inspectable
+  module Sanitizers
+    # Excludes and transforms struct members.
+    class Structer
+      def initialize pattern: "#<struct%<class>s %<body>s>", inspector: Inspectable::INSPECTOR
+        @pattern = pattern
+        @inspector = inspector
+        freeze
+      end
+
+      def call instance, *excludes, **transformers
+        format pattern,
+               class: instance.class.name.then { " #{it}" if it },
+               body: exclude_and_transform(instance, excludes, transformers).chomp(", ")
+      end
+
+      private
+
+      attr_reader :pattern, :inspector
+
+      def exclude_and_transform instance, excludes, transformers
+        (instance.members - excludes).reduce(+"") do |body, member|
+          body << "#{member}=#{transformers.fetch(member, inspector).call instance[member]}, "
+        end
+      end
+    end
+  end
+end

data/lib/inspectable/transformers/redactor.rb

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

data/lib/inspectable.rb

@@ -2,6 +2,9 @@
 
 require "inspectable/builder"
 require "inspectable/registry"
+require "inspectable/sanitizers/classer"
+require "inspectable/sanitizers/dater"
+require "inspectable/sanitizers/structer"
 require "inspectable/transformers/classifier"
 require "inspectable/transformers/redactor"
 
@@ -9,5 +12,14 @@ require "inspectable/transformers/redactor"
 module Inspectable
   extend Registry
 
+  INSPECTOR = -> value { value.inspect }
+
+  CONTAINER = {
+    registry: self,
+    class: Sanitizers::Classer.new,
+    data: Sanitizers::Dater.new,
+    struct: Sanitizers::Structer.new
+  }.freeze
+
   def self.[](*, **) = Builder.new(*, **)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inspectable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -49,6 +49,9 @@ 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/transformers/redactor.rb
 homepage: https://alchemists.io/projects/inspectable
@@ -76,7 +79,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A customizable object inspector.
 test_files: []