zeitwerk 2.8.0 → 2.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 071170ec551e69be67c517af6e04ae2788d6f81f6451a7da0dfab49be8f0c52b
-  data.tar.gz: 96fd655043bee86c5f57567a01b5f5282e315b72bde7e5ca370ee8fd5e7917fb
+  metadata.gz: bc67ff7496feaaf2e3598809e67733b9be0f92f69820736e3471ae0487c39d85
+  data.tar.gz: cecf1045923045d9d11d4f5e6c214a9e6dd14abd742fc1065c6f23a8aec82e13
 SHA512:
-  metadata.gz: 2b74298014af2753fbb19ad36f2a5d484cfbe364beb6aa583fe43d1f2cdf2fc3135bd5aaa16bedeb45a4a4ecbae95fc9d2e62aae5b59fd3df7cf5422693a947f
-  data.tar.gz: 242710104b8d2fba905cb65d1382080d098f4ff6c3d8b982d1cf53e9ea877612b22ee07b9d3f8f155a17b354e8412f2f350d835e7418f6eef7cf33a324a5ea4a
+  metadata.gz: 739fe00bce3542defa99e3c7a9014d7c4e00d0aa5a062e996c00dc2c9139e26de055e5aee806807c6da614504275bf2c790904d323d47213c031c291713daad6
+  data.tar.gz: 85acfebcb1de71e4c54e94803fb3be1c804960d3ba3754cdb6903a32a61e52f139cc06f7672f2cdcabb189dc9d66975479fc20a6733152e58e3131797fc151e4

data/README.md

@@ -305,8 +305,8 @@ loader.nsfile = 'ns.rb' # must be set before setup
 you can alternatively define the explicit namespace inside its directory:
 
 ```
-my_component/ns.rb     # MyComponent
-my_component/widget.rb # MyComponent::Widget
+my_component/ns.rb     -> MyComponent
+my_component/widget.rb -> MyComponent::Widget
 ```
 
 This may be handy for self-contained units for which a `my_component.rb` file in the parent directory would feel unnatural.
@@ -316,19 +316,19 @@ A loader's nsfile has to be a non-hidden basename with a `.rb` extension, as in
 Collapsed directories work as expected. For example, if we assume that `src` is collapsed, and that `assets` and `tests` are ignored, you could have the code organized this way:
 
 ```
-my_component/src/ns.rb     # MyComponent
-my_component/src/widget.rb # MyComponent::Widget
+my_component/src/ns.rb            -> MyComponent
+my_component/src/widget.rb        -> MyComponent::Widget
 my_component/assets/widget.js
 my_component/tests/test_widget.rb
 ```
 
-Loaders with an nsfile configured also support explicit namespaces defined in ordinary files. The styles are not exclusive. Some parts of the project may be component-oriented, while in other parts ordinary files may feel more natural. That works.
+Loaders with an nsfile configured also support explicit namespaces defined in ordinary files. The conventions are not exclusive project-wide. Some parts may be component-oriented, while in other parts ordinary files may feel more natural. That works.
 
 However, attempting to define the same namespace using an ordinary file and an nsfile is an error condition that raises `Zeitwerk::ConflictingNamespaceDefinitionError`.
 
 Nsfiles in root directories raise `Zeitwerk::ConflictingNamespaceDefinitionError` too, since the namespace in a root directory is externally defined.
 
-A project file whose basename is equal to the nsfile is always considered to be an nsfile. You cannot opt out. Therefore, if we have:
+Non-ignored files whose basename is equal to the nsfile are always considered to be nsfiles. You cannot opt out. Therefore, if we have:
 
 ```ruby
 loader.nsfile = 'index.rb'
@@ -336,12 +336,6 @@ loader.nsfile = 'index.rb'
 
 there is no way `foo/index.rb` can define `Foo::Index` in any part of the project, it must define `Foo`.
 
-While configurable, `ns.rb` is the recommended convention:
-
-* `ns.rb` is short.
-* `ns.rb` suggests "namespace".
-* Needing an `Ns` constant is unlikely.
-
 <a id="markdown-collapsing-directories" name="collapsing-directories"></a>
 ### Collapsing directories
 

data/lib/zeitwerk/loader/config.rb

@@ -7,6 +7,9 @@ module Zeitwerk::Loader::Config
   extend Zeitwerk::Internal
   include Zeitwerk::RealModName
 
+  UNDEFINED = Object.new.freeze
+  private_constant :UNDEFINED
+
   #: camelize(String, String) -> String
   attr_accessor :inflector
 
@@ -276,12 +279,19 @@ module Zeitwerk::Loader::Config
   #     # ...
   #   end
   #
-  #: (String?) { (top, String) -> void } -> void ! TypeError
-  def on_load(cpath = :ANY, &block)
-    raise TypeError, 'on_load only accepts strings' unless cpath.is_a?(String) || cpath == :ANY
+  #: (String) { (top, String) -> void } -> void ! TypeError | NameError
+  #| { (String, top, String) -> void } -> void
+  def on_load(cpath = UNDEFINED, &block)
+    key = if cpath.equal?(UNDEFINED)
+      :ANY
+    elsif !cpath.is_a?(String)
+      raise TypeError, 'on_load only accepts strings'
+    else
+      @cpv.validate!(cpath)
+    end
 
     mutex.synchronize do
-      (on_load_callbacks[cpath] ||= []) << block
+      (on_load_callbacks[key] ||= []) << block
     end
   end
 
@@ -299,12 +309,19 @@ module Zeitwerk::Loader::Config
   #     # ...
   #   end
   #
-  #: (String?) { (top, String) -> void } -> void ! TypeError
-  def on_unload(cpath = :ANY, &block)
-    raise TypeError, 'on_unload only accepts strings' unless cpath.is_a?(String) || cpath == :ANY
+  #: (String) { (top, String) -> void } -> void ! TypeError | NameError
+  #| { (String, top, String) -> void } -> void
+  def on_unload(cpath = UNDEFINED, &block)
+    key = if cpath.equal?(UNDEFINED)
+      :ANY
+    elsif !cpath.is_a?(String)
+      raise TypeError, 'on_unload only accepts strings'
+    else
+      @cpv.validate!(cpath)
+    end
 
     mutex.synchronize do
-      (on_unload_callbacks[cpath] ||= []) << block
+      (on_unload_callbacks[key] ||= []) << block
     end
   end
 

data/lib/zeitwerk/loader/constant_path_validator.rb

@@ -0,0 +1,17 @@
+# @private
+class Zeitwerk::Loader::ConstantPathValidator # :nodoc
+  CNAME_VALIDATOR = Module.new.freeze #: Module
+  private_constant :CNAME_VALIDATOR
+
+  # Technically, this validation works with symbols, but API boundary restricts
+  # input to strings, so we assume strings, and we test strings.
+  #
+  #: (String) -> String ! NameError
+  def validate!(possible_cpath)
+    # We do this before validating because as of this writing, TruffleRuby
+    # raises TypeError if the argument has leading colons.
+    possible_cpath = possible_cpath.delete_prefix('::')
+    CNAME_VALIDATOR.const_defined?(possible_cpath, false)
+    possible_cpath
+  end
+end

data/lib/zeitwerk/loader/file_system.rb

@@ -27,7 +27,7 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
   # path, and file type, which can only be :file or :directory.
   #
   #: (String) { (String, String, Symbol) -> void } -> void
-  def ls(dir, collapse: true, &)
+  def ls(dir, collapse: true, &block)
     children = relevant_dir_entries(dir)
 
     # The order in which a directory is listed depends on the file system.
@@ -43,7 +43,7 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
           @loader.__log { "directory #{abspath} is ignored because it has no Ruby files" }
           next
         elsif collapse && @loader.__collapse?(abspath)
-          ls(abspath, collapse: collapse, &)
+          ls(abspath, collapse: collapse, &block)
           next
         end
       end

data/lib/zeitwerk/loader/helpers.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
 module Zeitwerk::Loader::Helpers
-  CNAME_VALIDATOR = Module.new #: Module
-  private_constant :CNAME_VALIDATOR
-
   #: (String, String) -> Symbol ! Zeitwerk::NameError
   private def cname_for(basename, abspath)
     cname = inflector.camelize(basename, abspath)
@@ -23,7 +20,7 @@ module Zeitwerk::Loader::Helpers
     end
 
     begin
-      CNAME_VALIDATOR.const_defined?(cname, false)
+      @cpv.validate!(cname)
     rescue ::NameError => error
       path_type = @fs.rb_extension?(abspath) ? 'file' : 'directory'
 

data/lib/zeitwerk/loader.rb

@@ -10,6 +10,7 @@ module Zeitwerk
     require_relative 'loader/config'
     require_relative 'loader/eager_load'
     require_relative 'loader/file_system'
+    require_relative 'loader/constant_path_validator'
 
     extend Internal
 
@@ -115,6 +116,7 @@ module Zeitwerk
       @setup           = false
       @eager_loaded    = false
       @fs              = FileSystem.new(self)
+      @cpv             = ConstantPathValidator.new
 
       @mutex = Mutex.new
       @dirs_autoload_monitor = Monitor.new

data/lib/zeitwerk/registry/loaders.rb

@@ -6,8 +6,8 @@ module Zeitwerk::Registry
     end
 
     #: ({ (Zeitwerk::Loader) -> void }) -> void
-    def each(&)
-      @loaders.each(&)
+    def each(&block)
+      @loaders.each(&block)
     end
 
     #: (Zeitwerk::Loader) -> void

data/lib/zeitwerk/version.rb

@@ -2,5 +2,5 @@
 
 module Zeitwerk
   #: String
-  VERSION = '2.8.0'
+  VERSION = '2.8.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.8.0
+  version: 2.8.2
 platform: ruby
 authors:
 - Xavier Noria
@@ -34,6 +34,7 @@ files:
 - lib/zeitwerk/loader.rb
 - lib/zeitwerk/loader/callbacks.rb
 - lib/zeitwerk/loader/config.rb
+- lib/zeitwerk/loader/constant_path_validator.rb
 - lib/zeitwerk/loader/eager_load.rb
 - lib/zeitwerk/loader/file_system.rb
 - lib/zeitwerk/loader/helpers.rb