zeitwerk 1.0.0.beta → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb5151594ce18ccd7919a1ed6b7860107ce1bfc1a02a4f9b038d77cc91ce2450
-  data.tar.gz: e403ef92cc0a14b09bcb54d15d53ba821ad3d72e7d6216c3b0e10e6e9c0734f9
+  metadata.gz: cfc51c080dd7eb9b63e869a04b6eeeb14c0098b64de32d0ef872bba22a6d85d2
+  data.tar.gz: 0d1f743c91aefa0dd073f8f9d05c97991849cd5aa2552633048c15e93269015c
 SHA512:
-  metadata.gz: 10f8af59a66e1462c622cfb6f5316c98808113830041f094861b1fa07a2e9a6734d1ea64a01ebc664e9b5dcf20844b443e98c6bbf196fec99a0dcfee76010331
-  data.tar.gz: 226489835ceb91d696138a966b34054755d9fb1e6bb3245cc028d03e156f21df6a949ee329f5575be1501e8bc143afe532037ff95af2a3631e82fe72963e9479
+  metadata.gz: 05fba3abfe897598b45650dd837bb8e7fe4ae19f8ddd43bac1e934e2da18d1374bec14c13c46e43ad37f5cc31f991ddd9c9e429455aa7014bc4e6760b690a03d
+  data.tar.gz: 9ae4f99de1c0e2ace6be146c80fb7384cc893f57f2ec4e6970b44b85ce80d9cf2aa95300b2aac18cb87bc56dfd07c3d155b6b7898c21216b303a1ebc24575414

data/README.md

@@ -1,5 +1,6 @@
 # Zeitwerk
 
+[![Gem Version](https://badge.fury.io/rb/zeitwerk.svg)](https://badge.fury.io/rb/zeitwerk)
 [![Build Status](https://travis-ci.com/fxn/zeitwerk.svg?branch=master)](https://travis-ci.com/fxn/zeitwerk)
 
 <!-- TOC -->
@@ -22,6 +23,8 @@
             - [Custom inflector](#custom-inflector)
         - [Logging](#logging)
         - [Ignoring parts of the project](#ignoring-parts-of-the-project)
+        - [Edge cases](#edge-cases)
+    - [Pronunciation](#pronunciation)
     - [Supported Ruby versions](#supported-ruby-versions)
     - [Motivation](#motivation)
     - [Thanks](#thanks)
@@ -64,7 +67,7 @@ loader.push_dir(...)
 loader.setup # ready!
 ```
 
-The `loader` variable can go out of scope. Zeitwerk keeps a registry with all of them, and so the object won't be garbage collected and remain active.
+The `loader` variable can go out of scope. Zeitwerk keeps a registry with all of them, and so the object won't be garbage collected.
 
 Later, you can reload if you want to:
 
@@ -80,7 +83,7 @@ loader.eager_load
 
 It is also possible to broadcast `eager_load` to all instances:
 
-```
+```ruby
 Zeitwerk::Loader.eager_load_all
 ```
 
@@ -128,7 +131,16 @@ app/models/hotel.rb         -> Hotel
 app/models/hotel/pricing.rb -> Hotel::Pricing
 ```
 
-Zeitwerk does not autovivify a `Hotel` module in that case. The file `app/models/hotel.rb` explicitly defines `Hotel` and Zeitwerk loads it as needed before going for `Hotel::Pricing`.
+There, `app/models/hotel.rb` defines `Hotel`, and thus Zeitwerk does not autovivify a module.
+
+The classes and modules from the namespace are already available in the body of the class or module defining it:
+
+```ruby
+class Hotel < ApplicationRecord
+  include Pricing # works
+  ...
+end
+```
 
 ### Nested root directories
 
@@ -162,6 +174,8 @@ 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.
 
+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.
+
 ### Reloading
 
 In order to reload code:
@@ -170,12 +184,16 @@ In order to reload code:
 loader.reload
 ```
 
-Generally speaking, reloading is useful for services, servers, web applications, etc. Gems that implement regular libraries, so to speak, won't normally have a use case for reloading.
+Generally speaking, reloading is useful while developing running services like web applications. Gems that implement regular libraries, so to speak, won't normally have a use case for reloading.
+
+Reloading removes the currently loaded classes and modules, resets the loader so that it will pick whatever is in the file system now, and runs preloads if there are any.
 
-It is important to highlight that this is and instance method. Therefore, reloading the code of a project managed by a particular loader does _not_ reload the code of other gems using Zeitwerk at all.
+It is important to highlight that this is an instance method. Don't worry about the project dependencies, 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.
+
 ### Eager loading
 
 Zeitwerk instances are able to eager load their managed files:
@@ -184,23 +202,7 @@ Zeitwerk instances are able to eager load their managed files:
 loader.eager_load
 ```
 
-You can opt-out of eager loading individual files or directories:
-
-```ruby
-db_adapters = File.expand_path("my_gem/db_adapters", __dir__)
-cache_adapters = File.expand_path("my_gem/cache_adapters", __dir__)
-loader.do_not_eager_load(db_adapters, cache_adapters)
-loader.setup
-loader.eager_load # won't go into the directories with db/cache adapters
-```
-
-Files and directories excluded from eager loading can still be loaded on demand, so an idiom like this is possible:
-
-```ruby
-db_adapter = Object.const_get("MyGem::DbAdapters::#{config[:db_adapter]}")
-```
-
-Please check `Zeitwerk::Loader#ignore` if you want files or directories to not be even autoloadable.
+That skips ignored files and directories.
 
 If you want to eager load yourself and all dependencies using Zeitwerk, you can broadcast the `eager_load` call to all instances:
 
@@ -208,8 +210,6 @@ If you want to eager load yourself and all dependencies using Zeitwerk, you can
 Zeitwerk::Loader.eager_load_all
 ```
 
-In that case, exclusions are per autoloader, and so will apply to each of them accordingly.
-
 This may be handy in top-level services, like web applications.
 
 ### Preloading
@@ -221,14 +221,12 @@ loader.preload("app/models/videogame.rb")
 loader.preload("app/models/book.rb")
 ```
 
-The example above depicts several calls are supported, but `preload` accepts multiple arguments and arrays of strings as well.
-
-The call can happen after `setup` (preloads on the spot), or before `setup` (executes during setup).
-
-If you're using reloading, preloads run on each reload too.
+The call can happen before `setup` (preloads during setup), or after `setup` (preloads on the spot). Each reload preloads too.
 
 This is a feature specifically thought for STIs in Rails, preloading the leafs of a STI tree ensures all classes are known when doing a query.
 
+The example above depicts several calls are supported, but `preload` accepts multiple arguments and arrays of strings as well.
+
 ### 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.
@@ -258,7 +256,7 @@ The inflectors that ship with Zeitwerk are deterministic and simple. But you can
 ```ruby
 # frozen_string_literal: true
 
-class MyInflector < Zeitwerk::Inflector # or Zeitwerk::GemInflector
+class MyInflector < Zeitwerk::Inflector
   def camelize(basename, _abspath)
     case basename
     when "api"
@@ -276,13 +274,13 @@ The first argument, `basename`, is a string with the basename of the file or dir
 
 The second argument, `abspath`, is a string with the absolute path to the file or directory in case you need it to decide how to inflect the basename.
 
-Then, assign the inflector before calling `setup`:
+Then, assign the inflector:
 
-```
+```ruby
 loader.inflector = MyInflector.new
 ```
 
-This needs to be assigned before the call to `setup`.
+This needs to be done before calling `setup`.
 
 ### Logging
 
@@ -292,7 +290,7 @@ Zeitwerk is silent by default, but you can configure a callable as logger:
 loader.logger = method(:puts)
 ```
 
-If there is a logger configured, the loader is going to print traces when autoloads are set, files loaded, and modules autovivified.
+If there is a logger configured, the loader is going to print traces when autoloads are set, files loaded, and modules autovivified. While reloading, removed autoloads and unloaded objects are also traced.
 
 If your project has namespaces, you'll notice in the traces Zeitwerk sets autoloads for _directories_. That's a technique used to be able to descend into subdirectories on demand, avoiding that way unnecessary tree walks.
 
@@ -318,6 +316,52 @@ loader.setup
 
 You can pass several arguments to this method, also an array of strings. And you can call `ignore` multiple times too.
 
+Another use case for ignoring files is the adapter pattern. Let's imagine your project talks to databases, supports several, and has adapters for each one of them. Those adapters may have top-level `require` calls that load their respective drivers, but you don't want your users to install them all, only the one they are going to use. On the other hand, if your code is eager loaded by you or a parent project (with `Zeitwerk::Loader.eager_load_all`), those `require` calls are going to be executed. Ignoring the adapters prevents that:
+
+```ruby
+db_adapters = File.expand_path("my_gem/db_adapters", __dir__)
+loader.ignore(db_adapters)
+loader.setup
+```
+
+The chosen adapter, then, has to be loaded by hand somehow:
+
+```ruby
+require "my_gem/db_adapters/#{config[:db_adapter]}"
+```
+
+### Edge cases
+
+A class or module that acts as a namespace:
+
+```ruby
+# trip.rb
+class Trip
+  include Geolocation
+end
+
+# trip/geolocation.rb
+module Trip::Geolocation
+  ...
+end
+```
+
+has to be defined with the `class` or `module` keywords, as in the example above.
+
+For technical reasons, raw constant assignment is not supported:
+
+```ruby
+# trip.rb
+Trip = Class.new { ... }  # NOT SUPPORTED
+Trip = Struct.new { ... } # NOT SUPPORTED
+```
+
+This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
+
+## Pronunciation
+
+"Zeitwerk" is pronounced [this way](https://raw.githubusercontent.com/fxn/zeitwerk/master/extras/zeitwerk_pronunciation.mp3).
+
 ## Supported Ruby versions
 
 Zeitwerk works with MRI 2.4.4 and above.

data/lib/zeitwerk/inflector.rb

@@ -12,7 +12,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

@@ -33,7 +33,7 @@ module Zeitwerk
     # Absolute paths of files or directories to be totally ignored.
     #
     # @private
-    # @return [String]
+    # @return [Set<String>]
     attr_reader :ignored
 
     # Maps real absolute paths for which an autoload has been set to their
@@ -65,10 +65,6 @@ module Zeitwerk
     # @return [{String => <String>}]
     attr_reader :lazy_subdirs
 
-    # @private
-    # @return [Set]
-    attr_reader :eager_load_exclusions
-
     # @private
     # @return [Mutex]
     attr_reader :mutex
@@ -84,18 +80,17 @@ module Zeitwerk
     def initialize
       self.inflector = Inflector.new
 
-      @dirs                  = {}
-      @preloads              = []
-      @ignored               = Set.new
-      @autoloads             = {}
-      @lazy_subdirs          = {}
-      @eager_load_exclusions = Set.new
+      @dirs         = {}
+      @preloads     = []
+      @ignored      = Set.new
+      @autoloads    = {}
+      @lazy_subdirs = {}
 
       @mutex        = Mutex.new
       @setup        = false
       @eager_loaded = false
 
-      @tracer = TracePoint.trace(:class) do |tp|
+      @tracer = TracePoint.new(:class) do |tp|
         unless lazy_subdirs.empty? # do not even compute the hash key if not needed
           if subdirs = lazy_subdirs.delete(tp.self.name)
             subdirs.each { |subdir| set_autoloads_in_dir(subdir, tp.self) }
@@ -155,7 +150,6 @@ module Zeitwerk
       mutex.synchronize do
         unless @setup
           actual_dirs.each { |dir| set_autoloads_in_dir(dir, Object) }
-          tracer.enable
           do_preload
           @setup = true
         end
@@ -174,9 +168,13 @@ module Zeitwerk
     def unload
       mutex.synchronize do
         autoloads.each do |path, (parent, cname)|
-          # If the constant was loaded, we unload it. Otherwise, this removes
-          # the autoload in the parent, which is something we want to do anyway.
-          parent.send(:remove_const, cname) rescue :user_removed_it_by_hand_that_is_fine
+          if parent.autoload?(cname)
+            parent.send(:remove_const, cname)
+            log("autoload for #{cpath(parent, cname)} removed") if logger
+          elsif parent.const_defined?(cname, false)
+            parent.send(:remove_const, cname)
+            log("#{cpath(parent, cname)} unloaded") if logger
+          end
 
           # Let Kernel#require load the same path later again by removing it
           # from $LOADED_FEATURES. We check the extension to avoid unnecessary
@@ -188,7 +186,7 @@ module Zeitwerk
 
         Registry.on_unload(self)
 
-        tracer.disable
+        disable_tracer
         @setup = false
       end
     end
@@ -207,31 +205,19 @@ module Zeitwerk
 
     # Eager loads all files in the root directories, recursively. Files do not
     # need to be in `$LOAD_PATH`, absolute file names are used. Ignored files
-    # are not eager loaded. You can opt-out specifically in specific files and
-    # directories with `do_not_eager_load`.
+    # are not eager loaded.
     #
     # @return [void]
     def eager_load
       mutex.synchronize do
         unless @eager_loaded
-          actual_dirs.each do |dir|
-            eager_load_dir(dir) unless eager_load_exclusions.member?(dir)
-          end
-          tracer.disable if eager_load_exclusions.empty?
+          actual_dirs.each { |dir| eager_load_dir(dir) }
+          disable_tracer
           @eager_loaded = true
         end
       end
     end
 
-    # Let eager load ignore the given files or directories. The constants
-    # defined in those files are still autoloadable.
-    #
-    # @param paths [<String, Pathname, <String, Pathname>>]
-    # @return [void]
-    def do_not_eager_load(*paths)
-      mutex.synchronize { eager_load_exclusions.merge(expand_paths(paths)) }
-    end
-
     # --- Class methods ---------------------------------------------------------------------------
 
     # This is a shortcut for
@@ -270,7 +256,7 @@ module Zeitwerk
     def on_file_loaded(file)
       if logger
         parent, cname = autoloads[file]
-        logger.call("constant #{cpath(parent, cname)} loaded from file #{file}")
+        log("constant #{cpath(parent, cname)} loaded from file #{file}")
       end
     end
 
@@ -282,7 +268,7 @@ module Zeitwerk
     def on_dir_loaded(dir)
       parent, cname = autoloads[dir]
       autovivified = parent.const_set(cname, Module.new)
-      logger.call("module #{cpath(parent, cname)} autovivified from directory #{dir}") if logger
+      log("module #{cpath(parent, cname)} autovivified from directory #{dir}") if logger
 
       if subdirs = lazy_subdirs[cpath(parent, cname)]
         subdirs.each { |subdir| set_autoloads_in_dir(subdir, autovivified) }
@@ -293,7 +279,7 @@ module Zeitwerk
 
     # @return [<String>]
     def actual_dirs
-      dirs.each_key.reject { |dir| ignored.member?(dir) }
+      dirs.keys.delete_if { |dir| ignored.member?(dir) }
     end
 
     # @param dir [String]
@@ -321,11 +307,11 @@ module Zeitwerk
     # @param subdir [String]
     # @return [void]
     def autoload_subdir(parent, cname, subdir)
-      if autoload_for?(parent, cname)
-        # If there is already an autoload for this cname, maybe there are
-        # multiple directories defining the namespace, or the cname is going to
-        # be defined in a file (explicit namespace). In either case, we do not
-        # need to issue another autoload, the existing one is fine.
+      if autoload = autoload_for?(parent, cname)
+        enable_tracer if ruby?(autoload)
+        # We do not need to issue another autoload, the existing one is enough
+        # no matter if it is for a file or a directory. Just remember the
+        # subdirectory has to be visited if the namespace is used.
         (lazy_subdirs[cpath(parent, cname)] ||= []) << subdir
       elsif !parent.const_defined?(cname, false)
         # First time we find this namespace, set an autoload for it.
@@ -351,7 +337,9 @@ module Zeitwerk
         # class/module defined in this file.
         autoloads.delete(autoload_path)
         Registry.unregister_autoload(autoload_path)
+
         set_autoload(parent, cname, file)
+        enable_tracer
       elsif !parent.const_defined?(cname, false)
         set_autoload(parent, cname, file)
       end
@@ -369,9 +357,9 @@ module Zeitwerk
       parent.autoload(cname, realpath)
       if logger
         if ruby?(realpath)
-          logger.call("autoload set for #{cpath(parent, cname)}, to be loaded from #{realpath}")
+          log("autoload set for #{cpath(parent, cname)}, to be loaded from #{realpath}")
         else
-          logger.call("autoload set for #{cpath(parent, cname)}, to be autovivified from #{realpath}")
+          log("autoload set for #{cpath(parent, cname)}, to be autovivified from #{realpath}")
         end
       end
 
@@ -395,8 +383,6 @@ module Zeitwerk
     # @return [void]
     def eager_load_dir(dir)
       each_abspath(dir) do |abspath|
-        next if eager_load_exclusions.member?(abspath)
-
         if ruby?(abspath)
           require abspath
         elsif dir?(abspath)
@@ -434,7 +420,7 @@ module Zeitwerk
     # @param file [String]
     # @return [Boolean]
     def do_preload_file(file)
-      logger.call("preloading #{file}") if logger
+      log("preloading #{file}") if logger
       require file
     end
 
@@ -473,5 +459,21 @@ module Zeitwerk
     def expand_paths(paths)
       Array(paths).flatten.map { |path| File.expand_path(path) }
     end
+
+    # @param message [String]
+    # @return [void]
+    def log(message)
+      logger.call("Zeitwerk: #{message}")
+    end
+
+    def enable_tracer
+      # We check enabled? because, looking at the C source code, enabling an
+      # enabled tracer does not seem to be a simple no-op.
+      tracer.enable if !tracer.enabled?
+    end
+
+    def disable_tracer
+      tracer.disable if tracer.enabled?
+    end
   end
 end

data/lib/zeitwerk/registry.rb

@@ -83,7 +83,7 @@ module Zeitwerk
       def loader_for_gem(root_file)
         loaders_managing_gems[root_file] ||= begin
           Loader.new.tap do |loader|
-            loader.inflector = Zeitwerk::GemInflector.new(root_file)
+            loader.inflector = GemInflector.new(root_file)
             loader.push_dir(File.dirname(root_file))
           end
         end

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "1.0.0.beta"
+  VERSION = "1.0.0.beta2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta
+  version: 1.0.0.beta2
 platform: ruby
 authors:
 - Xavier Noria
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-18 00:00:00.000000000 Z
+date: 2019-01-22 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem