zeitwerk 2.4.0 → 2.5.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 682fa352a9d6d4bf68d07cf2cbfbb539de3cfec4e8af2f930894ab27c707ca93
-  data.tar.gz: 1e7ce6157e6046cdb60f0f1b531f1f39fb97cad3537392114be5cf84dae672c9
+  metadata.gz: 64ea17faefd07265c96bd8c49c9a4e14170612f85f868c03df91aa4511e473e3
+  data.tar.gz: fb98b0f841e49016039d73310d50563e8e6c3bbcf4c16f2d4441b241cb266647
 SHA512:
-  metadata.gz: e308baba1a8fbe4d7c64d7195c753d795a53caefa7264d2404117cb620f2081f6b0fc05c056dafb035b44430102e4472b7eb9fb3a4fd9d70aa124b7f9a3a8313
-  data.tar.gz: 5139d5abaeed86e256493b592460b13b19fd7602f7c099f7017b55af9f16a91429e84074a4e31fe79bf28235e02cbba3055cc4bda579bbc7de2a391c5997a393
+  metadata.gz: 3dfdc023489a4b7306c2bbac6f56234ff4a80887820967ff691fd9b13609ea256ba5bca301870d5e5b35d26c09ece01158a984d3093fa63d0de0bd3d9cdff458
+  data.tar.gz: 4860a04e9e489251ce43e56f37c7213ac3dda7c301f9dff1826d7e5f2567b992bfac35f645dab67a356bb8a4024c29d0fd8431f91896f7a254bf747864dd8ef0

data/README.md

@@ -3,40 +3,48 @@
 
 
 [![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/master?style=for-the-badge)](https://travis-ci.com/fxn/zeitwerk)
+[![Build Status](https://img.shields.io/github/workflow/status/fxn/zeitwerk/CI?event=push&style=for-the-badge)](https://github.com/fxn/zeitwerk/actions?query=event%3Apush)
 
 <!-- TOC -->
 
 - [Introduction](#introduction)
 - [Synopsis](#synopsis)
 - [File structure](#file-structure)
-    - [Implicit namespaces](#implicit-namespaces)
-    - [Explicit namespaces](#explicit-namespaces)
-    - [Collapsing directories](#collapsing-directories)
+  - [The idea: File paths match constant paths](#the-idea-file-paths-match-constant-paths)
+  - [Inner simple constants](#inner-simple-constants)
+  - [Root directories and root namespaces](#root-directories-and-root-namespaces)
+    - [The default root namespace is `Object`](#the-default-root-namespace-is-object)
+    - [Custom root namespaces](#custom-root-namespaces)
     - [Nested root directories](#nested-root-directories)
+  - [Implicit namespaces](#implicit-namespaces)
+  - [Explicit namespaces](#explicit-namespaces)
+  - [Collapsing directories](#collapsing-directories)
 - [Usage](#usage)
-    - [Setup](#setup)
-        - [Generic](#generic)
-        - [for_gem](#for_gem)
-    - [Autoloading](#autoloading)
-    - [Eager loading](#eager-loading)
-    - [Reloading](#reloading)
-    - [Inflection](#inflection)
-        - [Zeitwerk::Inflector](#zeitwerkinflector)
-        - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
-        - [Custom inflector](#custom-inflector)
-    - [Logging](#logging)
-        - [Loader tag](#loader-tag)
-    - [Ignoring parts of the project](#ignoring-parts-of-the-project)
-        - [Use case: Files that do not follow the conventions](#use-case-files-that-do-not-follow-the-conventions)
-        - [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)
+  - [Setup](#setup)
+    - [Generic](#generic)
+    - [for_gem](#for_gem)
+  - [Autoloading](#autoloading)
+  - [Eager loading](#eager-loading)
+  - [Reloading](#reloading)
+  - [Inflection](#inflection)
+    - [Zeitwerk::Inflector](#zeitwerkinflector)
+    - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
+    - [Custom inflector](#custom-inflector)
+  - [The on_load callback](#the-on_load-callback)
+  - [The on_unload callback](#the-on_unload-callback)
+    - [Technical details](#technical-details)
+  - [Logging](#logging)
+    - [Loader tag](#loader-tag)
+  - [Ignoring parts of the project](#ignoring-parts-of-the-project)
+    - [Use case: Files that do not follow the conventions](#use-case-files-that-do-not-follow-the-conventions)
+    - [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)
@@ -116,6 +124,9 @@ Zeitwerk::Loader.eager_load_all
 <a id="markdown-file-structure" name="file-structure"></a>
 ## File structure
 
+<a id="markdown-the-idea-file-paths-match-constant-paths" name="the-idea-file-paths-match-constant-paths"></a>
+### The idea: File paths match constant paths
+
 To have a file structure Zeitwerk can work with, just name files and directories after the name of the classes and modules they define:
 
 ```
@@ -125,25 +136,57 @@ lib/my_gem/bar_baz.rb -> MyGem::BarBaz
 lib/my_gem/woo/zoo.rb -> MyGem::Woo::Zoo
 ```
 
-Every directory configured with `push_dir` acts as root namespace. There can be several of them. For example, given
+You can tune that a bit by [collapsing directories](#collapsing-directories), or by [ignoring parts of the project](#ignoring-parts-of-the-project), but that is the main idea.
+
+<a id="markdown-inner-simple-constants" name="inner-simple-constants"></a>
+### Inner simple constants
+
+While a simple constant like `HttpCrawler::MAX_RETRIES` can be defined in its own file:
 
 ```ruby
-loader.push_dir(Rails.root.join("app/models"))
-loader.push_dir(Rails.root.join("app/controllers"))
+# http_crawler/max_retries.rb
+HttpCrawler::MAX_RETRIES = 10
 ```
 
-Zeitwerk understands that their respective files and subdirectories belong to the root namespace:
+that is not required, you can also define it the regular way:
 
+```ruby
+# http_crawler.rb
+class HttpCrawler
+  MAX_RETRIES = 10
+end
 ```
-app/models/user.rb                        -> User
-app/controllers/admin/users_controller.rb -> Admin::UsersController
+
+<a id="markdown-root-directories-and-root-namespaces" name="root-directories-and-root-namespaces"></a>
+### Root directories and root namespaces
+
+Every directory configured with `push_dir` is called a _root directory_, and they represent _root namespaces_.
+
+<a id="markdown-the-default-root-namespace-is-object" name="the-default-root-namespace-is-object"></a>
+#### The default root namespace is `Object`
+
+By default, the namespace associated to a root directory is the top-level one: `Object`.
+
+For example, given
+
+```ruby
+loader.push_dir("#{__dir__}/models")
+loader.push_dir("#{__dir__}/serializers"))
 ```
 
-Alternatively, you can associate a custom namespace to a root directory by passing a class or module object in the optional `namespace` keyword argument.
+these are the expected classes and modules being defined by these files:
 
-For example, Active Job queue adapters have to define a constant after their name in `ActiveJob::QueueAdapters`.
+```
+models/user.rb                 -> User
+serializers/user_serializer.rb -> UserSerializer
+```
+
+<a id="markdown-custom-root-namespaces" name="custom-root-namespaces"></a>
+#### Custom root namespaces
+
+While `Object` is by far the most common root namespace, you can associate a different one to a particular root directory. The method `push_dir` accepts a class or module object in the optional `namespace` keyword argument.
 
-So, if you declare
+For example, given:
 
 ```ruby
 require "active_job"
@@ -151,9 +194,26 @@ require "active_job/queue_adapters"
 loader.push_dir("#{__dir__}/adapters", namespace: ActiveJob::QueueAdapters)
 ```
 
-your adapter can be stored directly in that directory instead of the canonical `lib/active_job/queue_adapters`.
+a file defining `ActiveJob::QueueAdapters::MyQueueAdapter` does not need the conventional parent directories, you can (and have to) store the file directly below `adapters`:
+
+```
+adapters/my_queue_adapter.rb -> ActiveJob::QueueAdapters::MyQueueAdapter
+```
 
-Please, note that the given namespace must be non-reloadable, though autoloaded constants in that namespace can be. That is, if you associate `app/api` with an existing `Api` module, that module should not be reloadable. However, if the project defines and autoloads the class `Api::V2::Deliveries`, that one can be reloaded.
+Please, note that the given root namespace must be non-reloadable, though autoloaded constants in that namespace can be. That is, if you associate `app/api` with an existing `Api` module, that module should not be reloadable. However, if the project defines and autoloads the class `Api::Deliveries`, that one can be reloaded.
+
+<a id="markdown-nested-root-directories" name="nested-root-directories"></a>
+#### Nested root directories
+
+Root directories should not be ideally nested, but Zeitwerk supports them because in Rails, for example, both `app/models` and `app/models/concerns` belong to the autoload paths.
+
+Zeitwerk detects nested root directories, and treats them as roots only. In the example above, `concerns` is not considered to be a namespace below `app/models`. For example, the file:
+
+```
+app/models/concerns/geolocatable.rb
+```
+
+should define `Geolocatable`, not `Concerns::Geolocatable`.
 
 <a id="markdown-implicit-namespaces" name="implicit-namespaces"></a>
 ### Implicit namespaces
@@ -202,7 +262,7 @@ booking/actions/create.rb -> Booking::Create
 To make it work that way, configure Zeitwerk to collapse said directory:
 
 ```ruby
-loader.collapse("booking/actions")
+loader.collapse("#{__dir__}/booking/actions")
 ```
 
 This method accepts an arbitrary number of strings or `Pathname` objects, and also an array of them.
@@ -212,22 +272,9 @@ You can pass directories and glob patterns. Glob patterns are expanded when they
 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")
+loader.collapse("#{__dir__}/*/actions")
 ```
 
-<a id="markdown-nested-root-directories" name="nested-root-directories"></a>
-### Nested root directories
-
-Root directories should not be ideally nested, but Zeitwerk supports them because in Rails, for example, both `app/models` and `app/models/concerns` belong to the autoload paths.
-
-Zeitwerk detects nested root directories, and treats them as roots only. In the example above, `concerns` is not considered to be a namespace below `app/models`. For example, the file:
-
-```
-app/models/concerns/geolocatable.rb
-```
-
-should define `Geolocatable`, not `Concerns::Geolocatable`.
-
 <a id="markdown-usage" name="usage"></a>
 ## Usage
 
@@ -386,11 +433,13 @@ On reloading, client code has to update anything that would otherwise be storing
 <a id="markdown-inflection" name="inflection"></a>
 ### Inflection
 
-Each individual loader needs an inflector to figure out which constant path would a given file or directory map to. Zeitwerk ships with two basic inflectors.
+Each individual loader needs an inflector to figure out which constant path would a given file or directory map to. Zeitwerk ships with two basic inflectors, and you can define your own.
 
 <a id="markdown-zeitwerkinflector" name="zeitwerkinflector"></a>
 #### Zeitwerk::Inflector
 
+Each loader instantiated with `Zeitwerk::Loader.new` has an inflector of this type by default.
+
 This is a very basic inflector that converts snake case to camel case:
 
 ```
@@ -417,16 +466,16 @@ 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.
-
-Loaders instantiated with `Zeitwerk::Loader.new` have an inflector of this type, independent of each other.
+ 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-zeitwerkgeminflector" name="zeitwerkgeminflector"></a>
 #### Zeitwerk::GemInflector
 
+Each loader instantiated with `Zeitwerk::Loader.for_gem` has an inflector of this type by default.
+
 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.
+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-custom-inflector" name="custom-inflector"></a>
 #### Custom inflector
@@ -502,6 +551,109 @@ class MyGem::Inflector < Zeitwerk::GemInflector
 end
 ```
 
+<a id="markdown-the-on_load-callback" name="the-on_load-callback"></a>
+### The on_load callback
+
+The usual place to run something when a file is loaded is the file itself. However, sometimes you'd like to be called, and this is possible with the `on_load` callback.
+
+For example, let's imagine this class belongs to a Rails application:
+
+```ruby
+class SomeApiClient
+  class << self
+    attr_accessor :endpoint
+  end
+end
+```
+
+With `on_load`, it is easy to schedule code at boot time that initializes `endpoint` according to the configuration:
+
+```ruby
+# config/environments/development.rb
+loader.on_load("SomeApiClient") do |klass, _abspath|
+  klass.endpoint = "https://api.dev"
+end
+
+# config/environments/production.rb
+loader.on_load("SomeApiClient") do |klass, _abspath|
+  klass.endpoint = "https://api.prod"
+end
+```
+
+Some uses cases:
+
+* Doing something with a reloadable class or module in a Rails application during initialization, in a way that plays well with reloading. As in the previous example.
+* Delaying the execution of the block until the class is loaded for performance.
+* Delaying the execution of the block until the class is loaded because it follows the adapter pattern and better not to load the class if the user does not need it.
+
+`on_load` gets a target constant path as a string (e.g., "User", or "Service::NotificationsGateway"). When fired, its block receives the stored value, and the absolute path to the corresponding file or directory as a string. The callback is executed every time the target is loaded. That includes reloads.
+
+Multiple callbacks on the same target are supported, and they run in order of definition.
+
+The block is executed once the loader has loaded the target. In particular, if the target was already loaded when the callback is defined, the block won't run. But if you reload and load the target again, then it will. Normally, you'll want to define `on_load` callbacks before `setup`.
+
+Defining a callback for a target not managed by the receiver is not an error, the block simply won't ever be executed.
+
+It is also possible to be called when any constant managed by the loader is loaded:
+
+```ruby
+loader.on_load do |cpath, value, abspath|
+  # ...
+end
+```
+
+The block gets the constant path as a string (e.g., "User", or "Foo::VERSION"), the value it stores (e.g., the class object stored in `User`, or "2.5.0"), and the absolute path to the corresponding file or directory as a string.
+
+Multiple callbacks like these are supported, and they run in order of definition.
+
+There are use cases for this last catch-all callback, but they are rare. If you just need to understand how things are being loaded for debugging purposes, please remember that `Zeitwerk::Loader#log!` logs plenty of information.
+
+If both types of callbacks are defined, the specific ones run first.
+
+<a id="markdown-the-on_unload-callback" name="the-on_unload-callback"></a>
+### The on_unload callback
+
+When reloading is enabled, you may occasionally need to execute something before a certain autoloaded class or module is unloaded. The `on_unload` callback allows you to do that.
+
+For example, let's imagine that a `Country` class fetches a list of countries and caches them when it is loaded. You might want to clear that cache if unloaded:
+
+```ruby
+loader.on_unload("Country") do |klass, _abspath|
+  klass.clear_cache
+end
+```
+
+`on_unload` gets a target constant path as a string (e.g., "User", or "Service::NotificationsGateway"). When fired, its block receives the stored value, and the absolute path to the corresponding file or directory as a string. The callback is executed every time the target is unloaded.
+
+`on_unload` blocks are executed before the class is unloaded, but in the middle of unloading, which happens in an unspecified order. Therefore, **that callback should not refer to any reloadable constant because there is no guarantee the constant works there**. Those blocks should rely on objects only, as in the example above, or regular constants not managed by the loader. This remark is transitive, applies to any methods invoked within the block.
+
+Multiple callbacks on the same target are supported, and they run in order of definition.
+
+Defining a callback for a target not managed by the receiver is not an error, the block simply won't ever be executed.
+
+It is also possible to be called when any constant managed by the loader is unloaded:
+
+```ruby
+loader.on_unload do |cpath, value, abspath|
+  # ...
+end
+```
+
+The block gets the constant path as a string (e.g., "User", or "Foo::VERSION"), the value it stores (e.g., the class object stored in `User`, or "2.5.0"), and the absolute path to the corresponding file or directory as a string.
+
+Multiple callbacks like these are supported, and they run in order of definition.
+
+If both types of callbacks are defined, the specific ones run first.
+
+<a id="markdown-technical-details" name="technical-details"></a>
+#### Technical details
+
+Zeitwerk uses the word "unload" to ease communication and for symmetry with `on_load`. However, in Ruby you cannot unload things for real. So, when does `on_unload` technically happen?
+
+When unloading, Zeitwerk issues `Module#remove_const` calls. Classes and modules are no longer reachable through their constants, and `on_unload` callbacks are executed right before those calls.
+
+Technically, though, the objects themselves are still alive, but if everything is used as expected and they are not stored in any non-reloadable place (don't do that), they are ready for garbage collection, which is when the real unloading happens.
+
 <a id="markdown-logging" name="logging"></a>
 ### Logging
 

data/lib/zeitwerk.rb

@@ -3,10 +3,23 @@
 module Zeitwerk
   require_relative "zeitwerk/real_mod_name"
   require_relative "zeitwerk/loader"
+  require_relative "zeitwerk/autoloads"
   require_relative "zeitwerk/registry"
   require_relative "zeitwerk/explicit_namespace"
   require_relative "zeitwerk/inflector"
   require_relative "zeitwerk/gem_inflector"
   require_relative "zeitwerk/kernel"
   require_relative "zeitwerk/error"
+  require_relative "zeitwerk/version"
+
+  # This is a dangerous method.
+  #
+  # @experimental
+  # @sig () -> void
+  def self.with_loader
+    loader = Zeitwerk::Loader.new
+    yield loader
+  ensure
+    loader.unregister
+  end
 end

data/lib/zeitwerk/autoloads.rb

@@ -0,0 +1,69 @@
+module Zeitwerk
+  # @private
+  class Autoloads
+    # Maps crefs for which an autoload has been defined to the corresponding
+    # absolute path.
+    #
+    #   [Object, :User]  => "/Users/fxn/blog/app/models/user.rb"
+    #   [Object, :Hotel] => "/Users/fxn/blog/app/models/hotel"
+    #   ...
+    #
+    # This colection is transient, callbacks delete its entries as autoloads get
+    # executed.
+    #
+    # @sig Hash[[Module, Symbol], String]
+    attr_reader :c2a
+
+    # This is the inverse of c2a, for inverse lookups.
+    #
+    # @sig Hash[String, [Module, Symbol]]
+    attr_reader :a2c
+
+    # @sig () -> void
+    def initialize
+      @c2a = {}
+      @a2c = {}
+    end
+
+    # @sig (Module, Symbol, String) -> void
+    def define(parent, cname, abspath)
+      parent.autoload(cname, abspath)
+      cref = [parent, cname]
+      c2a[cref] = abspath
+      a2c[abspath] = cref
+    end
+
+    # @sig () { () -> [[Module, Symbol], String] } -> void
+    def each(&block)
+      c2a.each(&block)
+    end
+
+    # @sig (Module, Symbol) -> String?
+    def abspath_for(parent, cname)
+      c2a[[parent, cname]]
+    end
+
+    # @sig (String) -> [Module, Symbol]?
+    def cref_for(abspath)
+      a2c[abspath]
+    end
+
+    # @sig (String) -> [Module, Symbol]?
+    def delete(abspath)
+      cref = a2c.delete(abspath)
+      c2a.delete(cref)
+      cref
+    end
+
+    # @sig () -> void
+    def clear
+      c2a.clear
+      a2c.clear
+    end
+
+    # @sig () -> bool
+    def empty?
+      c2a.empty? && a2c.empty?
+    end
+  end
+end