zeitwerk 2.6.0 → 2.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7c15f85768f681d78dd0a96b23e5bb92fe8955fe74d9ae0cefeb1b0a55b76f1
-  data.tar.gz: 212a4b236b7d67c9413bd583bef540c0c9c090f5d0457af38b0681405bba3244
+  metadata.gz: cf4acabb8b402560402158aced0f30ae6bae5120dc65d719f4fb15c1385a2454
+  data.tar.gz: 0a297687455cf8c3924a64c5e36223c35b0f69712c807ee9bc70748f8c42ff37
 SHA512:
-  metadata.gz: 4feeb02e4ec695895035a39d1a46d45bd8eb77a1d72e732c28387ff16f4c3e2ac10735195fa246179cfce2fe072ada05c0f661b599fd4bc44763d300e485b12d
-  data.tar.gz: 0bd284cdfd10b1f27c7ad31ecd79c7bce9d76be46d3644941259ac7ee22ed425baac0cbcc340653547c873aecca6d5833c908e3009f58c4f0376be5402c9645b
+  metadata.gz: 1d6666a098ae430f452edcd8b5e458541f20b20c4ee5903c4d18fe19cdce5afe81d6311a1bff5f9412b18ae57274e9b13132f8d59d9189b0ccd6cf7711337d6e
+  data.tar.gz: a131561faa463e489f7e9c4898bc8e212b2f6814ba3ce634b7ef62e25467f38b88e4c63106e8d53ee933681e1f0dc196244d16f13c299d2ca0771ee4031655a1

data/README.md

@@ -47,6 +47,7 @@
   - [Edge cases](#edge-cases)
   - [Beware of circular dependencies](#beware-of-circular-dependencies)
   - [Reopening third-party namespaces](#reopening-third-party-namespaces)
+  - [Introspection](#introspection)
   - [Encodings](#encodings)
   - [Rules of thumb](#rules-of-thumb)
   - [Debuggers](#debuggers)
@@ -249,7 +250,7 @@ app/controllers/admin/users_controller.rb -> Admin::UsersController
 
 and does not have a file called `admin.rb`, Zeitwerk automatically creates an `Admin` module on your behalf the first time `Admin` is used.
 
-For this to happen, the directory has to contain non-ignored Ruby files, directly or recursively, otherwise it is ignored. This condition is evaluated again on reloads.
+For this to happen, the directory has to contain non-ignored Ruby files with extension `.rb`, directly or recursively, otherwise it is ignored. This condition is evaluated again on reloads.
 
 <a id="markdown-explicit-namespaces" name="explicit-namespaces"></a>
 ### Explicit namespaces
@@ -983,12 +984,36 @@ require "active_job"
 require "active_job/queue_adapters"
 
 require "zeitwerk"
-loader = Zeitwerk::Loader.for_gem
+# By passign the flag, we acknowledge the extra directory lib/active_job
+# has to be managed by the loader and no warning has to be issued for it.
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 loader.setup
 ```
 
 With that, when Zeitwerk scans the file system and reaches the gem directories `lib/active_job` and `lib/active_job/queue_adapters`, it detects the corresponding modules already exist and therefore understands it does not have to manage them. The loader just descends into those directories. Eventually will reach `lib/active_job/queue_adapters/awesome_queue.rb`, and since `ActiveJob::QueueAdapters::AwesomeQueue` is unknown, Zeitwerk will manage it. Which is what happens regularly with the files in your gem. On reload, the namespaces are safe, won't be reloaded. The loader only reloads what it manages, which in this case is the adapter itself.
 
+<a id="markdown-introspection" name="introspection"></a>
+### Introspection
+
+The method `Zeitwerk::Loader#dirs` returns an array with the absolute paths of the root directories as strings:
+
+```ruby
+loader = Zeitwerk::Loader.new
+loader.push_dir(Pathname.new("/foo"))
+loader.dirs # => ["/foo"]
+```
+
+This method accepts an optional `namespaces` keyword argument. If truthy, the method returns a hash table instead. Keys are the absolute paths of the root directories as strings. Values are their corresponding namespaces, class or module objects:
+
+```ruby
+loader = Zeitwerk::Loader.new
+loader.push_dir(Pathname.new("/foo"))
+loader.push_dir(Pathname.new("/bar"), namespace: Bar)
+loader.dirs(namespaces: true) # => { "/foo" => Object, "/bar" => Bar }
+```
+
+These collections are read-only. Please add to them with `Zeitwerk::Loader#push_dir`.
+
 <a id="markdown-encodings" name="encodings"></a>
 ### Encodings
 

data/lib/zeitwerk/loader/config.rb

@@ -5,18 +5,19 @@ require "securerandom"
 
 module Zeitwerk::Loader::Config
   # Absolute paths of the root directories. Stored in a hash to preserve
-  # order, easily handle duplicates, and also be able to have a fast lookup,
-  # needed for detecting nested paths.
+  # order, easily handle duplicates, have a fast lookup needed for detecting
+  # nested paths, and store custom namespaces as values.
   #
-  #   "/Users/fxn/blog/app/assets"   => true,
-  #   "/Users/fxn/blog/app/channels" => true,
+  #   "/Users/fxn/blog/app/assets"   => Object,
+  #   "/Users/fxn/blog/app/channels" => Object,
+  #   "/Users/fxn/blog/adapters"     => ActiveJob::QueueAdapters,
   #   ...
   #
   # This is a private collection maintained by the loader. The public
   # interface for it is `push_dir` and `dirs`.
   #
   # @private
-  # @sig Hash[String, true]
+  # @sig Hash[String, Module]
   attr_reader :root_dirs
 
   # @sig #camelize
@@ -136,12 +137,20 @@ module Zeitwerk::Loader::Config
     @tag = tag.to_s
   end
 
-  # Absolute paths of the root directories. This is a read-only collection,
-  # please push here via `push_dir`.
+  # If `namespaces` is falsey (default), returns an array with the absolute
+  # paths of the root directories as strings. If truthy, returns a hash table
+  # instead. Keys are the absolute paths of the root directories as strings,
+  # values are their corresponding namespaces, class or module objects.
   #
-  # @sig () -> Array[String]
-  def dirs
-    root_dirs.keys.freeze
+  # These are read-only collections, please add to them with `push_dir`.
+  #
+  # @sig () -> Array[String] | Hash[String, Module]
+  def dirs(namespaces: false)
+    if namespaces
+      root_dirs.clone
+    else
+      root_dirs.keys
+    end.freeze
   end
 
   # You need to call this method before setup in order to be able to reload.

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.0
+  version: 2.6.1
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-06-13 00:00:00.000000000 Z
+date: 2022-09-30 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem