feature_envy 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebacd4b2d2a8d5292de874248a212a72b02a7bc13b5279b08f020a88c8973e71
-  data.tar.gz: bca18e8eab4ef3d67efa38b65a09f4ede7291873a95a266748bbfd79e2b9ab45
+  metadata.gz: a14b68770c0137db65d3846d607afa7c355f994d3f5716dc8f9f97b092c63cc4
+  data.tar.gz: f8c7eca5be96c55987540c741f19d2161e8d758ce3a22de98e7fc5603ca3d0ba
 SHA512:
-  metadata.gz: 534c102e65795b30fd4cdd42ef10b34b062776642f145ebddffd3865fc39e81657c870e645e782362f39c45b1d6afb2e565caefb2932da69fcd84d71121a5548
-  data.tar.gz: 0be465e644e71f4b51f14acb6e6e496c43618e5fbe8e13cc2a288291789074bcbc5d297589b4cb4b3d36eff742eb5a5351b3db81298a7637e22f348e78afb53b
+  metadata.gz: 2c2f7efc87d84526283e4558102ef8355455efa9597fbf83d9874a1adc177cbaddbd8167c87a50836778b2312d94dda1328c85eae06d91cb395d0eb4c6cc6228
+  data.tar.gz: 0c338372e47dba9ee7e4177f619a6de77cc8515c0daaea0976634a315564b5bfe34250a51ada1d55c126902c819d10ee8704cdf0d358fd50921860a905917ad7

data/README.md

@@ -5,6 +5,13 @@ Feature Envy enhances Ruby with features found in other programming languages.
 **WARNING**: This gem is still in development and a stable release hasn't been
 made yet. Bug reports and contributions are welcome!
 
+Supported features:
+
+- Final classes
+- Thread-safe lazy accessors
+- Object literals
+- Inspect (inspired by Elixir's `Kernel.inspect/2`)
+
 ## Installation
 
 You can install the gem by running `gem install feature_envy` or adding it to
@@ -18,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_class.rb

@@ -3,21 +3,35 @@
 module FeatureEnvy
   # Final classes.
   #
+  # ### Definition
+  #
   # A final class is a class that cannot be inherited from. In other words, a
-  # final class enforces the invariant that it has no subclasses. Existence of
-  # subclasses if checked **at the moment a class is defined final** (to catch
-  # cases where a class is reopened and made final after subclasses were
-  # defined) and when.
+  # final class enforces the invariant that it has no subclasses.
+  #
+  # ### Applications
+  #
+  # Preventing subclassing of classes that weren't specifically designed for
+  # handling it.
   #
-  # The module can be used in two ways:
+  # ### Usage
   #
-  # 1. Using it as a refinement and calling +.final!+ in bodies of classes that
+  # 1. Enable the feature in a specific class via `extend Feature::FinalClass`.
+  #    The class has been marked final and there's nothing else to do.
+  #    Alternatively, ...
+  # 2. Enable the feature in a specific **scope** using a refinement via
+  #    `using FeatureEnvy::FinalClass` and call `final!` in all classes that
   #    should be marked final.
-  # 2. Extending the class with {FeatureEnvy::FinalClass}.
   #
-  # See the example below for details.
+  # ### Discussion
   #
-  # @example Final classes with refinements
+  # A class in Ruby can be made final by raising an error in its `inherited`
+  # hook. This is what this module does. However, this is **not** enough to
+  # guarantee that no subclasses will be created. Due to Ruby's dynamic nature
+  # it'd be possible to define a class, subclass, and then reopen the class and
+  # mark it final. This edge **is** taken care of and would result in an
+  # exception.
+  #
+  # @example
   #   module Models
   #     # Use the refinement within the module, so that all classes defined
   #     # within support the final! method.
@@ -28,14 +42,6 @@ module FeatureEnvy
   #       final!
   #     end
   #   end
-  #
-  # @example Final classes without refinements
-  #   module Models
-  #     class User < Base
-  #       # Mark the User class final.
-  #       extend FeatureEnvy::FinalClass
-  #     end
-  #   end
   module FinalClass
     # An error representing a final class invariant violation.
     class Error < FeatureEnvy::Error
@@ -72,7 +78,7 @@ module FeatureEnvy
         subclasses = Internal.subclasses final_class
         return if subclasses.empty?
 
-        raise Error.new(final_class: final_class, subclasses: subclasses)
+        raise Error.new(final_class:, subclasses:)
       end
 
       # Determines whether a given class is marked final.

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/lazy_accessor.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module FeatureEnvy
+  # Lazy accessors.
+  #
+  # ### Definition
+  #
+  # A lazy **attribute** is an attribute whose value is determined on first
+  # access. The same value is used on all subsequent access without running the
+  # code to determine its value again.
+  #
+  # Lazy attributes are impossible in Ruby (see the discussion below), but
+  # lazy **accessors** are, and are provided by this module.
+  #
+  # ### Applications
+  #
+  # Deferring expensive computations until needed and ensuring they're performed
+  # at most once.
+  #
+  # ### Usage
+  #
+  # 1. Enable the feature in a specific class via `extend FeatureEnvy::LazyAccessor` or ...
+  # 2. Enable the feature in a specific **scope** (given module and all modules
+  #    and classes contained within) using a refinement via `using FeatureEnvy::LazyAccessor`.
+  # 3. Define one or more lazy attributes via `lazy(:name) { definition }`.
+  # 4. Do **NOT** read or write to the underlying attribute, e.g. `@name`;
+  #    always use the accessor method.
+  # 5. Lazy accessors are **thread-safe**: the definition block will be called
+  #    at most once; if two threads call the accessor for the first time one
+  #    will win the race to run the block and the other one will wait and reuse
+  #    the value produced by the first.
+  # 6. It's impossible to reopen a class and add new lazy accessors after **the
+  #    any class using lazy accessors has been instantiated**. Doing so would
+  #    either make the code thread-unsafe or require additional thread-safety
+  #    measures, potentially reducing performance.
+  #
+  # ### Discussion
+  #
+  # Ruby attributes start with `@` and assume the default value of `nil` if not
+  # assigned explicitly. Real lazy attributes are therefore impossible to
+  # implement in Ruby. Fortunately **accessors** (i.e. methods used to obtain
+  # attribute values) are conceptually close to attributes and can be made lazy.
+  #
+  # A naive approach found in many Ruby code bases looks like this:
+  #
+  # ```ruby
+  # def highest_score_user
+  #   @highest_score_user ||= find_highest_score_user
+  # end
+  # ```
+  #
+  # It's simple but suffers from a serious flaw: if `nil` is assigned to the
+  # attribute then subsequent access will result in another attempt to determine
+  # the attribute's value.
+  #
+  # The proper approach is much more verbose:
+  #
+  # ```ruby
+  # def highest_score_user
+  #   # If the underlying attribute is defined then return it no matter its value.
+  #   return @highest_score_user if defined?(@highest_score_user)
+  #
+  #   @highest_score_user = find_highest_score_user
+  # end
+  # ```
+  #
+  # ### Implementation Notes
+  #
+  # 1. Defining a lazy accessor defines a method with that name. The
+  #    corresponding attribute is **not** set before the accessor is called for
+  #    the first time.
+  # 2. The first time a lazy accessor is added to a class a special module
+  #    is included into it. It provides an `initialize` method that sets
+  #    `@lazy_attributes_mutexes` - a hash of mutexes protecting each lazy
+  #    accessor.
+  #
+  # @example
+  #   class User
+  #     # Enable the feature via refinements.
+  #     using FeatureEnvy::LazyAccessor
+  #
+  #     # Lazy accessors can return nil and have it cached and reused in
+  #     # subsequent calls.
+  #     lazy(:full_name) do
+  #       "#{first_name} #{last_name}" if first_name && last_name
+  #     end
+  #
+  #     # Lazy accessors are regular methods, that follow a specific structure,
+  #     # so they can call other methods, including other lazy accessors.
+  #     lazy(:letter_ending) do
+  #       if full_name
+  #         "Sincerely,\n#{full_name}"
+  #       else
+  #         "Sincerely"
+  #       end
+  #     end
+  #   end
+  module LazyAccessor
+    # A class representing an error related to lazy-accessors.
+    class Error < FeatureEnvy::Error; end
+
+    refine Class do
+      def lazy name, &definition
+        LazyAccessor.define self, name, &definition
+      end
+    end
+
+    # Defines a lazy accessor.
+    #
+    # The `definition` block will be called once when the accessor is used for
+    # the first time. Its value is returned and cached for subsequent accessor
+    # use.
+    #
+    # @param name [String|Symbol] accessor name.
+    # @return [Array<Symbol>] the array containing the accessor name as a
+    #   symbol; this is motivated by the built-in behavior of `attr_reader` and
+    #   other built-in accessor definition methods.
+    # @yieldreturn the value to store in the underlying attribute and return on
+    #   subsequent accessor use.
+    def lazy name, &definition
+      LazyAccessor.define self, name, &definition
+    end
+
+    # A class for creating mutexes for classes that make use of lazy accessors.
+    #
+    # The class keeps a hash that maps modules and classes to arrays of lazy
+    # accessor names defined therein.
+    #
+    # @private
+    class MutexFactory
+      def initialize
+        @mutexes_by_class = Hash.new { |hash, klass| hash[klass] = [] }
+      end
+
+      # Register a new lazy attribute.
+      #
+      # @return [Symbol] The name of the mutex corresponding to the specified
+      #   lazy accessor.
+      #
+      # @private
+      def register klass, lazy_accessor_name
+        ObjectSpace.each_object(klass) do # rubocop:disable Lint/UnreachableLoop
+          raise Error.new(<<~ERROR)
+            An instance of #{klass.name} has been already created, so it's no longer
+            possible to define a new lazy accessor, due to thread-safety reasons.
+          ERROR
+        end
+
+        mutex_name = :"@#{lazy_accessor_name}_mutex"
+        @mutexes_by_class[klass] << mutex_name
+        mutex_name
+      end
+
+      # Create mutexes for lazy accessor supported on a given instance.
+      #
+      # @private
+      def initialize_mutexes_for instance
+        current_class = instance.class
+        while current_class
+          @mutexes_by_class[current_class].each do |mutex_name|
+            instance.instance_variable_set mutex_name, Thread::Mutex.new
+          end
+          current_class = current_class.superclass
+        end
+
+        instance.class.included_modules.each do |mod|
+          @mutexes_by_class[mod].each do |mutex_name|
+            instance.instance_variable_set mutex_name, Thread::Mutex.new
+          end
+        end
+      end
+    end
+    private_constant :MutexFactory
+
+    @mutex_factory = MutexFactory.new
+
+    class << self
+      # A mutex factory used by the lazy accessors feature.
+      #
+      # @private
+      attr_reader :mutex_factory
+
+      # Defines a lazy accessor.
+      #
+      # Required to share the code between the extension and refinement.
+      #
+      # @private
+      def define klass, name, &definition
+        name = name.to_sym
+        variable_name = :"@#{name}"
+        mutex_name = LazyAccessor.mutex_factory.register klass, name
+
+        klass.class_eval do
+          # Include the lazy accessor initializer to ensure state related to
+          # lazy accessors is initialized properly. There's no need to include
+          # this module more than once.
+          #
+          # Question: is the inclusion check required? Brief testing indicates
+          # it's not.
+          if !include? Initialize
+            include Initialize
+          end
+
+          [
+            define_method(name) do
+              mutex = instance_variable_get(mutex_name)
+              if mutex # rubocop:disable Style/SafeNavigation
+                mutex.synchronize do
+                  if instance_variable_defined?(mutex_name)
+                    instance_variable_set variable_name, instance_eval(&definition)
+                    remove_instance_variable mutex_name
+                  end
+                end
+              end
+
+              instance_variable_get variable_name
+            end
+          ]
+        end
+      end
+    end
+
+    # A module included in all classes that use lazy accessors responsible for
+    # initializing a hash of mutexes that guarantee thread-safety on first call.
+    #
+    # @private
+    module Initialize
+      def initialize ...
+        super
+
+        LazyAccessor.mutex_factory.initialize_mutexes_for self
+      end
+    end
+    private_constant :Initialize
+  end
+end

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/object_literal.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module FeatureEnvy
+  # Object literals.
+  #
+  # ### Definition
+  #
+  # An expression that results in creating of an object with a predefined set of
+  # attributes and methods, without having to define and instantiated a class.
+  #
+  # ### Applications
+  #
+  # Defining singleton objects, both state and methods, without having to define
+  # their class explicitly.
+  #
+  # ### Usage
+  #
+  # 1. Enable the feature in a specific class via `include FeatureEnvy::ObjectLiteral`
+  #    or ...
+  # 2. Enable the feature in a specific scope via `using FeatureEnvy::ObjectLiteral`.
+  # 3. Create objects by calling `object { ... }`.
+  #
+  # ### Discussion
+  #
+  # Ruby does not offer literals for defining arbitrary objects. Fortunately,
+  # that gap is easy to fill with a helper method. The snippet below is
+  # literally how Feature Envy implements object literals:
+  #
+  # ```ruby
+  # def object &definition
+  #   object = Object.new
+  #   object.instance_eval &definition
+  #   object
+  # end
+  # ```
+  #
+  # All attributes set and methods defined inside the block will be set on
+  # `object`.
+  #
+  # @example
+  #   # Enable the feature in the current scope.
+  #   using FeatureEnvy::ObjectLiteral
+  #
+  #   # Assuming `database` and `router` are already defined.
+  #   app = object do
+  #     @database = database
+  #     @router   = router
+  #
+  #     def start
+  #       @database.connect
+  #       @router.activate
+  #     end
+  #   end
+  #
+  #   app.start
+  module ObjectLiteral
+    refine Kernel do
+      def object ...
+        ObjectLiteral.object(...)
+      end
+    end
+
+    # Defines an object literal.
+    #
+    # @yield The block is evaluated in the context of a newly created object.
+    #   Instance attributes and methods can be defined within the block and will
+    #   end up being set on the resulting object.
+    # @return [Object] The object defined by the block passed to the call.
+    def object ...
+      ObjectLiteral.object(...)
+    end
+
+    # @private
+    def self.object &definition
+      result = Object.new
+      result.instance_eval &definition
+      result
+    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.1.0"
+  VERSION = "0.3.0"
 end

data/lib/feature_envy.rb

@@ -7,10 +7,20 @@ 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
 
-  autoload :Internal,   "feature_envy/internal"
-  autoload :FinalClass, "feature_envy/final_class"
+  autoload :FinalClass,    "feature_envy/final_class"
+  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.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Greg Navis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-24 00:00:00.000000000 Z
+date: 2023-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -44,28 +44,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.21.0
+        version: 1.49.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.21.0
+        version: 1.49.0
 - !ruby/object:Gem::Dependency
   name: rubocop-minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.26.1
+        version: 0.29.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.26.1
+        version: 0.29.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
@@ -103,18 +103,23 @@ 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
-- test/final_class_test.rb
-- test/internal_test.rb
-- test/support/assertions.rb
-- test/test_helper.rb
 homepage: https://github.com/gregnavis/feature_envy
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/gregnavis/feature_envy
   source_code_uri: https://github.com/gregnavis/feature_envy
+  bug_tracker_uri: https://github.com/gregnavis/feature_envy/issues
+  documentation_uri: https://rubydoc.info/gems/feature_envy
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -124,7 +129,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -135,8 +140,4 @@ rubygems_version: 3.4.6
 signing_key:
 specification_version: 4
 summary: Feature Envy enhances Ruby with features inspired by other programming languages
-test_files:
-- test/final_class_test.rb
-- test/internal_test.rb
-- test/support/assertions.rb
-- test/test_helper.rb
+test_files: []

data/test/final_class_test.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-require "test_helper"
-
-class FinalClassTest < Minitest::Test
-  using FeatureEnvy::FinalClass
-
-  def test_non_refinement_final_class_cannot_be_inherited
-    user = Class.new do
-      extend FeatureEnvy::FinalClass
-    end
-
-    assert_raises FeatureEnvy::FinalClass::Error,
-                  "Subclassing a final class should have raised an exception" do
-      Class.new user
-    end
-    assert user.final?,
-           "A final class should have been reported as final but was not"
-  end
-
-  def test_refinement_final_class_cannot_be_inherited
-    user = Class.new do
-      final!
-    end
-
-    assert_raises FeatureEnvy::FinalClass::Error,
-                  "Subclassing a final class should have raised an exception" do
-      Class.new user
-    end
-    assert user.final?,
-           "A final class should have been reported as final but was not"
-  end
-
-  def test_error_when_superclass_made_final
-    model = Class.new
-    user = Class.new model # rubocop:disable Lint/UselessAssignment
-
-    assert_raises FeatureEnvy::FinalClass::Error,
-                  "Making a superclass final should have raised an exception" do
-      model.extend FeatureEnvy::FinalClass
-    end
-  end
-end

data/test/internal_test.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-require "test_helper"
-
-class InternalTest < Minitest::Test
-  class Model; end
-  class User < Model; end
-  class Project < Model; end
-  class AdminUser < User; end
-
-  def test_subclasses
-    assert_equal [User, Project].sort_by(&:name),
-                 FeatureEnvy::Internal.subclasses(Model).sort_by(&:name),
-                 "All subclasses and no other descendants should have been returned"
-  end
-
-  def test_class_name
-    assert_equal "InternalTest::Model",
-                 FeatureEnvy::Internal.class_name(Model)
-    assert_equal "InternalTest::User",
-                 FeatureEnvy::Internal.class_name(User)
-    assert_equal "anonymous class",
-                 FeatureEnvy::Internal.class_name(Class.new)
-  end
-end

data/test/support/assertions.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Assertions
-  def assert_mapping callable, mapping
-    Hash(mapping).each do |input, output|
-      arguments = input.is_a?(Array) ? input : [input]
-
-      assert_equal output, callable.call(*arguments)
-    end
-  end
-end

data/test/test_helper.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "feature_envy"
-
-require "minitest/autorun"
-
-require_relative "support/assertions"
-
-class Minitest::Test
-  include Assertions
-end