zeitwerk 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2af50b4d74832ccd3c08e3445c09a941ed56758c57acd20e8d88436f79e16ea2
-  data.tar.gz: 23f693ca2b9fc44870c26991cd91c587031825e9d29c90dd5285f2c7a3731f6a
+  metadata.gz: b8fd1828e8e92937af8b1e46033442f517c65c07a443a9a265b67c03f22b8b86
+  data.tar.gz: 4e04076d6ac82d1bff9bf3db8604ca7e826afad753fb1268116cd115f15d301b
 SHA512:
-  metadata.gz: 1d47e1a735c5314ec56f9c16d66695222209109dddb7da3a663969b852295eed82d8eee56fc48a48cb6b0604e508940f474533e98c7d824175c344420a64baec
-  data.tar.gz: be275743889771c745fc90d300a4cbd01911b5b4547c41ea1df6429af1357b9328fb69293a03a282677295f27528220f180f1ca943f43b5567677b856baa3e06
+  metadata.gz: cacd0d2c43a566a5e3be7dfb98585e9598a9fda8e930bb0f97a96180db332d6303fb1cfbf850f85dd822071968fc624262b94c27db85ad3e1236f1e243df64c2
+  data.tar.gz: 0f9c90d543eae10edade4777f63c02a0f5ef30ecfdfe752fc9f11e5f6e3c835d2b893b0e8074e4cd068859e41dcf6e5374527c73499876deab3a9974cd0d2bf4

data/README.md

@@ -12,11 +12,13 @@
 - [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)
+    - [Autoloading](#autoloading)
     - [Eager loading](#eager-loading)
+    - [Reloading](#reloading)
     - [Inflection](#inflection)
         - [Zeitwerk::Inflector](#zeitwerkinflector)
         - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
@@ -32,6 +34,7 @@
     - [Autoloading, explicit namespaces, and debuggers](#autoloading-explicit-namespaces-and-debuggers)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
+- [Testing](#testing)
 - [Motivation](#motivation)
 - [Thanks](#thanks)
 - [License](#license)
@@ -163,6 +166,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
 
@@ -218,33 +247,28 @@ end
 
 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.
 
-<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
-```
+<a id="markdown-autoloading" name="autoloading"></a>
+### Autoloading
 
-There is no way to undo this, either you want to reload or you don't.
+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.
 
-Enabling reloading after setup raises `Zeitwerk::Error`. Similarly, calling `reload` without having enabled reloading also raises `Zeitwerk::Error`.
+Let's revisit the example above:
 
-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.
+```ruby
+# lib/my_gem.rb (main file)
 
-Reloading removes the currently loaded classes and modules and resets the loader so that it will pick whatever is in the file system now.
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
 
-It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
+module MyGem
+  include MyLogger # (*)
+end
+```
 
-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.
+That works, and there is no `require "my_gem/my_logger"`. When `(*)` is reached, Zeitwerk seamlessly autoloads `MyGem::MyLogger`.
 
-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.
+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
@@ -268,6 +292,8 @@ In gems, the method needs to be invoked after the main namespace has been define
 
 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
@@ -278,6 +304,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
 
@@ -599,6 +653,32 @@ As a workaround, you can eager load. Zeitwerk tries hard to succeed or fail cons
 
 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
 
@@ -613,6 +693,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/inflector.rb

@@ -28,7 +28,7 @@ module Zeitwerk
     #
     #   inflector.camelize("html_parser", abspath)      # => "HTMLParser"
     #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
-    #   inflector.camelize("users_controller", abspath) # => "PostsController"
+    #   inflector.camelize("users_controller", abspath) # => "UsersController"
     #
     # @param inflections [{String => String}]
     # @return [void]

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/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
@@ -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]
@@ -623,8 +661,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
@@ -711,6 +755,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/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.2.0"
+  VERSION = "2.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Xavier Noria
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-09 00:00:00.000000000 Z
+date: 2020-03-03 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem