zeitwerk 2.6.7 → 2.6.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6c7bf12c3a33195c57541b840ca6d7dbc21b19e0d7b91d8933ad37aa88b325d
-  data.tar.gz: 4b8dd86417dd633b78c02eada9ed6956e8e708397c988237aaddecb9644ba469
+  metadata.gz: 418f16f6224359c716a990f72ae916c980a3f388b09ab018c0972b8558530620
+  data.tar.gz: '04847c6c8f8f894fe3c2b3c39d175b5854b583d3a02ef5cca27a53cb1b8dafd4'
 SHA512:
-  metadata.gz: 4f0bc60d9914a9e815aed501a030f7e9bde7927f750f3836f96ac86a52c0699f4ca69456bd381845428f6b09adccaa085443f39bb0fdaa651437742e21d10af2
-  data.tar.gz: 3ba55f7bb24725d156cc4043697bfcd6092e2893f1aa71296965c82ae9ed66b79c30f853b535693b6b884d7d3d26cf1b122545e395ba11c92f65552e14116248
+  metadata.gz: f86272e84721cf9b8b1e07182b1b60cfe732ef2c266dbe076225d32af52fc9a30c278a14651ddbb3d435636646dd23c948d3fe0f00ed9b8393abdeb34dd40028
+  data.tar.gz: 562738b53779310e899c2065c7046844d27daabb5f354972e4c9b65bec3e5c0cdade92d19ed815fe7b0dc01538603daa3e4dd2f0049fe9a7a2e74313c0f040f6

data/README.md

@@ -24,6 +24,7 @@
   - [Setup](#setup)
     - [Generic](#generic)
     - [for_gem](#for_gem)
+    - [for_gem_extension](#for_gem_extension)
   - [Autoloading](#autoloading)
   - [Eager loading](#eager-loading)
     - [Eager load exclusions](#eager-load-exclusions)
@@ -410,6 +411,65 @@ Otherwise, there's a flag to say the extra stuff is OK:
 Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 ```
 
+<a id="markdown-for_gem_extension" name="for_gem_extension"></a>
+#### for_gem_extension
+
+Let's suppose you are writing a gem to extend `Net::HTTP` with some niche feature. By [convention](https://guides.rubygems.org/name-your-gem/):
+
+* The gem should be called `net-http-niche_feature`. That is, hyphens for the extended part, a hyphen, and underscores for yours.
+* The namespace should be `Net::HTTP::NicheFeature`.
+* The entry point should be `lib/net/http/niche_feature.rb`.
+* Optionally, the gem could have a top-level `lib/net-http-niche_feature.rb`, but, if defined, that one should have just a `require` call for the entry point.
+
+The top-level file mentioned in the last point is optional. In particular, from
+
+```ruby
+gem "net-http-niche_feature"
+```
+
+if the hyphenated file does not exist, Bundler notes the conventional hyphenated pattern and issues a `require` for `net/http/niche_feature`.
+
+Gem extensions following the conventions above have a dedicated loader constructor: `Zeitwerk::Loader.for_gem_extension`.
+
+The structure of the gem would be like this:
+
+```ruby
+# lib/net-http-niche_feature.rb (optional)
+
+# For technical reasons, this cannot be require_relative.
+require "net/http/niche_feature"
+
+
+# lib/net/http/niche_feature.rb
+
+require "net/http"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem_extension(Net::HTTP)
+loader.setup
+
+module Net::HTTP::NicheFeature
+  # Since the setup has been performed, at this point we are already able
+  # to reference project constants, in this case Net::HTTP::NicheFeature::MyMixin.
+  include MyMixin
+end
+
+
+# lib/net/http/niche_feature/version.rb
+
+module Net::HTTP::NicheFeature
+  VERSION = "1.0.0"
+end
+```
+
+`Zeitwerk::Loader.for_gem_extension` expects as argument the namespace being extended, which has to be a non-anonymous class or module object.
+
+If it exists, `lib/net/http/niche_feature/version.rb` is expected to define `Net::HTTP::NicheFeature::VERSION`.
+
+Due to technical reasons, the entry point of the gem has to be loaded with `Kernel#require`. Loading that file with `Kernel#load` or `Kernel#require_relative` won't generally work. This is important if you load the entry point from the optional hyphenated top-level file.
+
+`Zeitwerk::Loader.for_gem_extension` is idempotent when invoked from the same file, to support gems that want to reload (unlikely).
+
 <a id="markdown-autoloading" name="autoloading"></a>
 ### Autoloading
 

data/lib/zeitwerk/gem_inflector.rb

@@ -5,8 +5,8 @@ module Zeitwerk
     # @sig (String) -> void
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
-      lib_dir       = File.dirname(root_file)
-      @version_file = File.join(lib_dir, namespace, "version.rb")
+      root_dir      = File.dirname(root_file)
+      @version_file = File.join(root_dir, namespace, "version.rb")
     end
 
     # @sig (String, String) -> String

data/lib/zeitwerk/gem_loader.rb

@@ -3,27 +3,31 @@
 module Zeitwerk
   # @private
   class GemLoader < Loader
+    include RealModName
+
     # Users should not create instances directly, the public interface is
     # `Zeitwerk::Loader.for_gem`.
     private_class_method :new
 
     # @private
     # @sig (String, bool) -> Zeitwerk::GemLoader
-    def self._new(root_file, warn_on_extra_files:)
-      new(root_file, warn_on_extra_files: warn_on_extra_files)
+    def self.__new(root_file, namespace:, warn_on_extra_files:)
+      new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
     end
 
     # @sig (String, bool) -> void
-    def initialize(root_file, warn_on_extra_files:)
+    def initialize(root_file, namespace:, warn_on_extra_files:)
       super()
 
-      @tag                 = File.basename(root_file, ".rb")
+      @tag = File.basename(root_file, ".rb")
+      @tag = real_mod_name(namespace) + "-" + @tag unless namespace.equal?(Object)
+
       @inflector           = GemInflector.new(root_file)
       @root_file           = File.expand_path(root_file)
-      @lib                 = File.dirname(root_file)
+      @root_dir            = File.dirname(root_file)
       @warn_on_extra_files = warn_on_extra_files
 
-      push_dir(@lib)
+      push_dir(@root_dir, namespace: namespace)
     end
 
     # @sig () -> void
@@ -38,7 +42,7 @@ module Zeitwerk
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 
-      ls(@lib) do |basename, abspath|
+      ls(@root_dir) do |basename, abspath|
         next if abspath == @root_file
         next if abspath == expected_namespace_dir
 

data/lib/zeitwerk/loader/config.rb

@@ -109,8 +109,7 @@ module Zeitwerk::Loader::Config
   # @raise [Zeitwerk::Error]
   # @sig (String | Pathname, Module) -> void
   def push_dir(path, namespace: Object)
-    # Note that Class < Module.
-    unless namespace.is_a?(Module)
+    unless namespace.is_a?(Module) # Note that Class < Module.
       raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
     end
 
@@ -298,9 +297,9 @@ module Zeitwerk::Loader::Config
     # Common use case.
     return false if ignored_paths.empty?
 
-    walk_up(abspath) do |abspath|
-      return true  if ignored_path?(abspath)
-      return false if roots.key?(abspath)
+    walk_up(abspath) do |path|
+      return true  if ignored_path?(path)
+      return false if roots.key?(path)
     end
 
     false
@@ -328,9 +327,9 @@ module Zeitwerk::Loader::Config
     # Optimize this common use case.
     return false if eager_load_exclusions.empty?
 
-    walk_up(abspath) do |abspath|
-      return true  if eager_load_exclusions.member?(abspath)
-      return false if roots.key?(abspath)
+    walk_up(abspath) do |path|
+      return true  if eager_load_exclusions.member?(path)
+      return false if roots.key?(path)
     end
 
     false

data/lib/zeitwerk/loader.rb

@@ -264,12 +264,15 @@ module Zeitwerk
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
+      include RealModName
+
       # @sig #call | #debug | nil
       attr_accessor :default_logger
 
       # This is a shortcut for
       #
       #   require "zeitwerk"
+      #
       #   loader = Zeitwerk::Loader.new
       #   loader.tag = File.basename(__FILE__, ".rb")
       #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
@@ -284,7 +287,36 @@ module Zeitwerk
       # @sig (bool) -> Zeitwerk::GemLoader
       def for_gem(warn_on_extra_files: true)
         called_from = caller_locations(1, 1).first.path
-        Registry.loader_for_gem(called_from, warn_on_extra_files: warn_on_extra_files)
+        Registry.loader_for_gem(called_from, namespace: Object, warn_on_extra_files: warn_on_extra_files)
+      end
+
+      # This is a shortcut for
+      #
+      #   require "zeitwerk"
+      #
+      #   loader = Zeitwerk::Loader.new
+      #   loader.tag = namespace.name + "-" + File.basename(__FILE__, ".rb")
+      #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
+      #   loader.push_dir(__dir__, namespace: namespace)
+      #
+      # except that this method returns the same object in subsequent calls from
+      # the same file, in the unlikely case the gem wants to be able to reload.
+      #
+      # This method returns a subclass of Zeitwerk::Loader, but the exact type
+      # is private, client code can only rely on the interface.
+      #
+      # @sig (bool) -> Zeitwerk::GemLoader
+      def for_gem_extension(namespace)
+        unless namespace.is_a?(Module) # Note that Class < Module.
+          raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
+        end
+
+        unless real_mod_name(namespace)
+          raise Zeitwerk::Error, "extending anonymous namespaces is unsupported"
+        end
+
+        called_from = caller_locations(1, 1).first.path
+        Registry.loader_for_gem(called_from, namespace: namespace, warn_on_extra_files: false)
       end
 
       # Broadcasts `eager_load` to all loaders. Those that have not been setup

data/lib/zeitwerk/registry.rb

@@ -86,8 +86,8 @@ module Zeitwerk
       #
       # @private
       # @sig (String) -> Zeitwerk::Loader
-      def loader_for_gem(root_file, warn_on_extra_files:)
-        gem_loaders_by_root_file[root_file] ||= GemLoader._new(root_file, warn_on_extra_files: warn_on_extra_files)
+      def loader_for_gem(root_file, namespace:, warn_on_extra_files:)
+        gem_loaders_by_root_file[root_file] ||= GemLoader.__new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
       end
 
       # @private

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "2.6.7"
+  VERSION = "2.6.8"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.7
+  version: 2.6.8
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-10 00:00:00.000000000 Z
+date: 2023-04-28 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -61,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.3
+rubygems_version: 3.4.11
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader