zeitwerk 2.1.6 → 2.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43750607caaaa5d4fff5bd52204cafb98fbd5109b51a24d9099ba83c6a2a4990
-  data.tar.gz: 8ad3251fd93af9e66a9102c13556beff5805a38660d69e4c5de37e2808e76d8f
+  metadata.gz: 2cf7265c8e1a167cdf0107bdef2643d219317855b0f5a06b77048672e3a192a3
+  data.tar.gz: d1429158609c03b57f85b261290e61d88c7762f02693232336a0f4eb94bc7417
 SHA512:
-  metadata.gz: e6e87877104078f564686a15b81882a8e20a560a36999e0f8b9916aa520dd46fe1a2b7f65cacdb7b6c62d252472b6ce1370939054f026a335e21652881820814
-  data.tar.gz: 3641d412ab4b9176861b9ed9b28ea7964b6a814ebb72804c96967e511562fb87f424c48d7780345be8ccd2c53bdacfe095e3e5173e166a4185bf389740258ca6
+  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
@@ -340,7 +339,7 @@ This needs to be done before calling `setup`.
 
 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!` mehtod is a quick shortcut to let the loader log to `$stdout`:
+The `log!` method is a quick shortcut to let the loader log to `$stdout`:
 
 ```
 loader.log!
@@ -501,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

@@ -53,23 +53,6 @@ module Zeitwerk
     # @return [Set<String>]
     attr_reader :ignored_paths
 
-    # A _shadowed file_ is a file managed by this loader that is ignored when
-    # setting autoloads because its matching constant is taken. Either the
-    # constant is already defined, or there exists an autoload for it.
-    #
-    # Think $LOAD_PATH and require, only the first occurrence of a given
-    # relative name is loaded.
-    #
-    # This set keeps track of the absolute path of shadowed files, to be able to
-    # skip them while eager loading.
-    #
-    # Note this cannot be implemented with do_not_eager_load because these
-    # files are not autoloadable.
-    #
-    # @private
-    # @return [Set<String>]
-    attr_reader :shadowed_files
-
     # Maps real absolute paths for which an autoload has been set ---and not
     # executed--- to their corresponding parent class or module and constant
     # name.
@@ -155,7 +138,6 @@ module Zeitwerk
       @autoloaded_dirs       = []
       @to_unload             = {}
       @lazy_subdirs          = {}
-      @shadowed_files        = Set.new
       @eager_load_exclusions = Set.new
 
       # TODO: find a better name for these mutexes.
@@ -324,7 +306,6 @@ module Zeitwerk
         autoloaded_dirs.clear
         to_unload.clear
         lazy_subdirs.clear
-        shadowed_files.clear
 
         Registry.on_unload(self)
         ExplicitNamespace.unregister(self)
@@ -361,20 +342,24 @@ module Zeitwerk
         break if @eager_loaded
 
         queue = actual_root_dirs.reject { |dir| eager_load_exclusions.member?(dir) }
-        while dir = queue.shift
-          ls(dir) do |_basename, abspath|
+        queue.map! { |dir| [Object, dir] }
+        while to_eager_load = queue.shift
+          namespace, dir = to_eager_load
+
+          ls(dir) do |basename, abspath|
             next if eager_load_exclusions.member?(abspath)
 
             if ruby?(abspath)
-              require abspath unless shadowed_files.member?(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
 
-        shadowed_files.clear
-
         autoloaded_dirs.each do |autoloaded_dir|
           Registry.unregister_autoload(autoloaded_dir)
         end
@@ -526,7 +511,6 @@ module Zeitwerk
       if autoload_path = autoload_for?(parent, cname)
         # First autoload for a Ruby file wins, just ignore subsequent ones.
         if ruby?(autoload_path)
-          shadowed_files.add(file)
           log("file #{file} is ignored because #{autoload_path} has precedence") if logger
         else
           promote_namespace_from_implicit_to_explicit(
@@ -537,7 +521,6 @@ module Zeitwerk
           )
         end
       elsif cdef?(parent, cname)
-        shadowed_files.add(file)
         log("file #{file} is ignored because #{cpath(parent, cname)} is already defined") if logger
       else
         set_autoload(parent, cname, file)

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.1.6
+  version: 2.1.7
 platform: ruby
 authors:
 - Xavier Noria
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-30 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