feature_envy 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7675c689bf69e95854627b7dc5e28affa5a2fed1bcb46f8255a80217c6abdea
-  data.tar.gz: 17a050ab57c4af67a4c967756b4704220e8511940498cb5f66c9989b6ecb2225
+  metadata.gz: a14b68770c0137db65d3846d607afa7c355f994d3f5716dc8f9f97b092c63cc4
+  data.tar.gz: f8c7eca5be96c55987540c741f19d2161e8d758ce3a22de98e7fc5603ca3d0ba
 SHA512:
-  metadata.gz: 073e92360b8fbcaa1b6ce67a68f37adfdc4282c69bc15be4cc1e4119a99671958c175597309169a9e122008371a70814dd3e0836250185bad95374a241b6dbd5
-  data.tar.gz: 2f3e21f91d1be99f5e00251568c87cb62131e8666af9c2a2d9685d42832d20cefb36a1f8ba87705c8b4f0a4fc3ddad10177c6caf473dcd6001156e2113f07804
+  metadata.gz: 2c2f7efc87d84526283e4558102ef8355455efa9597fbf83d9874a1adc177cbaddbd8167c87a50836778b2312d94dda1328c85eae06d91cb395d0eb4c6cc6228
+  data.tar.gz: 0c338372e47dba9ee7e4177f619a6de77cc8515c0daaea0976634a315564b5bfe34250a51ada1d55c126902c819d10ee8704cdf0d358fd50921860a905917ad7

data/README.md

@@ -10,6 +10,7 @@ Supported features:
 - Final classes
 - Thread-safe lazy accessors
 - Object literals
+- Inspect (inspired by Elixir's `Kernel.inspect/2`)
 
 ## Installation
 
@@ -24,9 +25,75 @@ Don't forget to run `bundle install` afterwards.
 
 ## Usage
 
-Features are independent from each other and can be enabled one-by-one when
-needed. Please refer to individual feature documentation to understand how to
-enabled them.
+Below are example snippets for a quick start with the project. Please refer to
+individual feature documentation for details. Features are designed to be
+independent and should be enabled one-by-one.
+
+### Final Classes
+
+```ruby
+module Models
+  # Enable the feature in a given module via the using directive.
+  using FeatureEnvy::FinalClass
+
+  class Admin < User
+    # Call final! inside the definition of a class you want to mark final.
+    final!
+  end
+end
+```
+
+### Lazy Accessors
+
+```ruby
+class User
+  # Enable the feature in a given class via the using directive. Alternatively,
+  # you can enable it in a higher-level module, so that all classes defined in
+  # support lazy accessors.
+  using FeatureEnvy::LazyAccessor
+
+  # These are some attributes that will be used by the lazy accessor.
+  attr_accessor :first_name, :last_name
+
+  # full_name is computed in a thread-safe fashion, and is lazy, i.e. it's
+  # computed on first access and then cached.
+  lazy(:full_name) { "#{first_name}" "#{last_name}" }
+end
+```
+
+### Object Literals
+
+```ruby
+# Object literals are inspired by JavaScript and enable inline object definition
+# that mixes both attributes and methods. Consider the example below:
+app = object do
+  @database = create_database_connection
+  @router   = create_router
+
+  def start
+    @database.connect
+    @router.start
+  end
+end
+
+# app has @database and @router as attributes and responds to #start.
+app.start
+```
+
+### Inspect
+
+```ruby
+# Elixir-style inspect for debugging during development and testing. First,
+# make #inspect! available on all objects.
+class BasicObject
+  include FeatureEnvy::Inspect
+end
+
+# Second, configure how objects are inspected and where the results are sent.
+# In this case, we just call the regular #inspect and send results to stderr.
+FeatureEnvy::Inspect.inspector = FeatureEnvy::Inspect::InspectInspector
+FeatureEnvy::Inspect.output = $stderr
+```
 
 ## Author
 

data/lib/feature_envy/final_method.rb

@@ -0,0 +1,10 @@
+module FeatureEnvy
+  module FinalMethod
+    refine Module do
+      def final *method_names
+        method_names.each do |method_name|
+        end
+      end
+    end
+  end
+end

data/lib/feature_envy/inspect.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module FeatureEnvy
+  # Inspect method.
+  #
+  # ### Definition
+  #
+  # The inspect method is a helper method, inspired by `inspect/2` in Elixir,
+  # aimed at making print debugging easier with minimal disruption to
+  # surrounding code.
+  #
+  # ### Applications
+  #
+  # Quick inspection of intermediate values during development; **not intended
+  # for use in production**.
+  #
+  # ### Usage
+  #
+  # 1. Proceed with the remaining steps **only in non-production** environments.
+  # 2. Set an inspector by calling {FeatureEnvy::Inspect.inspector=}.
+  #    This is a method taking the object being inspected at as the argument and
+  #    returning its string representation. You can use the built-in
+  #    {InspectInspector} as the starting point.
+  # 3. Set an output by calling {FeatureEnvy::Inspect.output=}. This is an object
+  #    implementing `#puts` that will be called with the inspector result, so
+  #    IO objects like `$stdout` and `$stderr` can be used.
+  # 4. Call {inspect} on objects you want to inspect at.
+  #
+  # A custom inspector and output can be provided. The examples below have
+  # templates that can be used as starting points in development. There's also
+  # an example showing how to enable the module in a Rails app.
+  #
+  # ### Discussion
+  #
+  # Elixir makes it easy to print objects of interest, including intermediate
+  # ones, by passing them through `Kernel.inspect/2`. This function prints the
+  # object's representation and returns the object itself, so that it can be
+  # called on intermediate results without disrupting the remaining
+  # instructions.
+  #
+  # For example, the instruction below instantiates `Language`, prints its
+  # representation, and then passes that language to `Language.create!/1`:
+  #
+  # ```elixir
+  # %Language{name: "Ruby"} |>
+  #   inspect() |>
+  #   Language.create!()
+  # ```
+  #
+  # {FeatureEnvy::Inspect} is a Ruby counterpart of Elixir's `inspect/2`.
+  # `#inspect!` was chosen since `#inspect` is already defined by Ruby and the
+  # `!` suffix indicates a "dangerous" method.
+  #
+  # The syntax `object.inspect!` was chosen over `inspect!(object)` as it's
+  # easier to insert in the middle of complicated method calls by requiring less
+  # modifications to the surrounding code. The difference is best illustrated
+  # in the following example:
+  #
+  # ```ruby
+  # # If we start with ...
+  # User.create!(user_attributes(request))
+  #
+  # # ... then it's easier to do to this ...
+  # User.create!(user_attributes(request).inspect)
+  #
+  # # ... than this:
+  # User.create!(inspect(user_attributes(request)))
+  # ```
+  #
+  # ### Implementation Notes
+  #
+  # 1. Refinement-based activation would require the developer to add
+  #    `using FeatureEnvy::Inspect` before calling `inspect!`, which would be
+  #    extremely inconvenient. Since the feature is intended for non-production
+  #    use only monkey-patching is the only way to activate it.
+  #
+  # @example Enabling Inspect in a Rails app
+  #   # Inspect should be activated only in non-production environments.
+  #   unless Rails.env.production?
+  #     # To make the method available on all objects, BasicObject must be
+  #     # reopened and patched.
+  #     class BasicObject
+  #       include FeatureEnvy::Inspect
+  #     end
+  #
+  #     # Setting a inspector is required. Below, we're using a built-in inspector
+  #     # that calls #inspect on the object being inspected at.
+  #     FeatureEnvy::Inspect.inspector = FeatureEnvy::Inspect::InspectInspector
+  #
+  #     # Results should be printed to stderr.
+  #     FeatureEnvy::Inspect.output = $stderr
+  #   end
+  #
+  # @example Inspector and output class templates
+  #   class CustomInspector
+  #     def call(object)
+  #       # object is the object on which inspect! was called. The method should
+  #       # return the string that should be passed to the output.
+  #     end
+  #   end
+  #
+  #   class CustomOutput
+  #     def puts(string)
+  #       # string is the return value of #call sent to FeatureEnvy::Inspect.inspector.
+  #       # The output object is responsible for showing this string to the
+  #       # developer.
+  #     end
+  #   end
+  #
+  # @example Sending output to a logger
+  #   # Assuming logger is an instance of the built-in Logger class, an adapter
+  #   # is needed to make it output inspection results.
+  #   FeatureEnvy::Inspect.output = FeatureEnvy::Inspect::LoggerAdapter.new logger
+  module Inspect
+    # A base class for errors related to the inspect method.
+    class Error < FeatureEnvy::Error; end
+
+    # An error raised when {#inspect!} is called but no inspector has been set.
+    class NoInspectorError < Error
+      # @!visibility private
+      def initialize
+        super(<<~ERROR)
+          No inspector has been set. Ensure that FeatureEnvy::Inspect.inspector is set
+          to an object responding to #call(object) somewhere early during
+          initialization.
+        ERROR
+      end
+    end
+
+    # An error raised when {#inspect!} is called but no output has been set.
+    class NoOutputError < Error
+      # @!visibility private
+      def initialize
+        super(<<~ERROR)
+          No output has been set. Ensure that FeatureEnvy::Inspect.output is set
+          to an object responding to #puts(string) somewhere early during
+          initialization.
+        ERROR
+      end
+    end
+
+    # Inspect the object and return it.
+    #
+    # The method inspects the object by:
+    #
+    #   1. Passing the object to `#inspect` defined on {.inspector}, producing a
+    #      string representation of the object.
+    #   2. Passing that string to `#puts` defined on {.output}.
+    #
+    # @return [self] The object on which {#inspect!} was called.
+    def inspect!
+      if FeatureEnvy::Inspect.inspector.nil?
+        raise NoInspectorError.new
+      end
+      if FeatureEnvy::Inspect.output.nil?
+        raise NoOutputError.new
+      end
+
+      result = FeatureEnvy::Inspect.inspector.call self
+      FeatureEnvy::Inspect.output.puts result
+
+      self
+    end
+
+    class << self
+      # The inspector converting objects to string representations.
+      #
+      # The inspector **must** respond to `#call` with the object being
+      # inspected as the only argument, and **must** return a string, that will
+      # then be sent to {FeatureEnvy::Inspect.output}.
+      #
+      # @return [#call] The inspector currently in use.
+      attr_accessor :inspector
+
+      # The output object sending inspection results to the developer.
+      #
+      # The output object **must** respond to `#puts` with the string to print
+      # as its only argument. This implies all IO objects can be used, as well
+      # as custom classes implementing that interface.
+      #
+      # @return [#puts] The output object currently in use.
+      #
+      # @see FeatureEnvy::Inspect::LoggerAdapter
+      attr_accessor :output
+    end
+
+    # An inspect-based inspector.
+    #
+    # This is an inspector that calls `#inspect` on objects being inspected.
+    InspectInspector = ->(object) { object.inspect }
+
+    # An adapter class enabling the user of loggers for output.
+    #
+    # {FeatureEnvy::Inspect.output} must respond to `#puts`, which precludes
+    # loggers. This adapter can be used to make loggers usable as outputs by
+    # logging at the desired level.
+    #
+    # @example
+    #   # Given a logger, it can be used as inspection output by setting:
+    #   FeatureEnvy::Inspect.output = FeatureEnvy::Inspect::LoggerAdapter.new logger
+    #
+    # @example Changing the log level
+    #   FeatureEnvy::Inspect.output =
+    #     FeatureEnvy::Inspect::LoggerAdapter.new logger,
+    #                                             level: Logger::INFO
+    class LoggerAdapter
+      # Initializes a new adapter for the specified logger.
+      #
+      # @param logger [Logger] logger to use for output
+      # @param level [Logger::DEBUG | Logger::INFO | Logger::WARN | Logger::ERROR | Logger::FATAL | Logger::UNKNOWN]
+      #   level at which inspection results should be logged.
+      def initialize logger, level: Logger::DEBUG
+        @logger = logger
+        @level  = level
+      end
+
+      # @api private
+      def puts string
+        @logger.add @level, string
+        nil
+      end
+    end
+  end
+end

data/lib/feature_envy/internal.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module FeatureEnvy
-  # @private
+  # @!visibility private
   module Internal
     # Returns all subclasses of the given class.
     def self.subclasses parent_class

data/lib/feature_envy/missing.rb

@@ -0,0 +1,5 @@
+module FeatureEnvy
+  module Missing
+    # Missing parameters
+  end
+end

data/lib/feature_envy/name_dispatch.rb

@@ -0,0 +1,11 @@
+# irb(main):002:0> method(:foo).parameters
+# => [[:req, :a], [:req, :b], [:opt, :c], [:keyreq, :d], [:block, :block]]
+
+module FeatureEnvy
+  module NameDispatch
+    refine Module do
+      def name_dispatch *method_names
+      end
+    end
+  end
+end

data/lib/feature_envy/operation.rb

@@ -0,0 +1,102 @@
+# TODO:
+#   - handle blocks
+#   - add pre- and post-condition checking
+#   - add Kernel#parameter for injection
+#   - add Operation::Pipeline class to represent the whole pipeline
+#   - add inline parameter transformation
+#   - configurable exception handling
+module FeatureEnvy
+  class Operation
+    module PipelineOperator
+      refine BasicObject do
+        def >>(callable) = callable.call(self)
+      end
+    end
+
+    class Pipeline
+      def initialize first, second
+        first_operations = first.is_a?(Pipeline) ? first.operations : [first]
+        second_operations = second.is_a?(Pipeline) ? second.operations : [second]
+
+        @operations = first_operations + second_operations
+      end
+
+      def call value
+        @operations.each do |operation|
+          value = operation.call value
+        end
+
+        value
+      end
+
+      def inspect
+        @operations.map(&:inspect).join " >> "
+      end
+
+      protected
+
+      attr_reader :operations
+    end
+
+    Placeholder = Object.new.freeze
+
+    class << self
+      private :new
+
+      def define(&block)
+        klass = Class.new(Operation)
+        klass.define_singleton_method(:perform, &block)
+        klass
+      end
+
+      def call(*args, **kwargs)
+        if args.include?(Placeholder) || kwargs.value?(Placeholder)
+          new(*args, **kwargs)
+        else
+          perform(*args, **kwargs)
+        end
+      end
+
+      def [](...) = self.call(...)
+    end
+
+    def initialize *args, **kwargs
+      @args   = args
+      @kwargs = kwargs
+    end
+
+    def call value
+      args   = @args.map { |arg| arg.equal?(Placeholder) ? value : arg }
+      kwargs = @kwargs.transform_values { |arg| arg.equal?(Placeholder) ? value : arg }
+
+      self.class.perform *args, **kwargs
+    end
+
+    def [](...) = call(...)
+
+    def inspect
+      args = []
+      @args.each do |arg|
+        args << inspect_arg(arg)
+      end
+      kwargs_part = @kwargs.each do |key, arg|
+        args << "#{key}: #{inspect_arg(arg)}"
+      end
+      "#{self.class.name}[#{args.join(", ")}]"
+    end
+
+    def >>(rest)
+      Pipeline.new(self, rest)
+    end
+
+    private
+
+    def inspect_arg(arg)
+      if arg.equal?(Placeholder)
+        "__"
+      else
+        arg.inspect
+      end
+    end
+  end
+end

data/lib/feature_envy/version.rb

@@ -2,5 +2,5 @@
 
 module FeatureEnvy
   # The current version number.
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/feature_envy.rb

@@ -7,6 +7,13 @@ require_relative "feature_envy/version"
 # Features are independent from each other and are implemented in separate
 # submodules. Refer to module documentation for details on how each feature can
 # be enabled and used.
+#
+# The following features are available:
+#
+# - {FeatureEnvy::FinalClass} - final classes.
+# - {FeatureEnvy::LazyAccessor} - lazy accessors.
+# - {FeatureEnvy::ObjectLiteral} - object literals.
+# - {FeatureEnvy::Inspect} - Elixir-style inspect.
 module FeatureEnvy
   # A base class for all errors raised by Feature Envy.
   class Error < StandardError; end
@@ -15,4 +22,5 @@ module FeatureEnvy
   autoload :Internal,      "feature_envy/internal"
   autoload :LazyAccessor,  "feature_envy/lazy_accessor"
   autoload :ObjectLiteral, "feature_envy/object_literal"
+  autoload :Inspect,       "feature_envy/inspect"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: feature_envy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Greg Navis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-05 00:00:00.000000000 Z
+date: 2023-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -103,9 +103,14 @@ files:
 - README.md
 - lib/feature_envy.rb
 - lib/feature_envy/final_class.rb
+- lib/feature_envy/final_method.rb
+- lib/feature_envy/inspect.rb
 - lib/feature_envy/internal.rb
 - lib/feature_envy/lazy_accessor.rb
+- lib/feature_envy/missing.rb
+- lib/feature_envy/name_dispatch.rb
 - lib/feature_envy/object_literal.rb
+- lib/feature_envy/operation.rb
 - lib/feature_envy/version.rb
 homepage: https://github.com/gregnavis/feature_envy
 licenses: