zeitwerk 2.1.10 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3dbf7502d4126651ab645926f072af5f5164fcb495c06ae32e9748aa2807670e
-  data.tar.gz: e124bca82ed054d1ca304e95605ad011a2c6411792653c3c86b785a3cc956e06
+  metadata.gz: 7b0087cb3e996cc4e5ccfabf179c0e793a811d24e4ee36debf9e07fcb06e1630
+  data.tar.gz: 63c94cc509932eb9dfceb9e951f05092c30e9d3aff8bacda5a66d7da93bf4a64
 SHA512:
-  metadata.gz: 7efe14aeb7e16563d6a1b69b2aac82d75dd1c4e79dae2fb4654e7c93742e15018f16fad4591f8763bf03b2f9d9d71a6e95209907a0765952dafa8dedc957d2ef
-  data.tar.gz: 8dea5ad3b1979cacb619b13385b337e81cc08efc39e0411f890229f0a9d17035fdfb17cf2ac84f6dcd3eeec4b4daa732e796e51fc1fdf707c210d9943481edcf
+  metadata.gz: 6b978a994c59c4da2e50b32a825626a3e48c4e9e8f3455320f22799437c5fc81de4f3635ab8ea07626f42f03cbea71dc735c70b446942d8e914d5dd1104d15dc
+  data.tar.gz: 2a0d8301b268d419be3dd36902ba44236e9de4a502c203bcbc2d32448f1c1d4e85fbae294b57d200a253e8e61e8ef07c119c9bf5f50e905d50064be6fe62babc

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2019–ω Xavier Noria
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -3,7 +3,7 @@
 
 
 [![Gem Version](https://img.shields.io/gem/v/zeitwerk.svg?style=for-the-badge)](https://rubygems.org/gems/zeitwerk)
-[![Build Status](https://img.shields.io/travis/com/fxn/zeitwerk.svg?style=for-the-badge&branch=master)](https://travis-ci.com/fxn/zeitwerk)
+[![Build Status](https://img.shields.io/travis/com/fxn/zeitwerk/master?style=for-the-badge)](https://travis-ci.com/fxn/zeitwerk)
 
 <!-- TOC -->
 
@@ -12,11 +12,15 @@
 - [File structure](#file-structure)
     - [Implicit namespaces](#implicit-namespaces)
     - [Explicit namespaces](#explicit-namespaces)
+    - [Collapsing directories](#collapsing-directories)
     - [Nested root directories](#nested-root-directories)
 - [Usage](#usage)
     - [Setup](#setup)
-    - [Reloading](#reloading)
+        - [Generic](#generic)
+        - [for_gem](#for_gem)
+    - [Autoloading](#autoloading)
     - [Eager loading](#eager-loading)
+    - [Reloading](#reloading)
     - [Inflection](#inflection)
         - [Zeitwerk::Inflector](#zeitwerkinflector)
         - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
@@ -28,9 +32,14 @@
         - [Use case: The adapter pattern](#use-case-the-adapter-pattern)
         - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
     - [Edge cases](#edge-cases)
+    - [Reopening third-party namespaces](#reopening-third-party-namespaces)
     - [Rules of thumb](#rules-of-thumb)
+    - [Debuggers](#debuggers)
+        - [Break](#break)
+        - [Byebug](#byebug)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
+- [Testing](#testing)
 - [Motivation](#motivation)
 - [Thanks](#thanks)
 - [License](#license)
@@ -48,7 +57,9 @@ Zeitwerk is also able to reload code, which may be handy while developing web ap
 
 The gem is designed so that any project, gem dependency, application, etc. can have their own independent loader, coexisting in the same process, managing their own project trees, and independent of each other. Each loader has its own configuration, inflector, and optional logger.
 
-Internally, Zeitwerk issues `require` calls exclusively using absolute file names, so there are no costly file system lookups in `$LOAD_PATH`. Technically, the directories managed by Zeitwerk do not even need to be in `$LOAD_PATH`. Furthermore, Zeitwerk does only one single scan of the project tree, and it descends into subdirectories lazily, only if their namespaces are used.
+Internally, Zeitwerk issues `require` calls exclusively using absolute file names, so there are no costly file system lookups in `$LOAD_PATH`. Technically, the directories managed by Zeitwerk do not even need to be in `$LOAD_PATH`.
+
+Furthermore, Zeitwerk does at most one single scan of the project tree, and it descends into subdirectories lazily, only if their namespaces are used.
 
 <a id="markdown-synopsis" name="synopsis"></a>
 ## Synopsis
@@ -162,6 +173,32 @@ end
 
 An explicit namespace must be managed by one single loader. Loaders that reopen namespaces owned by other projects are responsible for loading their constants before setup.
 
+<a id="markdown-collapsing-directories" name="collapsing-directories"></a>
+### Collapsing directories
+
+Say some directories in a project exist for organizational purposes only, and you prefer not to have them as namespaces. For example, the `actions` subdirectory in the next example is not meant to represent a namespace, it is there only to group all actions related to bookings:
+
+```
+booking.rb                -> Booking
+booking/actions/create.rb -> Booking::Create
+```
+
+To make it work that way, configure Zeitwerk to collapse said directory:
+
+```ruby
+loader.collapse("booking/actions")
+```
+
+This method accepts an arbitrary number of strings or `Pathname` objects, and also an array of them.
+
+You can pass directories and glob patterns. Glob patterns are expanded when they are added, and again on each reload.
+
+To illustrate usage of glob patterns, if `actions` in the example above is part of a standardized structure, you could use a wildcard:
+
+```ruby
+loader.collapse("*/actions")
+```
+
 <a id="markdown-nested-root-directories" name="nested-root-directories"></a>
 ### Nested root directories
 
@@ -181,6 +218,9 @@ should define `Geolocatable`, not `Concerns::Geolocatable`.
 <a id="markdown-setup" name="setup"></a>
 ### Setup
 
+<a id="markdown-generic" name="generic"></a>
+#### Generic
+
 Loaders are ready to load code right after calling `setup` on them:
 
 ```ruby
@@ -197,37 +237,73 @@ loader.push_dir(...)
 loader.setup
 ```
 
-The loader returned by `Zeitwerk::Loader.for_gem` has the directory of the caller pushed, normally that is the absolute path of `lib`. In that sense, `for_gem` can be used also by projects with a gem structure, even if they are not technically gems. That is, you don't need a gemspec or anything.
+<a id="markdown-for_gem" name="for_gem"></a>
+#### for_gem
 
-Zeitwerk works internally only with absolute paths to avoid costly file searches in `$LOAD_PATH`. Indeed, the root directories do not even need to belong to `$LOAD_PATH`, everything just works by design if they don't.
+`Zeitwerk::Loader.for_gem` is a convenience shortcut for the common case in which a gem has its entry point directly under the `lib` directory:
 
-<a id="markdown-reloading" name="reloading"></a>
-### Reloading
+```
+lib/my_gem.rb         # MyGem
+lib/my_gem/version.rb # MyGem::VERSION
+lib/my_gem/foo.rb     # MyGem::Foo
+```
 
-Zeitwerk is able to reload code, but you need to enable this feature:
+Neither a gemspec nor a version file are technically required, this helper works as long as the code is organized using that standard structure.
+
+If the entry point of your gem lives in a subdirectory of `lib` because it is reopening a namespace defined somewhere else, please use the generic API to setup the loader, and make sure you check the section [_Reopening third-party namespaces_](https://github.com/fxn/zeitwerk#reopening-third-party-namespaces) down below.
+
+Conceptually, `for_gem` translates to:
 
 ```ruby
+# lib/my_gem.rb
+
+require "zeitwerk"
 loader = Zeitwerk::Loader.new
-loader.push_dir(...)
-loader.enable_reloading # you need to opt-in before setup
+loader.tag = File.basename(__FILE__, ".rb")
+loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
+loader.push_dir(__dir__)
+```
+
+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.
+
+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:
+
+```ruby
+# lib/my_gem.rb (main file)
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
 loader.setup
-...
-loader.reload
+
+module MyGem
+  # Since the setup has been performed, at this point we are already able
+  # to reference project constants, in this case MyGem::MyLogger.
+  include MyLogger
+end
 ```
 
-There is no way to undo this, either you want to reload or you don't.
+<a id="markdown-autoloading" name="autoloading"></a>
+### Autoloading
 
-Enabling reloading after setup raises `Zeitwerk::Error`. Similarly, calling `reload` without having enabled reloading also raises `Zeitwerk::Error`.
+After `setup`, you are able to reference classes and modules from the project without issuing `require` calls for them. They are all available everywhere, autoloading loads them on demand. This works even if the reference to the class or module is first hit in client code, outside your project.
 
-Generally speaking, reloading is useful while developing running services like web applications. Gems that implement regular libraries, so to speak, or services running in testing or production environments, won't normally have a use case for reloading. If reloading is not enabled, Zeitwerk is able to use less memory.
+Let's revisit the example above:
 
-Reloading removes the currently loaded classes and modules and resets the loader so that it will pick whatever is in the file system now.
+```ruby
+# lib/my_gem.rb (main file)
 
-It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
 
-In order for reloading to be thread-safe, you need to implement some coordination. For example, a web framework that serves each request with its own thread may have a globally accessible RW lock. When a request comes in, the framework acquires the lock for reading at the beginning, and the code in the framework that calls `loader.reload` needs to acquire the lock for writing.
+module MyGem
+  include MyLogger # (*)
+end
+```
 
-On reloading, client code has to update anything that would otherwise be storing a stale object. For example, if the routing layer of a web framework stores controller class objects or instances in internal structures, on reload it has to refresh them somehow, possibly reevaluating routes.
+That works, and there is no `require "my_gem/my_logger"`. When `(*)` is reached, Zeitwerk seamlessly autoloads `MyGem::MyLogger`.
+
+If autoloading a file does not define the expected class or module, Zeitwerk raises `Zeitwerk::NameError`, which is a subclass of `NameError`.
 
 <a id="markdown-eager-loading" name="eager-loading"></a>
 ### Eager loading
@@ -247,8 +323,12 @@ loader.setup
 loader.eager_load # won't eager load the database adapters
 ```
 
+In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](https://github.com/fxn/zeitwerk#synopsis).
+
 Eager loading is synchronized and idempotent.
 
+If eager loading a file does not define the expected class or module, Zeitwerk raises `Zeitwerk::NameError`, which is a subclass of `NameError`.
+
 If you want to eager load yourself and all dependencies using Zeitwerk, you can broadcast the `eager_load` call to all instances:
 
 ```ruby
@@ -259,6 +339,34 @@ This may be handy in top-level services, like web applications.
 
 Note that thanks to idempotence `Zeitwerk::Loader.eager_load_all` won't eager load twice if any of the instances already eager loaded.
 
+<a id="markdown-reloading" name="reloading"></a>
+### Reloading
+
+Zeitwerk is able to reload code, but you need to enable this feature:
+
+```ruby
+loader = Zeitwerk::Loader.new
+loader.push_dir(...)
+loader.enable_reloading # you need to opt-in before setup
+loader.setup
+...
+loader.reload
+```
+
+There is no way to undo this, either you want to reload or you don't.
+
+Enabling reloading after setup raises `Zeitwerk::Error`. Attempting to reload without having it enabled raises `Zeitwerk::ReloadingDisabledError`.
+
+Generally speaking, reloading is useful while developing running services like web applications. Gems that implement regular libraries, so to speak, or services running in testing or production environments, won't normally have a use case for reloading. If reloading is not enabled, Zeitwerk is able to use less memory.
+
+Reloading removes the currently loaded classes and modules and resets the loader so that it will pick whatever is in the file system now.
+
+It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
+
+In order for reloading to be thread-safe, you need to implement some coordination. For example, a web framework that serves each request with its own thread may have a globally accessible RW lock. When a request comes in, the framework acquires the lock for reading at the beginning, and the code in the framework that calls `loader.reload` needs to acquire the lock for writing.
+
+On reloading, client code has to update anything that would otherwise be storing a stale object. For example, if the routing layer of a web framework stores controller class objects or instances in internal structures, on reload it has to refresh them somehow, possibly reevaluating routes.
+
 <a id="markdown-inflection" name="inflection"></a>
 ### Inflection
 
@@ -275,14 +383,34 @@ users_controller -> UsersController
 html_parser      -> HtmlParser
 ```
 
+The camelize logic can be overridden easily for individual basenames:
+
+```ruby
+loader.inflector.inflect(
+  "html_parser"   => "HTMLParser",
+  "mysql_adapter" => "MySQLAdapter"
+)
+```
+
+The `inflect` method can be invoked several times if you prefer this other style:
+
+```ruby
+loader.inflector.inflect "html_parser" => "HTMLParser"
+loader.inflector.inflect "mysql_adapter" => "MySQLAdapter"
+```
+
+Overrides need to be configured before calling `setup`.
+
 There are no inflection rules or global configuration that can affect this inflector. It is deterministic.
 
-This is the default inflector.
+Loaders instantiated with `Zeitwerk::Loader.new` have an inflector of this type, independent of each other.
 
 <a id="markdown-zeitwerkgeminflector" name="zeitwerkgeminflector"></a>
 #### Zeitwerk::GemInflector
 
-The loader instantiated behind the scenes by `Zeitwerk::Loader.for_gem` gets assigned by default an inflector that is like the basic one, except it expects `lib/my_gem/version.rb` to define `MyGem::VERSION`.
+This inflector is like the basic one, except it expects `lib/my_gem/version.rb` to define `MyGem::VERSION`.
+
+Loaders instantiated with `Zeitwerk::Loader.for_gem` have an inflector of this type, independent of each other.
 
 <a id="markdown-custom-inflector" name="custom-inflector"></a>
 #### Custom inflector
@@ -293,12 +421,9 @@ The inflectors that ship with Zeitwerk are deterministic and simple. But you can
 # frozen_string_literal: true
 
 class MyInflector < Zeitwerk::Inflector
-  def camelize(basename, _abspath)
-    case basename
-    when "api"
-      "API"
-    when "mysql_adapter"
-      "MySQLAdapter"
+  def camelize(basename, abspath)
+    if basename =~ /\Ahtml_(.*)/
+      "HTML" + super($1, abspath)
     else
       super
     end
@@ -318,6 +443,49 @@ loader.inflector = MyInflector.new
 
 This needs to be done before calling `setup`.
 
+If a custom inflector definition in a gem takes too much space in the main file, you can extract it. For example, this is a simple pattern:
+
+```ruby
+# lib/my_gem/inflector.rb
+module MyGem
+  class Inflector < Zeitwerk::GemInflector
+    ...
+  end
+end
+
+# lib/my_gem.rb
+require "zeitwerk"
+require_relative "my_gem/inflector"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector = MyGem::Inflector.new(__FILE__)
+loader.setup
+
+module MyGem
+  # ...
+end
+```
+
+Since `MyGem` is referenced before the namespace is defined in the main file, it is important to use this style:
+
+```ruby
+# Correct, effectively defines MyGem.
+module MyGem
+  class Inflector < Zeitwerk::GemInflector
+    # ...
+  end
+end
+```
+
+instead of:
+
+```ruby
+# Raises uninitialized constant MyGem (NameError).
+class MyGem::Inflector < Zeitwerk::GemInflector
+  # ...
+end
+```
+
 <a id="markdown-logging" name="logging"></a>
 ### Logging
 
@@ -486,6 +654,42 @@ Trip = Struct.new { ... } # NOT SUPPORTED
 
 This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
 
+<a id="markdown-reopening-third-party-namespaces" name="reopening-third-party-namespaces"></a>
+### Reopening third-party namespaces
+
+Projects managed by Zeitwerk can work with namespaces defined by third-party libraries. However, they have to be loaded in memory before calling `setup`.
+
+For example, let's imagine you're writing a gem that implements an adapter for [Active Job](https://guides.rubyonrails.org/active_job_basics.html) that uses AwesomeQueue as backend. By convention, your gem has to define a class called `ActiveJob::QueueAdapters::AwesomeQueue`, and it has to do so in a file with a matching path:
+
+```ruby
+# lib/active_job/queue_adapters/awesome_queue.rb
+module ActiveJob
+  module QueueAdapters
+    class AwesomeQueue
+      # ...
+    end
+  end
+end
+```
+
+It is very important that your gem _reopens_ the modules `ActiveJob` and `ActiveJob::QueueAdapters` instead of _defining_ them. Because their proper definition lives in Active Job. Furthermore, if the project reloads, you do not want any of `ActiveJob` or `ActiveJob::QueueAdapters` to be reloaded.
+
+Bottom line, Zeitwerk should not be managing those namespaces. Active Job owns them and defines them. Your gem needs to _reopen_ them.
+
+In order to do so, you need to make sure those modules are loaded before calling `setup`. For instance, in the entry file for the gem:
+
+```ruby
+# Ensure these namespaces are reopened, not defined.
+require "active_job"
+require "active_job/queue_adapters"
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+```
+
+With that, when Zeitwerk scans the file system and reaches the gem directories `lib/active_job` and `lib/active_job/queue_adapters`, it detects the corresponding modules already exist and therefore understands it does not have to manage them. The loader just descends into those directories. Eventually will reach `lib/active_job/queue_adapters/awesome_queue.rb`, and since `ActiveJob::QueueAdapters::AwesomeQueue` is unknown, Zeitwerk will manage it. Which is what happens regularly with the files in your gem. On reload, the namespaces are safe, won't be reloaded. The loader only reloads what it manages, which in this case is the adapter itself.
+
 <a id="markdown-rules-of-thumb" name="rules-of-thumb"></a>
 ### Rules of thumb
 
@@ -501,6 +705,19 @@ This only affects explicit namespaces, those idioms work well for any other ordi
 
 6. In a given process, ideally, there should be at most one loader with reloading enabled. Technically, you can have more, but it may get tricky if one refers to constants managed by the other one. Do that only if you know what you are doing.
 
+<a id="markdown-debuggers" name="debuggers"></a>
+### Debuggers
+
+<a id="markdown-break" name="break"></a>
+#### Break
+
+Zeitwerk works fine with [@gsamokovarov](https://github.com/gsamokovarov)'s [Break](https://github.com/gsamokovarov/break) debugger.
+
+<a id="markdown-byebug" name="byebug"></a>
+#### Byebug
+
+Zeitwerk and [Byebug](https://github.com/deivid-rodriguez/byebug) are incompatible, classes or modules that belong to [explicit namespaces](#explicit-namespaces) are not autoloaded inside a Byebug session. See [this issue](https://github.com/deivid-rodriguez/byebug/issues/564#issuecomment-499413606) for further details.
+
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation
 
@@ -511,6 +728,32 @@ This only affects explicit namespaces, those idioms work well for any other ordi
 
 Zeitwerk works with MRI 2.4.4 and above.
 
+<a id="markdown-testing" name="testing"></a>
+## Testing
+
+In order to run the test suite of Zeitwerk, `cd` into the project root and execute
+
+```
+bin/test
+```
+
+To run one particular suite, pass its file name as an argument:
+
+```
+bin/test test/lib/zeitwerk/test_eager_load.rb
+```
+
+Furthermore, the project has a development dependency on [`minitest-focus`](https://github.com/seattlerb/minitest-focus). To run an individual test mark it with `focus`:
+
+```ruby
+focus
+test "capitalizes the first letter" do
+  assert_equal "User", camelize("user")
+end
+```
+
+and run `bin/test`.
+
 <a id="markdown-motivation" name="motivation"></a>
 ## Motivation
 
@@ -525,6 +768,8 @@ I'd like to thank [@matthewd](https://github.com/matthewd) for the discussions w
 
 Also, would like to thank [@Shopify](https://github.com/Shopify), [@rafaelfranca](https://github.com/rafaelfranca), and [@dylanahsmith](https://github.com/dylanahsmith), for sharing [this PoC](https://github.com/Shopify/autoload_reloader). The technique Zeitwerk uses to support explicit namespaces was copied from that project.
 
+Jean Boussier ([@casperisfine](https://github.com/casperisfine), [@byroot](https://github.com/byroot)) deserves special mention. Jean migrated autoloading in Shopify when Zeitwerk integration in Rails was yet unreleased. His work and positive attitude have been outstanding, and thanks to his feedback the interface and performance of Zeitwerk are way, way better. Kudos man ❤️.
+
 Finally, many thanks to [@schurig](https://github.com/schurig) for recording an [audio file](http://share.hashref.com/zeitwerk/zeitwerk_pronunciation.mp3) with the pronunciation of "Zeitwerk" in perfect German. 💯
 
 <a id="markdown-license" name="license"></a>

data/lib/zeitwerk/gem_inflector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  class GemInflector < Inflector # :nodoc:
+  class GemInflector < Inflector
     # @param root_file [String]
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
@@ -13,7 +13,7 @@ module Zeitwerk
     # @param abspath [String]
     # @return [String]
     def camelize(basename, abspath)
-      (basename == "version" && abspath == @version_file) ? "VERSION" : super
+      abspath == @version_file ? "VERSION" : super
     end
   end
 end

data/lib/zeitwerk/inflector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  class Inflector # :nodoc:
+  class Inflector
     # Very basic snake case -> camel case conversion.
     #
     #   inflector = Zeitwerk::Inflector.new
@@ -9,11 +9,41 @@ module Zeitwerk
     #   inflector.camelize("users_controller", ...) # => "UsersController"
     #   inflector.camelize("api", ...)              # => "Api"
     #
+    # Takes into account hard-coded mappings configured with `inflect`.
+    #
     # @param basename [String]
     # @param _abspath [String]
     # @return [String]
     def camelize(basename, _abspath)
-      basename.split('_').map!(&:capitalize).join
+      overrides[basename] || basename.split('_').map!(&:capitalize).join
+    end
+
+    # Configures hard-coded inflections:
+    #
+    #   inflector = Zeitwerk::Inflector.new
+    #   inflector.inflect(
+    #     "html_parser"   => "HTMLParser",
+    #     "mysql_adapter" => "MySQLAdapter"
+    #   )
+    #
+    #   inflector.camelize("html_parser", abspath)      # => "HTMLParser"
+    #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
+    #   inflector.camelize("users_controller", abspath) # => "UsersController"
+    #
+    # @param inflections [{String => String}]
+    # @return [void]
+    def inflect(inflections)
+      overrides.merge!(inflections)
+    end
+
+    private
+
+    # Hard-coded basename to constant name user maps that override the default
+    # inflection logic.
+    #
+    # @return [{String => String}]
+    def overrides
+      @overrides ||= {}
     end
   end
 end

data/lib/zeitwerk/kernel.rb

@@ -3,6 +3,17 @@
 module Kernel
   module_function
 
+  # We are going to decorate Kerner#require with two goals.
+  #
+  # First, by intercepting Kernel#require calls, we are able to autovivify
+  # modules on required directories, and also do internal housekeeping when
+  # managed files are loaded.
+  #
+  # On the other hand, if you publish a new version of a gem that is now managed
+  # by Zeitwerk, client code can reference directly your classes and modules and
+  # should not require anything. But if someone has legacy require calls around,
+  # they will work as expected, and in a compatible way.
+  #
   # 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.
@@ -30,4 +41,24 @@ module Kernel
       end
     end
   end
+
+  # By now, I have seen no way so far to decorate require_relative.
+  #
+  # For starters, at least in CRuby, require_relative does not delegate to
+  # require. Both require and require_relative delegate the bulk of their work
+  # to an internal C function called rb_require_safe. So, our require wrapper is
+  # not executed.
+  #
+  # On the other hand, we cannot use the aliasing technique above because
+  # require_relative receives a path relative to the directory of the file in
+  # which the call is performed. If a wrapper here invoked the original method,
+  # Ruby would resolve the relative path taking lib/zeitwerk as base directory.
+  #
+  # A workaround could be to extract the base directory from caller_locations,
+  # but what if someone else decorated require_relative before us? You can't
+  # really know with certainty where's the original call site in the stack.
+  #
+  # However, the main use case for require_relative is to load files from your
+  # own project. Projects managed by Zeitwerk don't do this for files managed by
+  # Zeitwerk, precisely.
 end

data/lib/zeitwerk/loader.rb

@@ -39,7 +39,7 @@ module Zeitwerk
     # @return [<String>]
     attr_reader :preloads
 
-    # Absolute paths of files, directories, of glob patterns to be totally
+    # Absolute paths of files, directories, or glob patterns to be totally
     # ignored.
     #
     # @private
@@ -54,6 +54,19 @@ module Zeitwerk
     # @return [Set<String>]
     attr_reader :ignored_paths
 
+    # Absolute paths of directories or glob patterns to be collapsed.
+    #
+    # @private
+    # @return [Set<String>]
+    attr_reader :collapse_glob_patterns
+
+    # The actual collection of absolute directory names at the time the collapse
+    # glob patterns were expanded. Computed on setup, and recomputed on reload.
+    #
+    # @private
+    # @return [Set<String>]
+    attr_reader :collapse_dirs
+
     # Maps real absolute paths for which an autoload has been set ---and not
     # executed--- to their corresponding parent class or module and constant
     # name.
@@ -131,15 +144,17 @@ module Zeitwerk
       @inflector = Inflector.new
       @logger    = self.class.default_logger
 
-      @root_dirs             = {}
-      @preloads              = []
-      @ignored_glob_patterns = Set.new
-      @ignored_paths         = Set.new
-      @autoloads             = {}
-      @autoloaded_dirs       = []
-      @to_unload             = {}
-      @lazy_subdirs          = {}
-      @eager_load_exclusions = Set.new
+      @root_dirs              = {}
+      @preloads               = []
+      @ignored_glob_patterns  = Set.new
+      @ignored_paths          = Set.new
+      @collapse_glob_patterns = Set.new
+      @collapse_dirs          = Set.new
+      @autoloads              = {}
+      @autoloaded_dirs        = []
+      @to_unload              = {}
+      @lazy_subdirs           = {}
+      @eager_load_exclusions  = Set.new
 
       # TODO: find a better name for these mutexes.
       @mutex        = Mutex.new
@@ -154,6 +169,7 @@ module Zeitwerk
 
     # Sets a tag for the loader, useful for logging.
     #
+    # @param tag [#to_s]
     # @return [void]
     def tag=(tag)
       @tag = tag.to_s
@@ -233,6 +249,18 @@ module Zeitwerk
       end
     end
 
+    # Configure directories or glob patterns to be collapsed.
+    #
+    # @param paths [<String, Pathname, <String, Pathname>>]
+    # @return [void]
+    def collapse(*glob_patterns)
+      glob_patterns = expand_paths(glob_patterns)
+      mutex.synchronize do
+        collapse_glob_patterns.merge(glob_patterns)
+        collapse_dirs.merge(expand_glob_patterns(glob_patterns))
+      end
+    end
+
     # Sets autoloads in the root namespace and preloads files, if any.
     #
     # @return [void]
@@ -306,7 +334,8 @@ module Zeitwerk
         Registry.on_unload(self)
         ExplicitNamespace.unregister(self)
 
-        @setup = false
+        @setup        = false
+        @eager_loaded = false
       end
     end
 
@@ -322,6 +351,7 @@ module Zeitwerk
       if reloading_enabled?
         unload
         recompute_ignored_paths
+        recompute_collapse_dirs
         setup
       else
         raise ReloadingDisabledError, "can't reload, please call loader.enable_reloading before setup"
@@ -351,8 +381,12 @@ module Zeitwerk
                 cref[0].const_get(cref[1], false)
               end
             elsif dir?(abspath) && !root_dirs.key?(abspath)
-              cname = inflector.camelize(basename, abspath)
-              queue << [namespace.const_get(cname, false), abspath]
+              if collapse_dirs.member?(abspath)
+                queue << [namespace, abspath]
+              else
+                cname = inflector.camelize(basename, abspath)
+                queue << [namespace.const_get(cname, false), abspath]
+              end
             end
           end
         end
@@ -430,7 +464,7 @@ module Zeitwerk
       #   require "zeitwerk"
       #   loader = Zeitwerk::Loader.new
       #   loader.tag = File.basename(__FILE__, ".rb")
-      #   loader.inflector = Zeitwerk::GemInflector.new
+      #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
       #   loader.push_dir(__dir__)
       #
       # except that this method returns the same object in subsequent calls from
@@ -476,7 +510,7 @@ module Zeitwerk
       ls(dir) do |basename, abspath|
         begin
           if ruby?(basename)
-            basename.slice!(-3, 3)
+            basename[-3..-1] = ''
             cname = inflector.camelize(basename, abspath).to_sym
             autoload_file(parent, cname, abspath)
           elsif dir?(abspath)
@@ -488,13 +522,17 @@ module Zeitwerk
             # it counts only as root. The guard checks that.
             unless root_dirs.key?(abspath)
               cname = inflector.camelize(basename, abspath).to_sym
-              autoload_subdir(parent, cname, abspath)
+              if collapse_dirs.member?(abspath)
+                set_autoloads_in_dir(abspath, parent)
+              else
+                autoload_subdir(parent, cname, abspath)
+              end
             end
           end
         rescue ::NameError => error
           path_type = ruby?(abspath) ? "file" : "directory"
 
-          raise NameError, <<~MESSAGE
+          raise NameError.new(<<~MESSAGE, error.name)
             #{error.message} inferred by #{inflector.class} from #{path_type}
 
               #{abspath}
@@ -558,7 +596,7 @@ module Zeitwerk
     end
 
     # @param dir [String] directory that would have autovivified a module
-    # @param file [String] the file where the namespace is explictly defined
+    # @param file [String] the file where the namespace is explicitly defined
     # @param parent [Module]
     # @param cname [Symbol]
     # @return [void]
@@ -578,7 +616,10 @@ module Zeitwerk
       # $LOADED_FEATURES stores real paths since Ruby 2.4.4. We set and save the
       # real path to be able to delete it from $LOADED_FEATURES on unload, and to
       # be able to do a lookup later in Kernel#require for manual require calls.
-      realpath = File.realpath(abspath)
+      #
+      # We freeze realpath because that saves allocations in Module#autoload.
+      # See #125.
+      realpath = File.realpath(abspath).freeze
       parent.autoload(cname, realpath)
       if logger
         if ruby?(realpath)
@@ -623,8 +664,14 @@ module Zeitwerk
     # @param parent [Module]
     # @param cname [Symbol]
     # @return [String, nil]
-    def strict_autoload_path(parent, cname)
-      parent.autoload?(cname) if cdef?(parent, cname)
+    if method(:autoload?).arity == 1
+      def strict_autoload_path(parent, cname)
+        parent.autoload?(cname) if cdef?(parent, cname)
+      end
+    else
+      def strict_autoload_path(parent, cname)
+        parent.autoload?(cname, false)
+      end
     end
 
     # This method is called this way because I prefer `preload` to be the method
@@ -675,8 +722,13 @@ module Zeitwerk
     def ls(dir)
       Dir.foreach(dir) do |basename|
         next if basename.start_with?(".")
+
         abspath = File.join(dir, basename)
-        yield basename, abspath unless ignored_paths.member?(abspath)
+        next if ignored_paths.member?(abspath)
+
+        # We freeze abspath because that saves allocations when passed later to
+        # File methods. See #125.
+        yield basename, abspath.freeze
       end
     end
 
@@ -711,6 +763,11 @@ module Zeitwerk
       ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
     end
 
+    # @return [void]
+    def recompute_collapse_dirs
+      collapse_dirs.replace(expand_glob_patterns(collapse_glob_patterns))
+    end
+
     # @param message [String]
     # @return [void]
     def log(message)

data/lib/zeitwerk/loader/callbacks.rb

@@ -14,7 +14,7 @@ module Zeitwerk::Loader::Callbacks
     if logger && cdef?(*cref)
       log("constant #{cpath(*cref)} loaded from file #{file}")
     elsif !cdef?(*cref)
-      raise NameError, "expected file #{file} to define constant #{cpath(*cref)}, but didn't"
+      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath(*cref)}, but didn't", cref.last)
     end
   end
 

data/lib/zeitwerk/real_mod_name.rb

@@ -9,7 +9,13 @@ module Zeitwerk::RealModName
   #
   # @param mod [Class, Module]
   # @return [String, nil]
-  def real_mod_name(mod)
-    UNBOUND_METHOD_MODULE_NAME.bind(mod).call
+  if UnboundMethod.method_defined?(:bind_call)
+    def real_mod_name(mod)
+      UNBOUND_METHOD_MODULE_NAME.bind_call(mod)
+    end
+  else
+    def real_mod_name(mod)
+      UNBOUND_METHOD_MODULE_NAME.bind(mod).call
+    end
   end
 end

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,25 +1,26 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.1.10
+  version: 2.3.1
 platform: ruby
 authors:
 - Xavier Noria
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-06 00:00:00.000000000 Z
+date: 2020-06-28 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
       and application may have their own independent autoloader, with its own
-      configuration, inflector, and logger. Supports autoloading, preloading,
+      configuration, inflector, and logger. Supports autoloading,
       reloading, and eager loading.
 email: fxn@hashref.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- MIT-LICENSE
 - README.md
 - lib/zeitwerk.rb
 - lib/zeitwerk/error.rb
@@ -35,7 +36,11 @@ files:
 homepage: https://github.com/fxn/zeitwerk
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/fxn/zeitwerk
+  changelog_uri: https://github.com/fxn/zeitwerk/blob/master/CHANGELOG.md
+  source_code_uri: https://github.com/fxn/zeitwerk
+  bug_tracker_uri: https://github.com/fxn/zeitwerk/issues
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -51,7 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader