zeitwerk 2.6.11 → 2.6.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dd43924a88fceee915258e119a02df8fb173199576f52cf18c8298aab091361
-  data.tar.gz: 6aeeced1ce99e28238ebd1488a543da6ba4fb885e283f999cec30a49db3a0ccf
+  metadata.gz: 5d4ce4eb7136dafe17130fc5d895e525d80ae947f02dd9420b5bc85a4d6f0dfd
+  data.tar.gz: edcac638955fef258ad36a358b78da6831a715ed46446848e39f9f1d8fb7de0b
 SHA512:
-  metadata.gz: ca6b895667327b79fe51d504de760150aeceba5edb64400a6976962c1241bb8061f5c29e4d8584ba888694a0b1b30cf2f149f66f52181089fda262dde541d902
-  data.tar.gz: 8393b41bda4187ce0195ce5b1192455a2bc574291188b0eba86f31af88fc66e3d441717823ac07407f8c7be4e4a97de06cb5bc1922a133e66ed51cc91f6eb1c7
+  metadata.gz: f0a6e64c56635c9c6a8c9b24bdeb7509e4a7f14489f32aae18b02221c23b95b34096184c78d2d1509130ce75031ed0f3a7751b78e43d9b72122440f07cf980bc
+  data.tar.gz: 06440147c101a95ac2c8b7dcd43920a3efc3da2f58b902c157730a449d57b6ef74e0d3db7f3d2735be816a74ceb774e2d4075741556c7e2ba7fa00b8130c1723

data/README.md

@@ -40,6 +40,7 @@
   - [Inflection](#inflection)
     - [Zeitwerk::Inflector](#zeitwerkinflector)
     - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
+    - [Zeitwerk::NullInflector](#zeitwerknullinflector)
     - [Custom inflector](#custom-inflector)
   - [Callbacks](#callbacks)
     - [The on_setup callback](#the-on_setup-callback)
@@ -373,7 +374,7 @@ require "zeitwerk"
 loader = Zeitwerk::Loader.new
 loader.tag = File.basename(__FILE__, ".rb")
 loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
-loader.push_dir(__dir__)
+loader.push_dir(File.dirname(__FILE__))
 ```
 
 If the main module references project constants at the top-level, Zeitwerk has to be ready to load them. Their definitions, in turn, may reference other project constants. And this is recursive. Therefore, it is important that the `setup` call happens above the main module definition:
@@ -579,7 +580,7 @@ root_dir2/my_app/routes
 root_dir3/my_app/routes
 ```
 
-where `root_directory{1,2,3}` are root directories, eager loading `MyApp::Routes` will eager load the contents of the three corresponding directories.
+where `root_dir{1,2,3}` are root directories, eager loading `MyApp::Routes` will eager load the contents of the three corresponding directories.
 
 There might exist external source trees implementing part of the namespace. This happens routinely, because top-level constants are stored in the globally shared `Object`. It happens also when deliberately [reopening third-party namespaces](#reopening-third-party-namespaces). Such external code is not eager loaded, the implementation is carefully scoped to what the receiver manages to avoid side-effects elsewhere.
 
@@ -774,6 +775,31 @@ This inflector is like the basic one, except it expects `lib/my_gem/version.rb`
 
 The inflectors of different loaders are independent of each other. There are no global inflection rules or global configuration that can affect this inflector. It is deterministic.
 
+<a id="markdown-zeitwerknullinflector" name="zeitwerknullinflector"></a>
+#### Zeitwerk::NullInflector
+
+This is an experimental inflector that simply returns its input unchanged.
+
+```ruby
+loader.inflector = Zeitwerk::NullInflector.new
+```
+
+In a project using this inflector, the names of files and directories are equal to the constants they define:
+
+```
+User.rb       -> User
+HTMLParser.rb -> HTMLParser
+Admin/Role.rb -> Admin::Role
+```
+
+Point is, you think less. Names that typically need custom configuration like acronyms no longer require your attention. What you see is what you get, simple.
+
+This inflector is experimental since Ruby usually goes for snake case in files and directories. But hey, if you fancy giving it a whirl, go for it!
+
+The null inflector cannot be used in Rails applications because the `main` autoloader also manages engines. However, you could subclass the default inflector and override `camelize` to return the basename untouched if it starts with an uppercase letter. Generators would not create the expected file names, but you could still experiment to see how far this approach takes you.
+
+In case-insensitive file systems, this inflector works as long as directory listings return the expected strings. Zeitwerk lists directories using Ruby APIs like `Dir.children` or `Dir.entries`.
+
 <a id="markdown-custom-inflector" name="custom-inflector"></a>
 #### Custom inflector
 
@@ -1006,7 +1032,7 @@ Zeitwerk::Loader.default_logger = method(:puts)
 
 If there is a logger configured, you'll see traces when autoloads are set, files loaded, and modules autovivified. While reloading, removed autoloads and unloaded objects are also traced.
 
-As a curiosity, if your project has namespaces you'll notice in the traces Zeitwerk sets autoloads for _directories_. That's a technique used to be able to descend into subdirectories on demand, avoiding that way unnecessary tree walks.
+As a curiosity, if your project has namespaces you'll notice in the traces Zeitwerk sets autoloads for _directories_. This allows descending into subdirectories on demand, thus avoiding unnecessary tree walks.
 
 <a id="markdown-loader-tag" name="loader-tag"></a>
 #### Loader tag
@@ -1032,7 +1058,7 @@ Zeitwerk@my_gem: constant MyGem::Foo loaded from ...
 <a id="markdown-ignoring-parts-of-the-project" name="ignoring-parts-of-the-project"></a>
 ### Ignoring parts of the project
 
-Zeitwerk ignores automatically any file or directory whose name starts with a dot, and any files that do not have extension ".rb".
+Zeitwerk ignores automatically any file or directory whose name starts with a dot, and any files that do not have the extension ".rb".
 
 However, sometimes it might still be convenient to tell Zeitwerk to completely ignore some particular Ruby file or directory. That is possible with `ignore`, which accepts an arbitrary number of strings or `Pathname` objects, and also an array of them.
 
@@ -1325,7 +1351,7 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
 
 3. In that line, if two loaders manage files that translate to the same constant in the same namespace, the first one wins, the rest are ignored. Similar to what happens with `require` and `$LOAD_PATH`, only the first occurrence matters.
 
-4. Projects that reopen a namespace defined by some dependency have to ensure said namespace is loaded before setup. That is, the project has to make sure it reopens, rather than define. This is often accomplished just loading the dependency.
+4. Projects that reopen a namespace defined by some dependency have to ensure said namespace is loaded before setup. That is, the project has to make sure it reopens, rather than defines, the namespace. This is often accomplished by loading (e.g., `require`-ing) the dependency.
 
 5. Objects stored in reloadable constants should not be cached in places that are not reloaded. For example, non-reloadable classes should not subclass a reloadable class, or mixin a reloadable module. Otherwise, after reloading, those classes or module objects would become stale. Referring to constants in dynamic places like method calls or lambdas is fine.
 

data/lib/zeitwerk/kernel.rb

@@ -14,10 +14,6 @@ module Kernel
   # should not require anything. But if someone has legacy require calls around,
   # they will work as expected, and in a compatible way. This feature is by now
   # EXPERIMENTAL and UNDOCUMENTED.
-  #
-  # We cannot decorate with prepend + super because Kernel has already been
-  # included in Object, and changes in ancestors don't get propagated into
-  # already existing ancestor chains on Ruby < 3.0.
   alias_method :zeitwerk_original_require, :require
   class << self
     alias_method :zeitwerk_original_require, :require
@@ -28,10 +24,10 @@ module Kernel
     if loader = Zeitwerk::Registry.loader_for(path)
       if path.end_with?(".rb")
         required = zeitwerk_original_require(path)
-        loader.on_file_autoloaded(path) if required
+        loader.__on_file_autoloaded(path) if required
         required
       else
-        loader.on_dir_autoloaded(path)
+        loader.__on_dir_autoloaded(path)
         true
       end
     else
@@ -39,7 +35,7 @@ module Kernel
       if required
         abspath = $LOADED_FEATURES.last
         if loader = Zeitwerk::Registry.loader_for(abspath)
-          loader.on_file_autoloaded(abspath)
+          loader.__on_file_autoloaded(abspath)
         end
       end
       required

data/lib/zeitwerk/loader/callbacks.rb

@@ -2,12 +2,12 @@
 
 module Zeitwerk::Loader::Callbacks
   include Zeitwerk::RealModName
+  extend Zeitwerk::Internal
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
-  # @private
   # @sig (String) -> void
-  def on_file_autoloaded(file)
+  internal def on_file_autoloaded(file)
     cref  = autoloads.delete(file)
     cpath = cpath(*cref)
 
@@ -20,8 +20,16 @@ module Zeitwerk::Loader::Callbacks
     else
       msg = "expected file #{file} to define constant #{cpath}, but didn't"
       log(msg) if logger
+
+      # Ruby still keeps the autoload defined, but we remove it because the
+      # contract in Zeitwerk is more strict.
       crem(*cref)
+
+      # Since the expected constant was not defined, there is nothing to unload.
+      # However, if the exception is rescued and reloading is enabled, we still
+      # need to deleted the file from $LOADED_FEATURES.
       to_unload[cpath] = [file, cref] if reloading_enabled?
+
       raise Zeitwerk::NameError.new(msg, cref.last)
     end
   end
@@ -29,9 +37,8 @@ module Zeitwerk::Loader::Callbacks
   # Invoked from our decorated Kernel#require when a managed directory is
   # autoloaded.
   #
-  # @private
   # @sig (String) -> void
-  def on_dir_autoloaded(dir)
+  internal def on_dir_autoloaded(dir)
     # Module#autoload does not serialize concurrent requires in CRuby < 3.2, and
     # we handle directories ourselves without going through Kernel#require, so
     # the callback needs to account for concurrency.
@@ -74,7 +81,7 @@ module Zeitwerk::Loader::Callbacks
   def on_namespace_loaded(namespace)
     if dirs = namespace_dirs.delete(real_mod_name(namespace))
       dirs.each do |dir|
-        set_autoloads_in_dir(dir, namespace)
+        define_autoloads_for_dir(dir, namespace)
       end
     end
   end

data/lib/zeitwerk/loader/eager_load.rb

@@ -171,7 +171,7 @@ module Zeitwerk::Loader::EagerLoad
         next if honour_exclusions && eager_load_exclusions.member?(abspath)
 
         if ruby?(abspath)
-          if (cref = autoloads[abspath]) && !shadowed_file?(abspath)
+          if (cref = autoloads[abspath])
             cget(*cref)
           end
         else

data/lib/zeitwerk/loader.rb

@@ -121,7 +121,7 @@ module Zeitwerk
         break if @setup
 
         actual_roots.each do |root_dir, root_namespace|
-          set_autoloads_in_dir(root_dir, root_namespace)
+          define_autoloads_for_dir(root_dir, root_namespace)
         end
 
         on_setup_callbacks.each(&:call)
@@ -407,14 +407,14 @@ module Zeitwerk
     end
 
     # @sig (String, Module) -> void
-    private def set_autoloads_in_dir(dir, parent)
+    private def define_autoloads_for_dir(dir, parent)
       ls(dir) do |basename, abspath|
         if ruby?(basename)
           basename.delete_suffix!(".rb")
           autoload_file(parent, cname_for(basename, abspath), abspath)
         else
           if collapse?(abspath)
-            set_autoloads_in_dir(abspath, parent)
+            define_autoloads_for_dir(abspath, parent)
           else
             autoload_subdir(parent, cname_for(basename, abspath), abspath)
           end
@@ -443,12 +443,12 @@ module Zeitwerk
       elsif !cdef?(parent, cname)
         # First time we find this namespace, set an autoload for it.
         namespace_dirs[cpath(parent, cname)] << subdir
-        set_autoload(parent, cname, subdir)
+        define_autoload(parent, cname, subdir)
       else
         # For whatever reason the constant that corresponds to this namespace has
         # already been defined, we have to recurse.
         log("the namespace #{cpath(parent, cname)} already exists, descending into #{subdir}") if logger
-        set_autoloads_in_dir(subdir, cget(parent, cname))
+        define_autoloads_for_dir(subdir, cget(parent, cname))
       end
     end
 
@@ -471,7 +471,7 @@ module Zeitwerk
         shadowed_files << file
         log("file #{file} is ignored because #{cpath(parent, cname)} is already defined") if logger
       else
-        set_autoload(parent, cname, file)
+        define_autoload(parent, cname, file)
       end
     end
 
@@ -485,12 +485,12 @@ module Zeitwerk
 
       log("earlier autoload for #{cpath(parent, cname)} discarded, it is actually an explicit namespace defined in #{file}") if logger
 
-      set_autoload(parent, cname, file)
+      define_autoload(parent, cname, file)
       register_explicit_namespace(cpath(parent, cname))
     end
 
     # @sig (Module, Symbol, String) -> void
-    private def set_autoload(parent, cname, abspath)
+    private def define_autoload(parent, cname, abspath)
       parent.autoload(cname, abspath)
 
       if logger

data/lib/zeitwerk/null_inflector.rb

@@ -0,0 +1,5 @@
+class Zeitwerk::NullInflector
+  def camelize(basename, _abspath)
+    basename
+  end
+end

data/lib/zeitwerk/version.rb

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

data/lib/zeitwerk.rb

@@ -9,6 +9,7 @@ module Zeitwerk
   require_relative "zeitwerk/explicit_namespace"
   require_relative "zeitwerk/inflector"
   require_relative "zeitwerk/gem_inflector"
+  require_relative "zeitwerk/null_inflector"
   require_relative "zeitwerk/kernel"
   require_relative "zeitwerk/error"
   require_relative "zeitwerk/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.11
+  version: 2.6.13
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-02 00:00:00.000000000 Z
+date: 2024-02-06 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -35,6 +35,7 @@ files:
 - lib/zeitwerk/loader/config.rb
 - lib/zeitwerk/loader/eager_load.rb
 - lib/zeitwerk/loader/helpers.rb
+- lib/zeitwerk/null_inflector.rb
 - lib/zeitwerk/real_mod_name.rb
 - lib/zeitwerk/registry.rb
 - lib/zeitwerk/version.rb
@@ -61,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.16
+rubygems_version: 3.5.5
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader