feature_envy 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebacd4b2d2a8d5292de874248a212a72b02a7bc13b5279b08f020a88c8973e71
-  data.tar.gz: bca18e8eab4ef3d67efa38b65a09f4ede7291873a95a266748bbfd79e2b9ab45
+  metadata.gz: d7675c689bf69e95854627b7dc5e28affa5a2fed1bcb46f8255a80217c6abdea
+  data.tar.gz: 17a050ab57c4af67a4c967756b4704220e8511940498cb5f66c9989b6ecb2225
 SHA512:
-  metadata.gz: 534c102e65795b30fd4cdd42ef10b34b062776642f145ebddffd3865fc39e81657c870e645e782362f39c45b1d6afb2e565caefb2932da69fcd84d71121a5548
-  data.tar.gz: 0be465e644e71f4b51f14acb6e6e496c43618e5fbe8e13cc2a288291789074bcbc5d297589b4cb4b3d36eff742eb5a5351b3db81298a7637e22f348e78afb53b
+  metadata.gz: 073e92360b8fbcaa1b6ce67a68f37adfdc4282c69bc15be4cc1e4119a99671958c175597309169a9e122008371a70814dd3e0836250185bad95374a241b6dbd5
+  data.tar.gz: 2f3e21f91d1be99f5e00251568c87cb62131e8666af9c2a2d9685d42832d20cefb36a1f8ba87705c8b4f0a4fc3ddad10177c6caf473dcd6001156e2113f07804

data/README.md

@@ -5,6 +5,12 @@ 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
+
 ## Installation
 
 You can install the gem by running `gem install feature_envy` or adding it to

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

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

data/lib/feature_envy.rb

@@ -11,6 +11,8 @@ 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"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: feature_envy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Greg Navis
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-24 00:00:00.000000000 Z
+date: 2023-04-05 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
@@ -104,17 +104,17 @@ files:
 - lib/feature_envy.rb
 - lib/feature_envy/final_class.rb
 - lib/feature_envy/internal.rb
+- lib/feature_envy/lazy_accessor.rb
+- lib/feature_envy/object_literal.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 +124,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 +135,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