zeitwerk 2.6.6 → 2.6.12
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +165 -43
- data/lib/zeitwerk/explicit_namespace.rb +7 -0
- data/lib/zeitwerk/gem_inflector.rb +2 -2
- data/lib/zeitwerk/gem_loader.rb +11 -7
- data/lib/zeitwerk/kernel.rb +3 -3
- data/lib/zeitwerk/loader/callbacks.rb +22 -14
- data/lib/zeitwerk/loader/config.rb +20 -11
- data/lib/zeitwerk/loader/eager_load.rb +10 -4
- data/lib/zeitwerk/loader/helpers.rb +50 -0
- data/lib/zeitwerk/loader.rb +136 -66
- data/lib/zeitwerk/registry.rb +2 -2
- data/lib/zeitwerk/version.rb +1 -1
- metadata +3 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 5a9048a5ba05f448e5406080995aab9709a3dd7c8dd32aad3aa0ba4f544b69c4
|
4
|
+
data.tar.gz: 581cf27f70c82b754a1baadf7a41f6c87c069ae2e78bd26b4ec6e02cfa2795b9
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 45327b148bab210d941ffeae022b70e5c2f2be4372f2192a08859faeed81d2cc5702b05d6e4efcf676a8fb7b451c46200ac372051c68ba84cfc31ed9339f3ede
|
7
|
+
data.tar.gz: 8e3266d7641f58b6a8f74abfa913c14ae4a79d4efd177578de4e7e144a21adc33d33279b7d2771cdc57937cfedfb1f5e193bb9e57c18ea90956b342b516e9bd9
|
data/README.md
CHANGED
@@ -3,7 +3,8 @@
|
|
3
3
|
|
4
4
|
|
5
5
|
[![Gem Version](https://img.shields.io/gem/v/zeitwerk.svg?style=for-the-badge)](https://rubygems.org/gems/zeitwerk)
|
6
|
-
[![Build Status](https://img.shields.io/github/workflow/status/fxn/zeitwerk/
|
6
|
+
[![Build Status](https://img.shields.io/github/actions/workflow/status/fxn/zeitwerk/ci.yml?branch=main&event=push&style=for-the-badge)](https://github.com/fxn/zeitwerk/actions/workflows/ci.yml?query=branch%3Amain)
|
7
|
+
|
7
8
|
|
8
9
|
<!-- TOC -->
|
9
10
|
|
@@ -24,6 +25,7 @@
|
|
24
25
|
- [Setup](#setup)
|
25
26
|
- [Generic](#generic)
|
26
27
|
- [for_gem](#for_gem)
|
28
|
+
- [for_gem_extension](#for_gem_extension)
|
27
29
|
- [Autoloading](#autoloading)
|
28
30
|
- [Eager loading](#eager-loading)
|
29
31
|
- [Eager load exclusions](#eager-load-exclusions)
|
@@ -55,12 +57,11 @@
|
|
55
57
|
- [Beware of circular dependencies](#beware-of-circular-dependencies)
|
56
58
|
- [Reopening third-party namespaces](#reopening-third-party-namespaces)
|
57
59
|
- [Introspection](#introspection)
|
60
|
+
- [`Zeitwerk::Loader#dirs`](#zeitwerkloaderdirs)
|
61
|
+
- [`Zeitwerk::Loader#cpath_expected_at`](#zeitwerkloadercpath_expected_at)
|
58
62
|
- [Encodings](#encodings)
|
59
63
|
- [Rules of thumb](#rules-of-thumb)
|
60
64
|
- [Debuggers](#debuggers)
|
61
|
-
- [debug.rb](#debugrb)
|
62
|
-
- [Byebug](#byebug)
|
63
|
-
- [Break](#break)
|
64
65
|
- [Pronunciation](#pronunciation)
|
65
66
|
- [Supported Ruby versions](#supported-ruby-versions)
|
66
67
|
- [Testing](#testing)
|
@@ -78,15 +79,15 @@
|
|
78
79
|
|
79
80
|
Zeitwerk is an efficient and thread-safe code loader for Ruby.
|
80
81
|
|
81
|
-
Given a [conventional file structure](#file-structure), Zeitwerk is
|
82
|
+
Given a [conventional file structure](#file-structure), Zeitwerk is capable of loading 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; instead, you can streamline your programming by knowing that your classes and modules are available everywhere. This feature is efficient, thread-safe, and aligns with Ruby's semantics for constants.
|
82
83
|
|
83
|
-
Zeitwerk
|
84
|
+
Zeitwerk also supports code reloading, which can be useful during web application development. However, coordination is required to reload in a thread-safe manner. The documentation below explains how to achieve this.
|
84
85
|
|
85
|
-
The gem is designed
|
86
|
+
The gem is designed to allow any project, gem dependency, or application to have its own independent loader. Multiple loaders can coexist in the same process, each managing its own project tree and operating independently of each other. Each loader has its own configuration, inflector, and optional logger.
|
86
87
|
|
87
|
-
Internally, Zeitwerk
|
88
|
+
Internally, Zeitwerk exclusively uses absolute file names when issuing `require` calls, eliminating the need for costly file system lookups in `$LOAD_PATH`. Technically, the directories managed by Zeitwerk don't even need to be in `$LOAD_PATH`.
|
88
89
|
|
89
|
-
Furthermore, Zeitwerk
|
90
|
+
Furthermore, Zeitwerk performs a single scan of the project tree at most, lazily descending into subdirectories only when their namespaces are used.
|
90
91
|
|
91
92
|
<a id="markdown-synopsis" name="synopsis"></a>
|
92
93
|
## Synopsis
|
@@ -146,7 +147,7 @@ Zeitwerk::Loader.eager_load_all
|
|
146
147
|
<a id="markdown-the-idea-file-paths-match-constant-paths" name="the-idea-file-paths-match-constant-paths"></a>
|
147
148
|
### The idea: File paths match constant paths
|
148
149
|
|
149
|
-
|
150
|
+
For Zeitwerk to work with your file structure, simply name files and directories after the classes and modules they define:
|
150
151
|
|
151
152
|
```
|
152
153
|
lib/my_gem.rb -> MyGem
|
@@ -155,7 +156,7 @@ lib/my_gem/bar_baz.rb -> MyGem::BarBaz
|
|
155
156
|
lib/my_gem/woo/zoo.rb -> MyGem::Woo::Zoo
|
156
157
|
```
|
157
158
|
|
158
|
-
You can tune
|
159
|
+
You can fine-tune this behavior by [collapsing directories](#collapsing-directories) or [ignoring specific parts of the project](#ignoring-parts-of-the-project), but that is the main idea.
|
159
160
|
|
160
161
|
<a id="markdown-inner-simple-constants" name="inner-simple-constants"></a>
|
161
162
|
### Inner simple constants
|
@@ -176,7 +177,7 @@ class HttpCrawler
|
|
176
177
|
end
|
177
178
|
```
|
178
179
|
|
179
|
-
The first example needs a custom [inflection](
|
180
|
+
The first example needs a custom [inflection](#inflection) rule:
|
180
181
|
|
181
182
|
```ruby
|
182
183
|
loader.inflector.inflect("max_retries" => "MAX_RETRIES")
|
@@ -213,7 +214,7 @@ serializers/user_serializer.rb -> UserSerializer
|
|
213
214
|
<a id="markdown-custom-root-namespaces" name="custom-root-namespaces"></a>
|
214
215
|
#### Custom root namespaces
|
215
216
|
|
216
|
-
|
217
|
+
Although `Object` is the most common root namespace, you have the flexibility to associate a different one with a specific root directory. The `push_dir` method accepts a non-anonymous class or module object as the optional `namespace` keyword argument.
|
217
218
|
|
218
219
|
For example, given:
|
219
220
|
|
@@ -229,14 +230,14 @@ a file defining `ActiveJob::QueueAdapters::MyQueueAdapter` does not need the con
|
|
229
230
|
adapters/my_queue_adapter.rb -> ActiveJob::QueueAdapters::MyQueueAdapter
|
230
231
|
```
|
231
232
|
|
232
|
-
Please
|
233
|
+
Please note that the provided root namespace must be non-reloadable, while allowing autoloaded constants within that namespace to be reloadable. This means that if you associate the `app/api` directory with an existing `Api` module, the module itself should not be reloadable. However, if the project defines and autoloads the `Api::Deliveries` class, that class can be reloaded.
|
233
234
|
|
234
235
|
<a id="markdown-nested-root-directories" name="nested-root-directories"></a>
|
235
236
|
#### Nested root directories
|
236
237
|
|
237
|
-
Root directories
|
238
|
+
Root directories are recommended not to be nested; however, Zeitwerk provides support for nested root directories since in frameworks like Rails, both `app/models` and `app/models/concerns` belong to the autoload paths.
|
238
239
|
|
239
|
-
Zeitwerk
|
240
|
+
Zeitwerk identifies nested root directories and treats them as independent roots. In the given example, `concerns` is not considered a namespace within `app/models`. For instance, consider the following file:
|
240
241
|
|
241
242
|
```
|
242
243
|
app/models/concerns/geolocatable.rb
|
@@ -247,9 +248,9 @@ should define `Geolocatable`, not `Concerns::Geolocatable`.
|
|
247
248
|
<a id="markdown-implicit-namespaces" name="implicit-namespaces"></a>
|
248
249
|
### Implicit namespaces
|
249
250
|
|
250
|
-
If a namespace
|
251
|
+
If a namespace consists only of a simple module without any code, there is no need to explicitly define it in a separate file. Zeitwerk automatically creates modules on your behalf for directories without a corresponding Ruby file.
|
251
252
|
|
252
|
-
For
|
253
|
+
For instance, suppose a project includes an `admin` directory:
|
253
254
|
|
254
255
|
```
|
255
256
|
app/controllers/admin/users_controller.rb -> Admin::UsersController
|
@@ -257,7 +258,7 @@ app/controllers/admin/users_controller.rb -> Admin::UsersController
|
|
257
258
|
|
258
259
|
and does not have a file called `admin.rb`, Zeitwerk automatically creates an `Admin` module on your behalf the first time `Admin` is used.
|
259
260
|
|
260
|
-
|
261
|
+
To trigger this behavior, the directory must contain non-ignored Ruby files with the `.rb` extension, either directly or recursively. Otherwise, the directory is ignored. This condition is reevaluated during reloads.
|
261
262
|
|
262
263
|
<a id="markdown-explicit-namespaces" name="explicit-namespaces"></a>
|
263
264
|
### Explicit namespaces
|
@@ -391,6 +392,12 @@ module MyGem
|
|
391
392
|
end
|
392
393
|
```
|
393
394
|
|
395
|
+
Due to technical reasons, the entry point of the gem has to be loaded with `Kernel#require`, which is the standard way to load a gem. Loading that file with `Kernel#load` or `Kernel#require_relative` won't generally work.
|
396
|
+
|
397
|
+
`Zeitwerk::Loader.for_gem` is idempotent when invoked from the same file, to support gems that want to reload (unlikely).
|
398
|
+
|
399
|
+
If the entry point of your gem lives in a subdirectory of `lib` because it is reopening a namespace defined somewhere else, please use the generic API to setup the loader, and make sure you check the section [_Reopening third-party namespaces_](#reopening-third-party-namespaces) down below.
|
400
|
+
|
394
401
|
Loaders returned by `Zeitwerk::Loader.for_gem` issue warnings if `lib` has extra Ruby files or directories.
|
395
402
|
|
396
403
|
For example, if the gem has Rails generators under `lib/generators`, by convention that directory defines a `Generators` Ruby module. If `generators` is just a container for non-autoloadable code and templates, not acting as a project namespace, you need to setup things accordingly.
|
@@ -407,9 +414,64 @@ Otherwise, there's a flag to say the extra stuff is OK:
|
|
407
414
|
Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
|
408
415
|
```
|
409
416
|
|
410
|
-
|
417
|
+
<a id="markdown-for_gem_extension" name="for_gem_extension"></a>
|
418
|
+
#### for_gem_extension
|
419
|
+
|
420
|
+
Let's suppose you are writing a gem to extend `Net::HTTP` with some niche feature. By [convention](https://guides.rubygems.org/name-your-gem/):
|
421
|
+
|
422
|
+
* The gem should be called `net-http-niche_feature`. That is, hyphens for the extended part, a hyphen, and underscores for yours.
|
423
|
+
* The namespace should be `Net::HTTP::NicheFeature`.
|
424
|
+
* The entry point should be `lib/net/http/niche_feature.rb`.
|
425
|
+
* Optionally, the gem could have a top-level `lib/net-http-niche_feature.rb`, but, if defined, that one should have just a `require` call for the entry point.
|
426
|
+
|
427
|
+
The top-level file mentioned in the last point is optional. In particular, from
|
428
|
+
|
429
|
+
```ruby
|
430
|
+
gem "net-http-niche_feature"
|
431
|
+
```
|
432
|
+
|
433
|
+
if the hyphenated file does not exist, Bundler notes the conventional hyphenated pattern and issues a `require` for `net/http/niche_feature`.
|
434
|
+
|
435
|
+
Gem extensions following the conventions above have a dedicated loader constructor: `Zeitwerk::Loader.for_gem_extension`.
|
436
|
+
|
437
|
+
The structure of the gem would be like this:
|
438
|
+
|
439
|
+
```ruby
|
440
|
+
# lib/net-http-niche_feature.rb (optional)
|
441
|
+
|
442
|
+
# For technical reasons, this cannot be require_relative.
|
443
|
+
require "net/http/niche_feature"
|
444
|
+
|
445
|
+
|
446
|
+
# lib/net/http/niche_feature.rb
|
447
|
+
|
448
|
+
require "net/http"
|
449
|
+
require "zeitwerk"
|
450
|
+
|
451
|
+
loader = Zeitwerk::Loader.for_gem_extension(Net::HTTP)
|
452
|
+
loader.setup
|
453
|
+
|
454
|
+
module Net::HTTP::NicheFeature
|
455
|
+
# Since the setup has been performed, at this point we are already able
|
456
|
+
# to reference project constants, in this case Net::HTTP::NicheFeature::MyMixin.
|
457
|
+
include MyMixin
|
458
|
+
end
|
459
|
+
|
460
|
+
|
461
|
+
# lib/net/http/niche_feature/version.rb
|
462
|
+
|
463
|
+
module Net::HTTP::NicheFeature
|
464
|
+
VERSION = "1.0.0"
|
465
|
+
end
|
466
|
+
```
|
467
|
+
|
468
|
+
`Zeitwerk::Loader.for_gem_extension` expects as argument the namespace being extended, which has to be a non-anonymous class or module object.
|
469
|
+
|
470
|
+
If it exists, `lib/net/http/niche_feature/version.rb` is expected to define `Net::HTTP::NicheFeature::VERSION`.
|
411
471
|
|
412
|
-
|
472
|
+
Due to technical reasons, the entry point of the gem has to be loaded with `Kernel#require`. Loading that file with `Kernel#load` or `Kernel#require_relative` won't generally work. This is important if you load the entry point from the optional hyphenated top-level file.
|
473
|
+
|
474
|
+
`Zeitwerk::Loader.for_gem_extension` is idempotent when invoked from the same file, to support gems that want to reload (unlikely).
|
413
475
|
|
414
476
|
<a id="markdown-autoloading" name="autoloading"></a>
|
415
477
|
### Autoloading
|
@@ -445,7 +507,7 @@ loader.eager_load
|
|
445
507
|
|
446
508
|
That skips [ignored files and directories](#ignoring-parts-of-the-project).
|
447
509
|
|
448
|
-
In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](
|
510
|
+
In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](#synopsis).
|
449
511
|
|
450
512
|
Eager loading is synchronized and idempotent.
|
451
513
|
|
@@ -486,7 +548,7 @@ This is useful when the loader is not eager loading the entire project, but you
|
|
486
548
|
|
487
549
|
Both strings and `Pathname` objects are supported as arguments. If the argument is not a directory managed by the receiver, the method raises `Zeitwerk::Error`.
|
488
550
|
|
489
|
-
[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](
|
551
|
+
[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](#shadowed-files) are not eager loaded.
|
490
552
|
|
491
553
|
`Zeitwerk::Loader#eager_load_dir` is idempotent, but compatible with reloading. If you eager load a directory and then reload, eager loading that directory will load its (current) contents again.
|
492
554
|
|
@@ -519,11 +581,11 @@ root_dir3/my_app/routes
|
|
519
581
|
|
520
582
|
where `root_directory{1,2,3}` are root directories, eager loading `MyApp::Routes` will eager load the contents of the three corresponding directories.
|
521
583
|
|
522
|
-
There might exist external source trees implementing part of the namespace. This happens routinely, because top-level constants are stored in the globally shared `Object`. It happens also when deliberately [reopening third-party namespaces](reopening-third-party-namespaces). Such external code is not eager loaded, the implementation is carefully scoped to what the receiver manages to avoid side-effects elsewhere.
|
584
|
+
There might exist external source trees implementing part of the namespace. This happens routinely, because top-level constants are stored in the globally shared `Object`. It happens also when deliberately [reopening third-party namespaces](#reopening-third-party-namespaces). Such external code is not eager loaded, the implementation is carefully scoped to what the receiver manages to avoid side-effects elsewhere.
|
523
585
|
|
524
586
|
This method is flexible about what it accepts. Its semantics have to be interpreted as: "_If_ you manage this namespace, or part of this namespace, please eager load what you got". In particular, if the receiver does not manage the namespace, it will simply do nothing, this is not an error condition.
|
525
587
|
|
526
|
-
[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](
|
588
|
+
[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](#shadowed-files) are not eager loaded.
|
527
589
|
|
528
590
|
`Zeitwerk::Loader#eager_load_namespace` is idempotent, but compatible with reloading. If you eager load a namespace and then reload, eager loading that namespace will load its (current) descendants again.
|
529
591
|
|
@@ -576,7 +638,7 @@ loader.load_file("#{__dir__}/custom_web_app/routes.rb")
|
|
576
638
|
|
577
639
|
This is useful when the loader is not eager loading the entire project, but you still need an individual file to be loaded for things to function properly.
|
578
640
|
|
579
|
-
Both strings and `Pathname` objects are supported as arguments. The method raises `Zeitwerk::Error` if the argument is not a Ruby file, is [ignored](#ignoring-parts-of-the-project), is [shadowed](
|
641
|
+
Both strings and `Pathname` objects are supported as arguments. The method raises `Zeitwerk::Error` if the argument is not a Ruby file, is [ignored](#ignoring-parts-of-the-project), is [shadowed](#shadowed-files), or is not managed by the receiver.
|
580
642
|
|
581
643
|
`Zeitwerk::Loader#load_file` is idempotent, but compatible with reloading. If you load a file and then reload, a new call will load its (current) contents again.
|
582
644
|
|
@@ -674,9 +736,34 @@ loader.inflector.inflect "html_parser" => "HTMLParser"
|
|
674
736
|
loader.inflector.inflect "mysql_adapter" => "MySQLAdapter"
|
675
737
|
```
|
676
738
|
|
739
|
+
Overrides have to match exactly directory or file (without extension) _basenames_. For example, if you configure
|
740
|
+
|
741
|
+
```ruby
|
742
|
+
loader.inflector.inflect("xml" => "XML")
|
743
|
+
```
|
744
|
+
|
745
|
+
then the following constants are expected:
|
746
|
+
|
747
|
+
```
|
748
|
+
xml.rb -> XML
|
749
|
+
foo/xml -> Foo::XML
|
750
|
+
foo/bar/xml.rb -> Foo::Bar::XML
|
751
|
+
```
|
752
|
+
|
753
|
+
As you see, any directory whose basename is exactly `xml`, and any file whose basename is exactly `xml.rb` are expected to define the constant `XML` in the corresponding namespace. On the other hand, partial matches are ignored. For example, `xml_parser.rb` would be inflected as `XmlParser` because `xml_parser` is not equal to `xml`. You'd need an additional override:
|
754
|
+
|
755
|
+
```ruby
|
756
|
+
loader.inflector.inflect(
|
757
|
+
"xml" => "XML",
|
758
|
+
"xml_parser" => "XMLParser"
|
759
|
+
)
|
760
|
+
```
|
761
|
+
|
762
|
+
If you need more flexibility, you can define a custom inflector, as explained down below.
|
763
|
+
|
677
764
|
Overrides need to be configured before calling `setup`.
|
678
765
|
|
679
|
-
|
766
|
+
The inflectors of different loaders are independent of each other. There are no global inflection rules or global configuration that can affect this inflector. It is deterministic.
|
680
767
|
|
681
768
|
<a id="markdown-zeitwerkgeminflector" name="zeitwerkgeminflector"></a>
|
682
769
|
#### Zeitwerk::GemInflector
|
@@ -951,6 +1038,8 @@ However, sometimes it might still be convenient to tell Zeitwerk to completely i
|
|
951
1038
|
|
952
1039
|
You can ignore file names, directory names, and glob patterns. Glob patterns are expanded when they are added and again on each reload.
|
953
1040
|
|
1041
|
+
There is an edge case related to nested root directories. Conceptually, root directories are independent source trees. If you ignore a parent of a nested root directory, the nested root directory is not affected. You need to ignore it explictly if you want it ignored too.
|
1042
|
+
|
954
1043
|
Let's see some use cases.
|
955
1044
|
|
956
1045
|
<a id="markdown-use-case-files-that-do-not-follow-the-conventions" name="use-case-files-that-do-not-follow-the-conventions"></a>
|
@@ -1085,8 +1174,9 @@ For technical reasons, raw constant assignment is not supported:
|
|
1085
1174
|
|
1086
1175
|
```ruby
|
1087
1176
|
# trip.rb
|
1088
|
-
Trip = Class
|
1089
|
-
Trip = Struct.new { ... }
|
1177
|
+
Trip = Class { ...} # NOT SUPPORTED
|
1178
|
+
Trip = Struct.new { ... } # NOT SUPPORTED
|
1179
|
+
Trip = Data.define { ... } # NOT SUPPORTED
|
1090
1180
|
```
|
1091
1181
|
|
1092
1182
|
This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
|
@@ -1152,6 +1242,9 @@ With that, when Zeitwerk scans the file system and reaches the gem directories `
|
|
1152
1242
|
<a id="markdown-introspection" name="introspection"></a>
|
1153
1243
|
### Introspection
|
1154
1244
|
|
1245
|
+
<a id="markdown-zeitwerkloaderdirs" name="zeitwerkloaderdirs"></a>
|
1246
|
+
#### `Zeitwerk::Loader#dirs`
|
1247
|
+
|
1155
1248
|
The method `Zeitwerk::Loader#dirs` returns an array with the absolute paths of the root directories as strings:
|
1156
1249
|
|
1157
1250
|
```ruby
|
@@ -1169,8 +1262,48 @@ loader.push_dir(Pathname.new("/bar"), namespace: Bar)
|
|
1169
1262
|
loader.dirs(namespaces: true) # => { "/foo" => Object, "/bar" => Bar }
|
1170
1263
|
```
|
1171
1264
|
|
1265
|
+
By default, ignored root directories are filtered out. If you want them included, please pass `ignored: true`.
|
1266
|
+
|
1172
1267
|
These collections are read-only. Please add to them with `Zeitwerk::Loader#push_dir`.
|
1173
1268
|
|
1269
|
+
<a id="markdown-zeitwerkloadercpath_expected_at" name="zeitwerkloadercpath_expected_at"></a>
|
1270
|
+
#### `Zeitwerk::Loader#cpath_expected_at`
|
1271
|
+
|
1272
|
+
Given a path as a string or `Pathname` object, `Zeitwerk::Loader#cpath_expected_at` returns a string with the corresponding expected constant path.
|
1273
|
+
|
1274
|
+
Some examples, assuming that `app/models` is a root directory:
|
1275
|
+
|
1276
|
+
```ruby
|
1277
|
+
loader.cpath_expected_at("app/models") # => "Object"
|
1278
|
+
loader.cpath_expected_at("app/models/user.rb") # => "User"
|
1279
|
+
loader.cpath_expected_at("app/models/hotel") # => "Hotel"
|
1280
|
+
loader.cpath_expected_at("app/models/hotel/billing.rb") # => "Hotel::Billing"
|
1281
|
+
```
|
1282
|
+
|
1283
|
+
If `collapsed` is a collapsed directory:
|
1284
|
+
|
1285
|
+
```ruby
|
1286
|
+
loader.cpath_expected_at("a/b/collapsed/c") # => "A::B::C"
|
1287
|
+
loader.cpath_expected_at("a/b/collapsed") # => "A::B", edge case
|
1288
|
+
loader.cpath_expected_at("a/b") # => "A::B"
|
1289
|
+
```
|
1290
|
+
|
1291
|
+
If the argument corresponds to an [ignored file or directory](#ignoring-parts-of-the-project), the method returns `nil`. Same if the argument is not managed by the loader.
|
1292
|
+
|
1293
|
+
`Zeitwerk::Error` is raised if the given path does not exist:
|
1294
|
+
|
1295
|
+
```ruby
|
1296
|
+
loader.cpath_expected_at("non_existing_file.rb") # => Zeitwerk::Error
|
1297
|
+
```
|
1298
|
+
|
1299
|
+
`Zeitwerk::NameError` is raised if a constant path cannot be derived from it:
|
1300
|
+
|
1301
|
+
```ruby
|
1302
|
+
loader.cpath_expected_at("8.rb") # => Zeitwerk::NameError
|
1303
|
+
```
|
1304
|
+
|
1305
|
+
This method does not parse file contents and does not guarantee files define the returned constant path. It just says which is the _expected_ one.
|
1306
|
+
|
1174
1307
|
<a id="markdown-encodings" name="encodings"></a>
|
1175
1308
|
### Encodings
|
1176
1309
|
|
@@ -1201,22 +1334,11 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
|
|
1201
1334
|
<a id="markdown-debuggers" name="debuggers"></a>
|
1202
1335
|
### Debuggers
|
1203
1336
|
|
1204
|
-
|
1205
|
-
#### debug.rb
|
1206
|
-
|
1207
|
-
The new [debug.rb](https://github.com/ruby/debug) gem and Zeitwerk are mostly compatible. This is the new debugger that is going to ship with Ruby 3.1.
|
1208
|
-
|
1209
|
-
There's one exception, though: Due to a technical limitation of tracepoints, explicit namespaces are not autoloaded while expressions are evaluated in the REPL. See [ruby/debug#408](https://github.com/ruby/debug/issues/408).
|
1210
|
-
|
1211
|
-
<a id="markdown-byebug" name="byebug"></a>
|
1212
|
-
#### Byebug
|
1213
|
-
|
1214
|
-
Zeitwerk and [Byebug](https://github.com/deivid-rodriguez/byebug) have a similar edge incompatibility.
|
1337
|
+
Zeitwerk and [debug.rb](https://github.com/ruby/debug) are fully compatible if CRuby is ≥ 3.1 (see [ruby/debug#558](https://github.com/ruby/debug/pull/558)).
|
1215
1338
|
|
1216
|
-
|
1217
|
-
#### Break
|
1339
|
+
[Byebug](https://github.com/deivid-rodriguez/byebug) is compatible except for an edge case explained in [deivid-rodriguez/byebug#564](https://github.com/deivid-rodriguez/byebug/issues/564). Prior to CRuby 3.1, `debug.rb` has a similar edge incompatibility.
|
1218
1340
|
|
1219
|
-
|
1341
|
+
[Break](https://github.com/gsamokovarov/break) is fully compatible.
|
1220
1342
|
|
1221
1343
|
<a id="markdown-pronunciation" name="pronunciation"></a>
|
1222
1344
|
## Pronunciation
|
@@ -47,6 +47,13 @@ module Zeitwerk
|
|
47
47
|
disable_tracer_if_unneeded
|
48
48
|
end
|
49
49
|
|
50
|
+
# This is an internal method only used by the test suite.
|
51
|
+
#
|
52
|
+
# @sig (String) -> bool
|
53
|
+
internal def registered?(cpath)
|
54
|
+
cpaths.key?(cpath)
|
55
|
+
end
|
56
|
+
|
50
57
|
# @sig () -> void
|
51
58
|
private def disable_tracer_if_unneeded
|
52
59
|
mutex.synchronize do
|
@@ -5,8 +5,8 @@ module Zeitwerk
|
|
5
5
|
# @sig (String) -> void
|
6
6
|
def initialize(root_file)
|
7
7
|
namespace = File.basename(root_file, ".rb")
|
8
|
-
|
9
|
-
@version_file = File.join(
|
8
|
+
root_dir = File.dirname(root_file)
|
9
|
+
@version_file = File.join(root_dir, namespace, "version.rb")
|
10
10
|
end
|
11
11
|
|
12
12
|
# @sig (String, String) -> String
|
data/lib/zeitwerk/gem_loader.rb
CHANGED
@@ -3,27 +3,31 @@
|
|
3
3
|
module Zeitwerk
|
4
4
|
# @private
|
5
5
|
class GemLoader < Loader
|
6
|
+
include RealModName
|
7
|
+
|
6
8
|
# Users should not create instances directly, the public interface is
|
7
9
|
# `Zeitwerk::Loader.for_gem`.
|
8
10
|
private_class_method :new
|
9
11
|
|
10
12
|
# @private
|
11
13
|
# @sig (String, bool) -> Zeitwerk::GemLoader
|
12
|
-
def self.
|
13
|
-
new(root_file, warn_on_extra_files: warn_on_extra_files)
|
14
|
+
def self.__new(root_file, namespace:, warn_on_extra_files:)
|
15
|
+
new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
|
14
16
|
end
|
15
17
|
|
16
18
|
# @sig (String, bool) -> void
|
17
|
-
def initialize(root_file, warn_on_extra_files:)
|
19
|
+
def initialize(root_file, namespace:, warn_on_extra_files:)
|
18
20
|
super()
|
19
21
|
|
20
|
-
@tag
|
22
|
+
@tag = File.basename(root_file, ".rb")
|
23
|
+
@tag = real_mod_name(namespace) + "-" + @tag unless namespace.equal?(Object)
|
24
|
+
|
21
25
|
@inflector = GemInflector.new(root_file)
|
22
26
|
@root_file = File.expand_path(root_file)
|
23
|
-
@
|
27
|
+
@root_dir = File.dirname(root_file)
|
24
28
|
@warn_on_extra_files = warn_on_extra_files
|
25
29
|
|
26
|
-
push_dir(@
|
30
|
+
push_dir(@root_dir, namespace: namespace)
|
27
31
|
end
|
28
32
|
|
29
33
|
# @sig () -> void
|
@@ -38,7 +42,7 @@ module Zeitwerk
|
|
38
42
|
def warn_on_extra_files
|
39
43
|
expected_namespace_dir = @root_file.delete_suffix(".rb")
|
40
44
|
|
41
|
-
ls(@
|
45
|
+
ls(@root_dir) do |basename, abspath|
|
42
46
|
next if abspath == @root_file
|
43
47
|
next if abspath == expected_namespace_dir
|
44
48
|
|
data/lib/zeitwerk/kernel.rb
CHANGED
@@ -28,10 +28,10 @@ module Kernel
|
|
28
28
|
if loader = Zeitwerk::Registry.loader_for(path)
|
29
29
|
if path.end_with?(".rb")
|
30
30
|
required = zeitwerk_original_require(path)
|
31
|
-
loader.
|
31
|
+
loader.__on_file_autoloaded(path) if required
|
32
32
|
required
|
33
33
|
else
|
34
|
-
loader.
|
34
|
+
loader.__on_dir_autoloaded(path)
|
35
35
|
true
|
36
36
|
end
|
37
37
|
else
|
@@ -39,7 +39,7 @@ module Kernel
|
|
39
39
|
if required
|
40
40
|
abspath = $LOADED_FEATURES.last
|
41
41
|
if loader = Zeitwerk::Registry.loader_for(abspath)
|
42
|
-
loader.
|
42
|
+
loader.__on_file_autoloaded(abspath)
|
43
43
|
end
|
44
44
|
end
|
45
45
|
required
|
@@ -2,38 +2,46 @@
|
|
2
2
|
|
3
3
|
module Zeitwerk::Loader::Callbacks
|
4
4
|
include Zeitwerk::RealModName
|
5
|
+
extend Zeitwerk::Internal
|
5
6
|
|
6
7
|
# Invoked from our decorated Kernel#require when a managed file is autoloaded.
|
7
8
|
#
|
8
|
-
# @private
|
9
9
|
# @sig (String) -> void
|
10
|
-
def on_file_autoloaded(file)
|
10
|
+
internal def on_file_autoloaded(file)
|
11
11
|
cref = autoloads.delete(file)
|
12
12
|
cpath = cpath(*cref)
|
13
13
|
|
14
|
-
# If reloading is enabled, we need to put this constant for unloading
|
15
|
-
# regardless of what cdef? says. In Ruby < 3.1 the internal state is not
|
16
|
-
# fully cleared. Module#constants still includes it, and you need to
|
17
|
-
# remove_const. See https://github.com/ruby/ruby/pull/4715.
|
18
|
-
to_unload[cpath] = [file, cref] if reloading_enabled?
|
19
14
|
Zeitwerk::Registry.unregister_autoload(file)
|
20
15
|
|
21
16
|
if cdef?(*cref)
|
22
17
|
log("constant #{cpath} loaded from file #{file}") if logger
|
18
|
+
to_unload[cpath] = [file, cref] if reloading_enabled?
|
23
19
|
run_on_load_callbacks(cpath, cget(*cref), file) unless on_load_callbacks.empty?
|
24
20
|
else
|
25
|
-
|
21
|
+
msg = "expected file #{file} to define constant #{cpath}, but didn't"
|
22
|
+
log(msg) if logger
|
23
|
+
|
24
|
+
# Ruby still keeps the autoload defined, but we remove it because the
|
25
|
+
# contract in Zeitwerk is more strict.
|
26
|
+
crem(*cref)
|
27
|
+
|
28
|
+
# Since the expected constant was not defined, there is nothing to unload.
|
29
|
+
# However, if the exception is rescued and reloading is enabled, we still
|
30
|
+
# need to deleted the file from $LOADED_FEATURES.
|
31
|
+
to_unload[cpath] = [file, cref] if reloading_enabled?
|
32
|
+
|
33
|
+
raise Zeitwerk::NameError.new(msg, cref.last)
|
26
34
|
end
|
27
35
|
end
|
28
36
|
|
29
37
|
# Invoked from our decorated Kernel#require when a managed directory is
|
30
38
|
# autoloaded.
|
31
39
|
#
|
32
|
-
# @private
|
33
40
|
# @sig (String) -> void
|
34
|
-
def on_dir_autoloaded(dir)
|
35
|
-
# Module#autoload does not serialize concurrent requires, and
|
36
|
-
# directories ourselves
|
41
|
+
internal def on_dir_autoloaded(dir)
|
42
|
+
# Module#autoload does not serialize concurrent requires in CRuby < 3.2, and
|
43
|
+
# we handle directories ourselves without going through Kernel#require, so
|
44
|
+
# the callback needs to account for concurrency.
|
37
45
|
#
|
38
46
|
# Multi-threading would introduce a race condition here in which thread t1
|
39
47
|
# autovivifies the module, and while autoloads for its children are being
|
@@ -43,7 +51,7 @@ module Zeitwerk::Loader::Callbacks
|
|
43
51
|
# That not only would reassign the constant (undesirable per se) but, worse,
|
44
52
|
# the module object created by t2 wouldn't have any of the autoloads for its
|
45
53
|
# children, since t1 would have correctly deleted its namespace_dirs entry.
|
46
|
-
|
54
|
+
dirs_autoload_monitor.synchronize do
|
47
55
|
if cref = autoloads.delete(dir)
|
48
56
|
autovivified_module = cref[0].const_set(cref[1], Module.new)
|
49
57
|
cpath = autovivified_module.name
|
@@ -73,7 +81,7 @@ module Zeitwerk::Loader::Callbacks
|
|
73
81
|
def on_namespace_loaded(namespace)
|
74
82
|
if dirs = namespace_dirs.delete(real_mod_name(namespace))
|
75
83
|
dirs.each do |dir|
|
76
|
-
|
84
|
+
define_autoloads_for_dir(dir, namespace)
|
77
85
|
end
|
78
86
|
end
|
79
87
|
end
|
@@ -109,8 +109,7 @@ module Zeitwerk::Loader::Config
|
|
109
109
|
# @raise [Zeitwerk::Error]
|
110
110
|
# @sig (String | Pathname, Module) -> void
|
111
111
|
def push_dir(path, namespace: Object)
|
112
|
-
# Note that Class < Module.
|
113
|
-
unless namespace.is_a?(Module)
|
112
|
+
unless namespace.is_a?(Module) # Note that Class < Module.
|
114
113
|
raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
|
115
114
|
end
|
116
115
|
|
@@ -149,14 +148,24 @@ module Zeitwerk::Loader::Config
|
|
149
148
|
# instead. Keys are the absolute paths of the root directories as strings,
|
150
149
|
# values are their corresponding namespaces, class or module objects.
|
151
150
|
#
|
151
|
+
# If `ignored` is falsey (default), ignored root directories are filtered out.
|
152
|
+
#
|
152
153
|
# These are read-only collections, please add to them with `push_dir`.
|
153
154
|
#
|
154
155
|
# @sig () -> Array[String] | Hash[String, Module]
|
155
|
-
def dirs(namespaces: false)
|
156
|
+
def dirs(namespaces: false, ignored: false)
|
156
157
|
if namespaces
|
157
|
-
|
158
|
+
if ignored || ignored_paths.empty?
|
159
|
+
roots.clone
|
160
|
+
else
|
161
|
+
roots.reject { |root_dir, _namespace| ignored_path?(root_dir) }
|
162
|
+
end
|
158
163
|
else
|
159
|
-
|
164
|
+
if ignored || ignored_paths.empty?
|
165
|
+
roots.keys
|
166
|
+
else
|
167
|
+
roots.keys.reject { |root_dir| ignored_path?(root_dir) }
|
168
|
+
end
|
160
169
|
end.freeze
|
161
170
|
end
|
162
171
|
|
@@ -288,9 +297,9 @@ module Zeitwerk::Loader::Config
|
|
288
297
|
# Common use case.
|
289
298
|
return false if ignored_paths.empty?
|
290
299
|
|
291
|
-
walk_up(abspath) do |
|
292
|
-
return true if ignored_path?(
|
293
|
-
return false if roots.key?(
|
300
|
+
walk_up(abspath) do |path|
|
301
|
+
return true if ignored_path?(path)
|
302
|
+
return false if roots.key?(path)
|
294
303
|
end
|
295
304
|
|
296
305
|
false
|
@@ -318,9 +327,9 @@ module Zeitwerk::Loader::Config
|
|
318
327
|
# Optimize this common use case.
|
319
328
|
return false if eager_load_exclusions.empty?
|
320
329
|
|
321
|
-
walk_up(abspath) do |
|
322
|
-
return true if eager_load_exclusions.member?(
|
323
|
-
return false if roots.key?(
|
330
|
+
walk_up(abspath) do |path|
|
331
|
+
return true if eager_load_exclusions.member?(path)
|
332
|
+
return false if roots.key?(path)
|
324
333
|
end
|
325
334
|
|
326
335
|
false
|
@@ -45,8 +45,10 @@ module Zeitwerk::Loader::EagerLoad
|
|
45
45
|
|
46
46
|
break if root_namespace = roots[dir]
|
47
47
|
|
48
|
+
basename = File.basename(dir)
|
49
|
+
return if hidden?(basename)
|
50
|
+
|
48
51
|
unless collapse?(dir)
|
49
|
-
basename = File.basename(dir)
|
50
52
|
cnames << inflector.camelize(basename, dir).to_sym
|
51
53
|
end
|
52
54
|
end
|
@@ -119,6 +121,8 @@ module Zeitwerk::Loader::EagerLoad
|
|
119
121
|
raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(abspath)
|
120
122
|
|
121
123
|
basename = File.basename(abspath, ".rb")
|
124
|
+
raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
|
125
|
+
|
122
126
|
base_cname = inflector.camelize(basename, abspath).to_sym
|
123
127
|
|
124
128
|
root_namespace = nil
|
@@ -129,8 +133,10 @@ module Zeitwerk::Loader::EagerLoad
|
|
129
133
|
|
130
134
|
break if root_namespace = roots[dir]
|
131
135
|
|
136
|
+
basename = File.basename(dir)
|
137
|
+
raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
|
138
|
+
|
132
139
|
unless collapse?(dir)
|
133
|
-
basename = File.basename(dir)
|
134
140
|
cnames << inflector.camelize(basename, dir).to_sym
|
135
141
|
end
|
136
142
|
end
|
@@ -165,7 +171,7 @@ module Zeitwerk::Loader::EagerLoad
|
|
165
171
|
next if honour_exclusions && eager_load_exclusions.member?(abspath)
|
166
172
|
|
167
173
|
if ruby?(abspath)
|
168
|
-
if (cref = autoloads[abspath])
|
174
|
+
if (cref = autoloads[abspath])
|
169
175
|
cget(*cref)
|
170
176
|
end
|
171
177
|
else
|
@@ -183,7 +189,7 @@ module Zeitwerk::Loader::EagerLoad
|
|
183
189
|
end
|
184
190
|
|
185
191
|
# In order to invoke this method, the caller has to ensure `child` is a
|
186
|
-
# strict namespace
|
192
|
+
# strict namespace descendant of `root_namespace`.
|
187
193
|
#
|
188
194
|
# @sig (Module, String, Module, Boolean) -> void
|
189
195
|
private def eager_load_child_namespace(child, child_name, root_dir, root_namespace)
|
@@ -134,4 +134,54 @@ module Zeitwerk::Loader::Helpers
|
|
134
134
|
private def cget(parent, cname)
|
135
135
|
parent.const_get(cname, false)
|
136
136
|
end
|
137
|
+
|
138
|
+
# @raise [NameError]
|
139
|
+
# @sig (Module, Symbol) -> Object
|
140
|
+
private def crem(parent, cname)
|
141
|
+
parent.__send__(:remove_const, cname)
|
142
|
+
end
|
143
|
+
|
144
|
+
CNAME_VALIDATOR = Module.new
|
145
|
+
private_constant :CNAME_VALIDATOR
|
146
|
+
|
147
|
+
# @raise [Zeitwerk::NameError]
|
148
|
+
# @sig (String, String) -> Symbol
|
149
|
+
private def cname_for(basename, abspath)
|
150
|
+
cname = inflector.camelize(basename, abspath)
|
151
|
+
|
152
|
+
unless cname.is_a?(String)
|
153
|
+
raise TypeError, "#{inflector.class}#camelize must return a String, received #{cname.inspect}"
|
154
|
+
end
|
155
|
+
|
156
|
+
if cname.include?("::")
|
157
|
+
raise Zeitwerk::NameError.new(<<~MESSAGE, cname)
|
158
|
+
wrong constant name #{cname} inferred by #{inflector.class} from
|
159
|
+
|
160
|
+
#{abspath}
|
161
|
+
|
162
|
+
#{inflector.class}#camelize should return a simple constant name without "::"
|
163
|
+
MESSAGE
|
164
|
+
end
|
165
|
+
|
166
|
+
begin
|
167
|
+
CNAME_VALIDATOR.const_defined?(cname, false)
|
168
|
+
rescue ::NameError => error
|
169
|
+
path_type = ruby?(abspath) ? "file" : "directory"
|
170
|
+
|
171
|
+
raise Zeitwerk::NameError.new(<<~MESSAGE, error.name)
|
172
|
+
#{error.message} inferred by #{inflector.class} from #{path_type}
|
173
|
+
|
174
|
+
#{abspath}
|
175
|
+
|
176
|
+
Possible ways to address this:
|
177
|
+
|
178
|
+
* Tell Zeitwerk to ignore this particular #{path_type}.
|
179
|
+
* Tell Zeitwerk to ignore one of its parent directories.
|
180
|
+
* Rename the #{path_type} to comply with the naming conventions.
|
181
|
+
* Modify the inflector to handle this case.
|
182
|
+
MESSAGE
|
183
|
+
end
|
184
|
+
|
185
|
+
cname.to_sym
|
186
|
+
end
|
137
187
|
end
|
data/lib/zeitwerk/loader.rb
CHANGED
@@ -1,5 +1,6 @@
|
|
1
1
|
# frozen_string_literal: true
|
2
2
|
|
3
|
+
require "monitor"
|
3
4
|
require "set"
|
4
5
|
|
5
6
|
module Zeitwerk
|
@@ -9,6 +10,8 @@ module Zeitwerk
|
|
9
10
|
require_relative "loader/config"
|
10
11
|
require_relative "loader/eager_load"
|
11
12
|
|
13
|
+
extend Internal
|
14
|
+
|
12
15
|
include RealModName
|
13
16
|
include Callbacks
|
14
17
|
include Helpers
|
@@ -26,9 +29,9 @@ module Zeitwerk
|
|
26
29
|
# "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
|
27
30
|
# ...
|
28
31
|
#
|
29
|
-
# @private
|
30
32
|
# @sig Hash[String, [Module, Symbol]]
|
31
33
|
attr_reader :autoloads
|
34
|
+
internal :autoloads
|
32
35
|
|
33
36
|
# We keep track of autoloaded directories to remove them from the registry
|
34
37
|
# at the end of eager loading.
|
@@ -36,9 +39,9 @@ module Zeitwerk
|
|
36
39
|
# Files are removed as they are autoloaded, but directories need to wait due
|
37
40
|
# to concurrency (see why in Zeitwerk::Loader::Callbacks#on_dir_autoloaded).
|
38
41
|
#
|
39
|
-
# @private
|
40
42
|
# @sig Array[String]
|
41
43
|
attr_reader :autoloaded_dirs
|
44
|
+
internal :autoloaded_dirs
|
42
45
|
|
43
46
|
# Stores metadata needed for unloading. Its entries look like this:
|
44
47
|
#
|
@@ -52,9 +55,9 @@ module Zeitwerk
|
|
52
55
|
# If reloading is enabled, this hash is filled as constants are autoloaded
|
53
56
|
# or eager loaded. Otherwise, the collection remains empty.
|
54
57
|
#
|
55
|
-
# @private
|
56
58
|
# @sig Hash[String, [String, [Module, Symbol]]]
|
57
59
|
attr_reader :to_unload
|
60
|
+
internal :to_unload
|
58
61
|
|
59
62
|
# Maps namespace constant paths to their respective directories.
|
60
63
|
#
|
@@ -70,9 +73,9 @@ module Zeitwerk
|
|
70
73
|
# and that its children are spread over those directories. We'll visit them
|
71
74
|
# to set up the corresponding autoloads.
|
72
75
|
#
|
73
|
-
# @private
|
74
76
|
# @sig Hash[String, Array[String]]
|
75
77
|
attr_reader :namespace_dirs
|
78
|
+
internal :namespace_dirs
|
76
79
|
|
77
80
|
# A shadowed file is a file managed by this loader that is ignored when
|
78
81
|
# setting autoloads because its matching constant is already taken.
|
@@ -81,17 +84,17 @@ module Zeitwerk
|
|
81
84
|
# has only scanned the top-level, `shadowed_files` does not have shadowed
|
82
85
|
# files that may exist deep in the project tree yet.
|
83
86
|
#
|
84
|
-
# @private
|
85
87
|
# @sig Set[String]
|
86
88
|
attr_reader :shadowed_files
|
89
|
+
internal :shadowed_files
|
87
90
|
|
88
|
-
# @private
|
89
91
|
# @sig Mutex
|
90
92
|
attr_reader :mutex
|
93
|
+
private :mutex
|
91
94
|
|
92
|
-
# @
|
93
|
-
|
94
|
-
|
95
|
+
# @sig Monitor
|
96
|
+
attr_reader :dirs_autoload_monitor
|
97
|
+
private :dirs_autoload_monitor
|
95
98
|
|
96
99
|
def initialize
|
97
100
|
super
|
@@ -101,11 +104,12 @@ module Zeitwerk
|
|
101
104
|
@to_unload = {}
|
102
105
|
@namespace_dirs = Hash.new { |h, cpath| h[cpath] = [] }
|
103
106
|
@shadowed_files = Set.new
|
104
|
-
@mutex = Mutex.new
|
105
|
-
@mutex2 = Mutex.new
|
106
107
|
@setup = false
|
107
108
|
@eager_loaded = false
|
108
109
|
|
110
|
+
@mutex = Mutex.new
|
111
|
+
@dirs_autoload_monitor = Monitor.new
|
112
|
+
|
109
113
|
Registry.register_loader(self)
|
110
114
|
end
|
111
115
|
|
@@ -117,7 +121,7 @@ module Zeitwerk
|
|
117
121
|
break if @setup
|
118
122
|
|
119
123
|
actual_roots.each do |root_dir, root_namespace|
|
120
|
-
|
124
|
+
define_autoloads_for_dir(root_dir, root_namespace)
|
121
125
|
end
|
122
126
|
|
123
127
|
on_setup_callbacks.each(&:call)
|
@@ -134,7 +138,7 @@ module Zeitwerk
|
|
134
138
|
# unload them.
|
135
139
|
#
|
136
140
|
# This method is public but undocumented. Main interface is `reload`, which
|
137
|
-
# means `unload` + `setup`. This one is
|
141
|
+
# means `unload` + `setup`. This one is available to be used together with
|
138
142
|
# `unregister`, which is undocumented too.
|
139
143
|
#
|
140
144
|
# @sig () -> void
|
@@ -226,6 +230,54 @@ module Zeitwerk
|
|
226
230
|
setup
|
227
231
|
end
|
228
232
|
|
233
|
+
# @sig (String | Pathname) -> String?
|
234
|
+
def cpath_expected_at(path)
|
235
|
+
abspath = File.expand_path(path)
|
236
|
+
|
237
|
+
raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
|
238
|
+
|
239
|
+
return unless dir?(abspath) || ruby?(abspath)
|
240
|
+
return if ignored_path?(abspath)
|
241
|
+
|
242
|
+
paths = []
|
243
|
+
|
244
|
+
if ruby?(abspath)
|
245
|
+
basename = File.basename(abspath, ".rb")
|
246
|
+
return if hidden?(basename)
|
247
|
+
|
248
|
+
paths << [basename, abspath]
|
249
|
+
walk_up_from = File.dirname(abspath)
|
250
|
+
else
|
251
|
+
walk_up_from = abspath
|
252
|
+
end
|
253
|
+
|
254
|
+
root_namespace = nil
|
255
|
+
|
256
|
+
walk_up(walk_up_from) do |dir|
|
257
|
+
break if root_namespace = roots[dir]
|
258
|
+
return if ignored_path?(dir)
|
259
|
+
|
260
|
+
basename = File.basename(dir)
|
261
|
+
return if hidden?(basename)
|
262
|
+
|
263
|
+
paths << [basename, abspath] unless collapse?(dir)
|
264
|
+
end
|
265
|
+
|
266
|
+
return unless root_namespace
|
267
|
+
|
268
|
+
if paths.empty?
|
269
|
+
real_mod_name(root_namespace)
|
270
|
+
else
|
271
|
+
cnames = paths.reverse_each.map { |b, a| cname_for(b, a) }
|
272
|
+
|
273
|
+
if root_namespace == Object
|
274
|
+
cnames.join("::")
|
275
|
+
else
|
276
|
+
"#{real_mod_name(root_namespace)}::#{cnames.join("::")}"
|
277
|
+
end
|
278
|
+
end
|
279
|
+
end
|
280
|
+
|
229
281
|
# Says if the given constant path would be unloaded on reload. This
|
230
282
|
# predicate returns `false` if reloading is disabled.
|
231
283
|
#
|
@@ -254,21 +306,23 @@ module Zeitwerk
|
|
254
306
|
# The return value of this predicate is only meaningful if the loader has
|
255
307
|
# scanned the file. This is the case in the spots where we use it.
|
256
308
|
#
|
257
|
-
# @private
|
258
309
|
# @sig (String) -> Boolean
|
259
|
-
def shadowed_file?(file)
|
310
|
+
internal def shadowed_file?(file)
|
260
311
|
shadowed_files.member?(file)
|
261
312
|
end
|
262
313
|
|
263
314
|
# --- Class methods ---------------------------------------------------------------------------
|
264
315
|
|
265
316
|
class << self
|
317
|
+
include RealModName
|
318
|
+
|
266
319
|
# @sig #call | #debug | nil
|
267
320
|
attr_accessor :default_logger
|
268
321
|
|
269
322
|
# This is a shortcut for
|
270
323
|
#
|
271
324
|
# require "zeitwerk"
|
325
|
+
#
|
272
326
|
# loader = Zeitwerk::Loader.new
|
273
327
|
# loader.tag = File.basename(__FILE__, ".rb")
|
274
328
|
# loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
|
@@ -283,7 +337,36 @@ module Zeitwerk
|
|
283
337
|
# @sig (bool) -> Zeitwerk::GemLoader
|
284
338
|
def for_gem(warn_on_extra_files: true)
|
285
339
|
called_from = caller_locations(1, 1).first.path
|
286
|
-
Registry.loader_for_gem(called_from, warn_on_extra_files: warn_on_extra_files)
|
340
|
+
Registry.loader_for_gem(called_from, namespace: Object, warn_on_extra_files: warn_on_extra_files)
|
341
|
+
end
|
342
|
+
|
343
|
+
# This is a shortcut for
|
344
|
+
#
|
345
|
+
# require "zeitwerk"
|
346
|
+
#
|
347
|
+
# loader = Zeitwerk::Loader.new
|
348
|
+
# loader.tag = namespace.name + "-" + File.basename(__FILE__, ".rb")
|
349
|
+
# loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
|
350
|
+
# loader.push_dir(__dir__, namespace: namespace)
|
351
|
+
#
|
352
|
+
# except that this method returns the same object in subsequent calls from
|
353
|
+
# the same file, in the unlikely case the gem wants to be able to reload.
|
354
|
+
#
|
355
|
+
# This method returns a subclass of Zeitwerk::Loader, but the exact type
|
356
|
+
# is private, client code can only rely on the interface.
|
357
|
+
#
|
358
|
+
# @sig (bool) -> Zeitwerk::GemLoader
|
359
|
+
def for_gem_extension(namespace)
|
360
|
+
unless namespace.is_a?(Module) # Note that Class < Module.
|
361
|
+
raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
|
362
|
+
end
|
363
|
+
|
364
|
+
unless real_mod_name(namespace)
|
365
|
+
raise Zeitwerk::Error, "extending anonymous namespaces is unsupported"
|
366
|
+
end
|
367
|
+
|
368
|
+
called_from = caller_locations(1, 1).first.path
|
369
|
+
Registry.loader_for_gem(called_from, namespace: namespace, warn_on_extra_files: false)
|
287
370
|
end
|
288
371
|
|
289
372
|
# Broadcasts `eager_load` to all loaders. Those that have not been setup
|
@@ -323,66 +406,54 @@ module Zeitwerk
|
|
323
406
|
end
|
324
407
|
end
|
325
408
|
|
326
|
-
private # -------------------------------------------------------------------------------------
|
327
|
-
|
328
409
|
# @sig (String, Module) -> void
|
329
|
-
def
|
410
|
+
private def define_autoloads_for_dir(dir, parent)
|
330
411
|
ls(dir) do |basename, abspath|
|
331
|
-
|
332
|
-
|
333
|
-
|
334
|
-
|
335
|
-
|
412
|
+
if ruby?(basename)
|
413
|
+
basename.delete_suffix!(".rb")
|
414
|
+
autoload_file(parent, cname_for(basename, abspath), abspath)
|
415
|
+
else
|
416
|
+
if collapse?(abspath)
|
417
|
+
define_autoloads_for_dir(abspath, parent)
|
336
418
|
else
|
337
|
-
|
338
|
-
set_autoloads_in_dir(abspath, parent)
|
339
|
-
else
|
340
|
-
cname = inflector.camelize(basename, abspath).to_sym
|
341
|
-
autoload_subdir(parent, cname, abspath)
|
342
|
-
end
|
419
|
+
autoload_subdir(parent, cname_for(basename, abspath), abspath)
|
343
420
|
end
|
344
|
-
rescue ::NameError => error
|
345
|
-
path_type = ruby?(abspath) ? "file" : "directory"
|
346
|
-
|
347
|
-
raise NameError.new(<<~MESSAGE, error.name)
|
348
|
-
#{error.message} inferred by #{inflector.class} from #{path_type}
|
349
|
-
|
350
|
-
#{abspath}
|
351
|
-
|
352
|
-
Possible ways to address this:
|
353
|
-
|
354
|
-
* Tell Zeitwerk to ignore this particular #{path_type}.
|
355
|
-
* Tell Zeitwerk to ignore one of its parent directories.
|
356
|
-
* Rename the #{path_type} to comply with the naming conventions.
|
357
|
-
* Modify the inflector to handle this case.
|
358
|
-
MESSAGE
|
359
421
|
end
|
360
422
|
end
|
361
423
|
end
|
362
424
|
|
363
425
|
# @sig (Module, Symbol, String) -> void
|
364
|
-
def autoload_subdir(parent, cname, subdir)
|
426
|
+
private def autoload_subdir(parent, cname, subdir)
|
365
427
|
if autoload_path = autoload_path_set_by_me_for?(parent, cname)
|
366
428
|
cpath = cpath(parent, cname)
|
367
|
-
|
368
|
-
|
369
|
-
|
370
|
-
|
429
|
+
if ruby?(autoload_path)
|
430
|
+
# Scanning visited a Ruby file first, and now a directory for the same
|
431
|
+
# constant has been found. This means we are dealing with an explicit
|
432
|
+
# namespace whose definition was seen first.
|
433
|
+
#
|
434
|
+
# Registering is idempotent, and we have to keep the autoload pointing
|
435
|
+
# to the file. This may run again if more directories are found later
|
436
|
+
# on, no big deal.
|
437
|
+
register_explicit_namespace(cpath)
|
438
|
+
end
|
439
|
+
# If the existing autoload points to a file, it has to be preserved, if
|
440
|
+
# not, it is fine as it is. In either case, we do not need to override.
|
441
|
+
# Just remember the subdirectory conforms this namespace.
|
371
442
|
namespace_dirs[cpath] << subdir
|
372
443
|
elsif !cdef?(parent, cname)
|
373
444
|
# First time we find this namespace, set an autoload for it.
|
374
445
|
namespace_dirs[cpath(parent, cname)] << subdir
|
375
|
-
|
446
|
+
define_autoload(parent, cname, subdir)
|
376
447
|
else
|
377
448
|
# For whatever reason the constant that corresponds to this namespace has
|
378
449
|
# already been defined, we have to recurse.
|
379
450
|
log("the namespace #{cpath(parent, cname)} already exists, descending into #{subdir}") if logger
|
380
|
-
|
451
|
+
define_autoloads_for_dir(subdir, cget(parent, cname))
|
381
452
|
end
|
382
453
|
end
|
383
454
|
|
384
455
|
# @sig (Module, Symbol, String) -> void
|
385
|
-
def autoload_file(parent, cname, file)
|
456
|
+
private def autoload_file(parent, cname, file)
|
386
457
|
if autoload_path = strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
|
387
458
|
# First autoload for a Ruby file wins, just ignore subsequent ones.
|
388
459
|
if ruby?(autoload_path)
|
@@ -400,7 +471,7 @@ module Zeitwerk
|
|
400
471
|
shadowed_files << file
|
401
472
|
log("file #{file} is ignored because #{cpath(parent, cname)} is already defined") if logger
|
402
473
|
else
|
403
|
-
|
474
|
+
define_autoload(parent, cname, file)
|
404
475
|
end
|
405
476
|
end
|
406
477
|
|
@@ -408,18 +479,18 @@ module Zeitwerk
|
|
408
479
|
# the file where we've found the namespace is explicitly defined.
|
409
480
|
#
|
410
481
|
# @sig (dir: String, file: String, parent: Module, cname: Symbol) -> void
|
411
|
-
def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
|
482
|
+
private def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
|
412
483
|
autoloads.delete(dir)
|
413
484
|
Registry.unregister_autoload(dir)
|
414
485
|
|
415
486
|
log("earlier autoload for #{cpath(parent, cname)} discarded, it is actually an explicit namespace defined in #{file}") if logger
|
416
487
|
|
417
|
-
|
488
|
+
define_autoload(parent, cname, file)
|
418
489
|
register_explicit_namespace(cpath(parent, cname))
|
419
490
|
end
|
420
491
|
|
421
492
|
# @sig (Module, Symbol, String) -> void
|
422
|
-
def
|
493
|
+
private def define_autoload(parent, cname, abspath)
|
423
494
|
parent.autoload(cname, abspath)
|
424
495
|
|
425
496
|
if logger
|
@@ -440,7 +511,7 @@ module Zeitwerk
|
|
440
511
|
end
|
441
512
|
|
442
513
|
# @sig (Module, Symbol) -> String?
|
443
|
-
def autoload_path_set_by_me_for?(parent, cname)
|
514
|
+
private def autoload_path_set_by_me_for?(parent, cname)
|
444
515
|
if autoload_path = strict_autoload_path(parent, cname)
|
445
516
|
autoload_path if autoloads.key?(autoload_path)
|
446
517
|
else
|
@@ -449,12 +520,12 @@ module Zeitwerk
|
|
449
520
|
end
|
450
521
|
|
451
522
|
# @sig (String) -> void
|
452
|
-
def register_explicit_namespace(cpath)
|
523
|
+
private def register_explicit_namespace(cpath)
|
453
524
|
ExplicitNamespace.__register(cpath, self)
|
454
525
|
end
|
455
526
|
|
456
527
|
# @sig (String) -> void
|
457
|
-
def raise_if_conflicting_directory(dir)
|
528
|
+
private def raise_if_conflicting_directory(dir)
|
458
529
|
MUTEX.synchronize do
|
459
530
|
dir_slash = dir + "/"
|
460
531
|
|
@@ -471,7 +542,6 @@ module Zeitwerk
|
|
471
542
|
raise Error,
|
472
543
|
"loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir}," \
|
473
544
|
" which is already managed by\n\n#{loader.pretty_inspect}\n"
|
474
|
-
EOS
|
475
545
|
end
|
476
546
|
end
|
477
547
|
end
|
@@ -479,23 +549,23 @@ module Zeitwerk
|
|
479
549
|
end
|
480
550
|
|
481
551
|
# @sig (String, Object, String) -> void
|
482
|
-
def run_on_unload_callbacks(cpath, value, abspath)
|
552
|
+
private def run_on_unload_callbacks(cpath, value, abspath)
|
483
553
|
# Order matters. If present, run the most specific one.
|
484
554
|
on_unload_callbacks[cpath]&.each { |c| c.call(value, abspath) }
|
485
555
|
on_unload_callbacks[:ANY]&.each { |c| c.call(cpath, value, abspath) }
|
486
556
|
end
|
487
557
|
|
488
558
|
# @sig (Module, Symbol) -> void
|
489
|
-
def unload_autoload(parent, cname)
|
490
|
-
parent
|
559
|
+
private def unload_autoload(parent, cname)
|
560
|
+
crem(parent, cname)
|
491
561
|
log("autoload for #{cpath(parent, cname)} removed") if logger
|
492
562
|
end
|
493
563
|
|
494
564
|
# @sig (Module, Symbol) -> void
|
495
|
-
def unload_cref(parent, cname)
|
565
|
+
private def unload_cref(parent, cname)
|
496
566
|
# Let's optimistically remove_const. The way we use it, this is going to
|
497
567
|
# succeed always if all is good.
|
498
|
-
parent
|
568
|
+
crem(parent, cname)
|
499
569
|
rescue ::NameError
|
500
570
|
# There are a few edge scenarios in which this may happen. If the constant
|
501
571
|
# is gone, that is OK, anyway.
|
data/lib/zeitwerk/registry.rb
CHANGED
@@ -86,8 +86,8 @@ module Zeitwerk
|
|
86
86
|
#
|
87
87
|
# @private
|
88
88
|
# @sig (String) -> Zeitwerk::Loader
|
89
|
-
def loader_for_gem(root_file, warn_on_extra_files:)
|
90
|
-
gem_loaders_by_root_file[root_file] ||= GemLoader.
|
89
|
+
def loader_for_gem(root_file, namespace:, warn_on_extra_files:)
|
90
|
+
gem_loaders_by_root_file[root_file] ||= GemLoader.__new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
|
91
91
|
end
|
92
92
|
|
93
93
|
# @private
|
data/lib/zeitwerk/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: zeitwerk
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 2.6.
|
4
|
+
version: 2.6.12
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Xavier Noria
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date:
|
11
|
+
date: 2023-09-25 00:00:00.000000000 Z
|
12
12
|
dependencies: []
|
13
13
|
description: |2
|
14
14
|
Zeitwerk implements constant autoloading with Ruby semantics. Each gem
|
@@ -61,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
61
61
|
- !ruby/object:Gem::Version
|
62
62
|
version: '0'
|
63
63
|
requirements: []
|
64
|
-
rubygems_version: 3.
|
64
|
+
rubygems_version: 3.4.16
|
65
65
|
signing_key:
|
66
66
|
specification_version: 4
|
67
67
|
summary: Efficient and thread-safe constant autoloader
|