zeitwerk 2.2.1 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7d5a0f54405ad45dd6afc9bf54bde579f66a75fb142cdbbfb5476157dd75493
-  data.tar.gz: b81311bb19c3b699a6720a3bb3d6df503b858a439c5f1f2605e029117de36bcb
+  metadata.gz: b6e1f64abc085125dd45f5c8373d793417811074dcb1d5c655c915ad393d0cf5
+  data.tar.gz: b4eba128f5267c2b3f40fdcd03085faae0a9063ef3a352f18b1bdbfd3031f068
 SHA512:
-  metadata.gz: 4f6fd6e8f7bd479ca6935d1f57d065151aff3be6977ad068f6b4ecdce200bbd131f4db4f2cc1bc2a719cb332b538cf24be55eb936a51572ac5c06676d21763f2
-  data.tar.gz: d4266c65e380b356ff4df7394f2f1882f72ac32b5226dedd717f6b4064c8ac1b8fd3d70ec08b6f9838debfc3690d2f3eee2d6885e446f087a686a619c872c718
+  metadata.gz: 6928afbdf70077641fd07240ec8b22d4589e721fe0ab4a4008d3a880bf460b3daac3b7504151eae2320b98a55bd2e7cae3977c78d3dbfde156eca69270795362
+  data.tar.gz: b64df779dcb21d094d87ee739291e7798942262b05ff32ebd841dd33b237addf7551ff641fb5e4fd8d10ccdf54f25845e77860d68931e0ebf307164c5ce076fb

data/README.md

@@ -15,8 +15,9 @@
     - [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)
@@ -219,33 +220,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
+<a id="markdown-autoloading" name="autoloading"></a>
+### Autoloading
 
-Zeitwerk is able to reload code, but you need to enable this feature:
+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.
 
-```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.
+Let's revisit the example above:
 
-Enabling reloading after setup raises `Zeitwerk::Error`. Similarly, calling `reload` without having enabled reloading also raises `Zeitwerk::Error`.
-
-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
@@ -269,6 +265,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
@@ -279,6 +277,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
 

data/lib/zeitwerk/loader.rb

@@ -494,7 +494,7 @@ module Zeitwerk
         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 +558,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]

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 Zeitwerk::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/version.rb

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

metadata

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