zeitwerk 2.1.5 → 2.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e89de8ad7897a95ccc14f71e1688eb826c7e01f2c0c9381e09de5dd8815d1974
-  data.tar.gz: 11bf19ab1b396399afc3110e8122cb783d2a2d64a889fa5ac7e506e65a8cc9be
+  metadata.gz: 2cf7265c8e1a167cdf0107bdef2643d219317855b0f5a06b77048672e3a192a3
+  data.tar.gz: d1429158609c03b57f85b261290e61d88c7762f02693232336a0f4eb94bc7417
 SHA512:
-  metadata.gz: b9a3e74bde3eec64186834b010f3c047d0b1c849a95c89747c6195b3a5fef974d4b1018cf4fca64a46e27aa5768c543d73b6203af80b170c20dab108544833e0
-  data.tar.gz: 2055af7e3b74fa7c6c3e0c1e7dc6bb1888736c5d8204106ed0504b83a3cba74f7db2a24a72a0e2afc995cf780d4ebcd5965c74262150bb9c90fc3abf4ae97310
+  metadata.gz: 3457b0e4afeb1e134db7815e538c8251aab11bda9b9feb8eec07257506786693f9f9ec0c0eb7a11c0663502f48778b37939cb47483d84b369ed82830518ff78a
+  data.tar.gz: 4996a053629f48004cb4c86f24a649295baaf1afbde0a2a5b5be0c3163205376659382ac3a9322586e2b86fee200c8bf97c5bb8faa2ae17c19aa0b169457af09

data/README.md

@@ -29,6 +29,7 @@
         - [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)
+    - [Rules of thumb](#rules-of-thumb)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
 - [Motivation](#motivation)
@@ -42,15 +43,13 @@
 
 Zeitwerk is an efficient and thread-safe code loader for Ruby.
 
-Given a conventional file structure, Zeitwerk loads your project's classes and modules on demand. You don't need to write `require` calls for your own files, rather, you can streamline your programming knowing that your classes and modules are available everywhere. This feature is efficient, thread-safe, and matches Ruby's semantics for constants.
+Given a [conventional file structure](#file-structure), Zeitwerk is able to load your project's classes and modules on demand (autoloading), or upfront (eager loading). You don't need to write `require` calls for your own files, rather, you can streamline your programming knowing that your classes and modules are available everywhere. This feature is efficient, thread-safe, and matches Ruby's semantics for constants.
 
-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, by design, Zeitwerk does only one single scan of the project tree, and it descends into subdirectories lazily, only if their namespaces are used.
+Zeitwerk is also able to reload code, which may be handy while developing web applications. Coordination is needed to reload in a thread-safe manner. The documentation below explains how to do this.
 
-The library is designed so that each gem and application can have their own loader, independent of each other. Each loader has its own configuration, inflector, and optional logger.
+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.
 
-Zeitwerk is also able to reload code, which may be handy for web applications. Coordination is needed to reload in a thread-safe manner. The documentation below explains how to do this.
-
-Finally, in some production setups it may be optimal to eager load all code upfront. Zeitwerk is able to do that too.
+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.
 
 <a id="markdown-synopsis" name="synopsis"></a>
 ## Synopsis
@@ -62,8 +61,8 @@ Main interface for gems:
 
 require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
-loader.setup # ready!
-# loader.eager_load, optionally
+loader.setup      # ready!
+loader.eager_load # optionally
 
 module MyGem
   # ...
@@ -205,7 +204,7 @@ Zeitwerk works internally only with absolute paths to avoid costly file searches
 <a id="markdown-reloading" name="reloading"></a>
 ### Reloading
 
-Zeitwer is able to reload code, but you need to enable this feature:
+Zeitwerk is able to reload code, but you need to enable this feature:
 
 ```ruby
 loader = Zeitwerk::Loader.new
@@ -338,7 +337,15 @@ This needs to be done before calling `setup`.
 <a id="markdown-logging" name="logging"></a>
 ### Logging
 
-Zeitwerk is silent by default, but you can configure a callable as logger:
+Zeitwerk is silent by default, but you can ask loaders to trace their activity. Logging is meant just for troubleshooting, shouldn't normally be enabled.
+
+The `log!` method is a quick shortcut to let the loader log to `$stdout`:
+
+```
+loader.log!
+```
+
+If you want more control, a logger can be configured as a callable
 
 ```ruby
 loader.logger = method(:puts)
@@ -493,6 +500,21 @@ Trip = Struct.new { ... } # NOT SUPPORTED
 
 This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
 
+<a id="markdown-rules-of-thumb" name="rules-of-thumb"></a>
+### Rules of thumb
+
+1. Different loaders should manage different directory trees. It is an error condition to configure overlapping root directories in different loaders.
+
+2. Think the mere existence of a file is effectively like writing a `require` call for them, which is executed on demand (autoload) or upfront (eager load).
+
+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.
+
+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.
+
+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-pronunciation" name="pronunciation"></a>
 ## Pronunciation
 

data/lib/zeitwerk/gem_inflector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  class GemInflector < Inflector
+  class GemInflector < Inflector # :nodoc:
     # @param root_file [String]
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")

data/lib/zeitwerk/inflector.rb

@@ -13,7 +13,7 @@ module Zeitwerk
     # @param _abspath [String]
     # @return [String]
     def camelize(basename, _abspath)
-      basename.split('_').map!(&:capitalize!).join
+      basename.split('_').map!(&:capitalize).join
     end
   end
 end

data/lib/zeitwerk/loader.rb

@@ -342,16 +342,20 @@ module Zeitwerk
         break if @eager_loaded
 
         queue = actual_root_dirs.reject { |dir| eager_load_exclusions.member?(dir) }
-        while dir = queue.shift
-          const_get_if_autoload(dir)
+        queue.map! { |dir| [Object, dir] }
+        while to_eager_load = queue.shift
+          namespace, dir = to_eager_load
 
-          each_abspath(dir) do |abspath|
+          ls(dir) do |basename, abspath|
             next if eager_load_exclusions.member?(abspath)
 
             if ruby?(abspath)
-              const_get_if_autoload(abspath)
+              if cref = autoloads[File.realpath(abspath)]
+                cref[0].const_get(cref[1], false)
+              end
             elsif dir?(abspath)
-              queue << abspath
+              cname = inflector.camelize(basename, abspath)
+              queue << [namespace.const_get(cname, false), abspath]
             end
           end
         end
@@ -391,6 +395,13 @@ module Zeitwerk
       to_unload.keys.freeze
     end
 
+    # Logs to `$stdout`, handy shortcut for debugging.
+    #
+    # @return [void]
+    def log!
+      @logger = ->(msg) { puts msg }
+    end
+
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
@@ -414,7 +425,7 @@ module Zeitwerk
       #
       # @return [Zeitwerk::Loader]
       def for_gem
-        called_from = caller_locations.first.path
+        called_from = caller_locations(1, 1).first.path
         Registry.loader_for_gem(called_from)
       end
 
@@ -449,9 +460,10 @@ module Zeitwerk
     # @param parent [Module]
     # @return [void]
     def set_autoloads_in_dir(dir, parent)
-      each_abspath(dir) do |abspath|
-        cname = inflector.camelize(File.basename(abspath, ".rb"), abspath).to_sym
-        if ruby?(abspath)
+      ls(dir) do |basename, abspath|
+        if ruby?(basename)
+          basename.slice!(-3, 3)
+          cname = inflector.camelize(basename, abspath).to_sym
           autoload_file(parent, cname, abspath)
         elsif dir?(abspath)
           # In a Rails application, `app/models/concerns` is a subdirectory of
@@ -460,7 +472,10 @@ module Zeitwerk
           # To resolve the ambiguity file name -> constant path this introduces,
           # the `app/models/concerns` directory is totally ignored as a namespace,
           # it counts only as root. The guard checks that.
-          autoload_subdir(parent, cname, abspath) unless root_dirs.key?(abspath)
+          unless root_dirs.key?(abspath)
+            cname = inflector.camelize(basename, abspath).to_sym
+            autoload_subdir(parent, cname, abspath)
+          end
         end
       end
     end
@@ -605,7 +620,7 @@ module Zeitwerk
     # @param dir [String]
     # @return [void]
     def do_preload_dir(dir)
-      each_abspath(dir) do |abspath|
+      ls(dir) do |_basename, abspath|
         do_preload_abspath(abspath)
       end
     end
@@ -625,13 +640,13 @@ module Zeitwerk
     end
 
     # @param dir [String]
-    # @yieldparam path [String]
+    # @yieldparam path [String, String]
     # @return [void]
-    def each_abspath(dir)
-      Dir.foreach(dir) do |entry|
-        next if entry.start_with?(".")
-        abspath = File.join(dir, entry)
-        yield abspath unless ignored_paths.member?(abspath)
+    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)
       end
     end
 
@@ -664,12 +679,6 @@ module Zeitwerk
       parent.const_defined?(cname, false)
     end
 
-    def const_get_if_autoload(abspath)
-      if cref = autoloads[File.realpath(abspath)]
-        cref[0].const_get(cref[1], false)
-      end
-    end
-
     def register_explicit_namespace(cpath)
       ExplicitNamespace.register(cpath, self)
     end

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.1.5
+  version: 2.1.7
 platform: ruby
 authors:
 - Xavier Noria
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-24 00:00:00.000000000 Z
+date: 2019-06-28 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -50,7 +50,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.1
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader