zeitwerk 2.6.1 → 2.6.8
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +242 -34
- data/lib/zeitwerk/error.rb +6 -0
- data/lib/zeitwerk/explicit_namespace.rb +14 -10
- data/lib/zeitwerk/gem_inflector.rb +2 -2
- data/lib/zeitwerk/gem_loader.rb +12 -8
- data/lib/zeitwerk/internal.rb +12 -0
- data/lib/zeitwerk/kernel.rb +3 -0
- data/lib/zeitwerk/loader/callbacks.rb +10 -10
- data/lib/zeitwerk/loader/config.rb +83 -48
- data/lib/zeitwerk/loader/eager_load.rb +228 -0
- data/lib/zeitwerk/loader/helpers.rb +30 -16
- data/lib/zeitwerk/loader.rb +145 -114
- data/lib/zeitwerk/registry.rb +2 -2
- data/lib/zeitwerk/version.rb +1 -1
- data/lib/zeitwerk.rb +1 -0
- metadata +5 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 418f16f6224359c716a990f72ae916c980a3f388b09ab018c0972b8558530620
|
4
|
+
data.tar.gz: '04847c6c8f8f894fe3c2b3c39d175b5854b583d3a02ef5cca27a53cb1b8dafd4'
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: f86272e84721cf9b8b1e07182b1b60cfe732ef2c266dbe076225d32af52fc9a30c278a14651ddbb3d435636646dd23c948d3fe0f00ed9b8393abdeb34dd40028
|
7
|
+
data.tar.gz: 562738b53779310e899c2065c7046844d27daabb5f354972e4c9b65bec3e5c0cdade92d19ed815fe7b0dc01538603daa3e4dd2f0049fe9a7a2e74313c0f040f6
|
data/README.md
CHANGED
@@ -3,7 +3,7 @@
|
|
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%3main)
|
7
7
|
|
8
8
|
<!-- TOC -->
|
9
9
|
|
@@ -24,11 +24,18 @@
|
|
24
24
|
- [Setup](#setup)
|
25
25
|
- [Generic](#generic)
|
26
26
|
- [for_gem](#for_gem)
|
27
|
+
- [for_gem_extension](#for_gem_extension)
|
27
28
|
- [Autoloading](#autoloading)
|
28
29
|
- [Eager loading](#eager-loading)
|
29
30
|
- [Eager load exclusions](#eager-load-exclusions)
|
31
|
+
- [Eager load directories](#eager-load-directories)
|
32
|
+
- [Eager load namespaces](#eager-load-namespaces)
|
33
|
+
- [Eager load namespaces shared by several loaders](#eager-load-namespaces-shared-by-several-loaders)
|
30
34
|
- [Global eager load](#global-eager-load)
|
35
|
+
- [Loading individual files](#loading-individual-files)
|
31
36
|
- [Reloading](#reloading)
|
37
|
+
- [Configuration and usage](#configuration-and-usage)
|
38
|
+
- [Thread-safety](#thread-safety)
|
32
39
|
- [Inflection](#inflection)
|
33
40
|
- [Zeitwerk::Inflector](#zeitwerkinflector)
|
34
41
|
- [Zeitwerk::GemInflector](#zeitwerkgeminflector)
|
@@ -44,6 +51,7 @@
|
|
44
51
|
- [Use case: Files that do not follow the conventions](#use-case-files-that-do-not-follow-the-conventions)
|
45
52
|
- [Use case: The adapter pattern](#use-case-the-adapter-pattern)
|
46
53
|
- [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
|
54
|
+
- [Shadowed files](#shadowed-files)
|
47
55
|
- [Edge cases](#edge-cases)
|
48
56
|
- [Beware of circular dependencies](#beware-of-circular-dependencies)
|
49
57
|
- [Reopening third-party namespaces](#reopening-third-party-namespaces)
|
@@ -51,9 +59,6 @@
|
|
51
59
|
- [Encodings](#encodings)
|
52
60
|
- [Rules of thumb](#rules-of-thumb)
|
53
61
|
- [Debuggers](#debuggers)
|
54
|
-
- [debug.rb](#debugrb)
|
55
|
-
- [Byebug](#byebug)
|
56
|
-
- [Break](#break)
|
57
62
|
- [Pronunciation](#pronunciation)
|
58
63
|
- [Supported Ruby versions](#supported-ruby-versions)
|
59
64
|
- [Testing](#testing)
|
@@ -169,7 +174,7 @@ class HttpCrawler
|
|
169
174
|
end
|
170
175
|
```
|
171
176
|
|
172
|
-
The first example needs a custom [inflection](
|
177
|
+
The first example needs a custom [inflection](#inflection) rule:
|
173
178
|
|
174
179
|
```ruby
|
175
180
|
loader.inflector.inflect("max_retries" => "MAX_RETRIES")
|
@@ -206,7 +211,7 @@ serializers/user_serializer.rb -> UserSerializer
|
|
206
211
|
<a id="markdown-custom-root-namespaces" name="custom-root-namespaces"></a>
|
207
212
|
#### Custom root namespaces
|
208
213
|
|
209
|
-
While `Object` is by far the most common root namespace, you can associate a different one to a particular root directory. The method `push_dir` accepts a class or module object in the optional `namespace` keyword argument.
|
214
|
+
While `Object` is by far the most common root namespace, you can associate a different one to a particular root directory. The method `push_dir` accepts a non-anonymous class or module object in the optional `namespace` keyword argument.
|
210
215
|
|
211
216
|
For example, given:
|
212
217
|
|
@@ -384,6 +389,12 @@ module MyGem
|
|
384
389
|
end
|
385
390
|
```
|
386
391
|
|
392
|
+
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.
|
393
|
+
|
394
|
+
`Zeitwerk::Loader.for_gem` is idempotent when invoked from the same file, to support gems that want to reload (unlikely).
|
395
|
+
|
396
|
+
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.
|
397
|
+
|
387
398
|
Loaders returned by `Zeitwerk::Loader.for_gem` issue warnings if `lib` has extra Ruby files or directories.
|
388
399
|
|
389
400
|
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.
|
@@ -400,9 +411,64 @@ Otherwise, there's a flag to say the extra stuff is OK:
|
|
400
411
|
Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
|
401
412
|
```
|
402
413
|
|
403
|
-
|
414
|
+
<a id="markdown-for_gem_extension" name="for_gem_extension"></a>
|
415
|
+
#### for_gem_extension
|
416
|
+
|
417
|
+
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/):
|
418
|
+
|
419
|
+
* The gem should be called `net-http-niche_feature`. That is, hyphens for the extended part, a hyphen, and underscores for yours.
|
420
|
+
* The namespace should be `Net::HTTP::NicheFeature`.
|
421
|
+
* The entry point should be `lib/net/http/niche_feature.rb`.
|
422
|
+
* 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.
|
423
|
+
|
424
|
+
The top-level file mentioned in the last point is optional. In particular, from
|
425
|
+
|
426
|
+
```ruby
|
427
|
+
gem "net-http-niche_feature"
|
428
|
+
```
|
429
|
+
|
430
|
+
if the hyphenated file does not exist, Bundler notes the conventional hyphenated pattern and issues a `require` for `net/http/niche_feature`.
|
431
|
+
|
432
|
+
Gem extensions following the conventions above have a dedicated loader constructor: `Zeitwerk::Loader.for_gem_extension`.
|
433
|
+
|
434
|
+
The structure of the gem would be like this:
|
435
|
+
|
436
|
+
```ruby
|
437
|
+
# lib/net-http-niche_feature.rb (optional)
|
438
|
+
|
439
|
+
# For technical reasons, this cannot be require_relative.
|
440
|
+
require "net/http/niche_feature"
|
441
|
+
|
442
|
+
|
443
|
+
# lib/net/http/niche_feature.rb
|
444
|
+
|
445
|
+
require "net/http"
|
446
|
+
require "zeitwerk"
|
447
|
+
|
448
|
+
loader = Zeitwerk::Loader.for_gem_extension(Net::HTTP)
|
449
|
+
loader.setup
|
450
|
+
|
451
|
+
module Net::HTTP::NicheFeature
|
452
|
+
# Since the setup has been performed, at this point we are already able
|
453
|
+
# to reference project constants, in this case Net::HTTP::NicheFeature::MyMixin.
|
454
|
+
include MyMixin
|
455
|
+
end
|
456
|
+
|
457
|
+
|
458
|
+
# lib/net/http/niche_feature/version.rb
|
459
|
+
|
460
|
+
module Net::HTTP::NicheFeature
|
461
|
+
VERSION = "1.0.0"
|
462
|
+
end
|
463
|
+
```
|
464
|
+
|
465
|
+
`Zeitwerk::Loader.for_gem_extension` expects as argument the namespace being extended, which has to be a non-anonymous class or module object.
|
466
|
+
|
467
|
+
If it exists, `lib/net/http/niche_feature/version.rb` is expected to define `Net::HTTP::NicheFeature::VERSION`.
|
404
468
|
|
405
|
-
|
469
|
+
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.
|
470
|
+
|
471
|
+
`Zeitwerk::Loader.for_gem_extension` is idempotent when invoked from the same file, to support gems that want to reload (unlikely).
|
406
472
|
|
407
473
|
<a id="markdown-autoloading" name="autoloading"></a>
|
408
474
|
### Autoloading
|
@@ -438,10 +504,12 @@ loader.eager_load
|
|
438
504
|
|
439
505
|
That skips [ignored files and directories](#ignoring-parts-of-the-project).
|
440
506
|
|
441
|
-
In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](
|
507
|
+
In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](#synopsis).
|
442
508
|
|
443
509
|
Eager loading is synchronized and idempotent.
|
444
510
|
|
511
|
+
Attempting to eager load without previously calling `setup` raises `Zeitwerk::SetupRequired`.
|
512
|
+
|
445
513
|
<a id="markdown-eager-load-exclusions" name="eager-load-exclusions"></a>
|
446
514
|
#### Eager load exclusions
|
447
515
|
|
@@ -464,6 +532,81 @@ Which may be handy if the project eager loads in the test suite to [ensure proje
|
|
464
532
|
|
465
533
|
The `force` flag does not affect ignored files and directories, those are still ignored.
|
466
534
|
|
535
|
+
<a id="markdown-eager-load-directories" name="eager-load-directories"></a>
|
536
|
+
#### Eager load directories
|
537
|
+
|
538
|
+
The method `Zeitwerk::Loader#eager_load_dir` eager loads a given directory, recursively:
|
539
|
+
|
540
|
+
```ruby
|
541
|
+
loader.eager_load_dir("#{__dir__}/custom_web_app/routes")
|
542
|
+
```
|
543
|
+
|
544
|
+
This is useful when the loader is not eager loading the entire project, but you still need some subtree to be loaded for things to function properly.
|
545
|
+
|
546
|
+
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`.
|
547
|
+
|
548
|
+
[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](#shadowed-files) are not eager loaded.
|
549
|
+
|
550
|
+
`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.
|
551
|
+
|
552
|
+
The method checks if a regular eager load was already executed, in which case it returns fast.
|
553
|
+
|
554
|
+
Nested root directories which are descendants of the argument are skipped. Those subtrees are considered to be conceptually apart.
|
555
|
+
|
556
|
+
Attempting to eager load a directory without previously calling `setup` raises `Zeitwerk::SetupRequired`.
|
557
|
+
|
558
|
+
<a id="markdown-eager-load-namespaces" name="eager-load-namespaces"></a>
|
559
|
+
#### Eager load namespaces
|
560
|
+
|
561
|
+
The method `Zeitwerk::Loader#eager_load_namespace` eager loads a given namespace, recursively:
|
562
|
+
|
563
|
+
```ruby
|
564
|
+
loader.eager_load_namespace(MyApp::Routes)
|
565
|
+
```
|
566
|
+
|
567
|
+
This is useful when the loader is not eager loading the entire project, but you still need some namespace to be loaded for things to function properly.
|
568
|
+
|
569
|
+
The argument has to be a class or module object and the method raises `Zeitwerk::Error` otherwise.
|
570
|
+
|
571
|
+
If the namespace is spread over multiple directories in the receiver's source tree, they are all eager loaded. For example, if you have a structure like
|
572
|
+
|
573
|
+
```
|
574
|
+
root_dir1/my_app/routes
|
575
|
+
root_dir2/my_app/routes
|
576
|
+
root_dir3/my_app/routes
|
577
|
+
```
|
578
|
+
|
579
|
+
where `root_directory{1,2,3}` are root directories, eager loading `MyApp::Routes` will eager load the contents of the three corresponding directories.
|
580
|
+
|
581
|
+
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.
|
582
|
+
|
583
|
+
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.
|
584
|
+
|
585
|
+
[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](#shadowed-files) are not eager loaded.
|
586
|
+
|
587
|
+
`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.
|
588
|
+
|
589
|
+
The method checks if a regular eager load was already executed, in which case it returns fast.
|
590
|
+
|
591
|
+
If root directories are assigned to custom namespaces, the method behaves as you'd expect, according to the namespacing relationship between the custom namespace and the argument.
|
592
|
+
|
593
|
+
Attempting to eager load a namespace without previously calling `setup` raises `Zeitwerk::SetupRequired`.
|
594
|
+
|
595
|
+
<a id="markdown-eager-load-namespaces-shared-by-several-loaders" name="eager-load-namespaces-shared-by-several-loaders"></a>
|
596
|
+
#### Eager load namespaces shared by several loaders
|
597
|
+
|
598
|
+
The method `Zeitwerk::Loader.eager_load_namespace` broadcasts `eager_load_namespace` to all loaders.
|
599
|
+
|
600
|
+
```ruby
|
601
|
+
Zeitwerk::Loader.eager_load_namespace(MyFramework::Routes)
|
602
|
+
```
|
603
|
+
|
604
|
+
This may be handy, for example, if a framework supports plugins and a shared namespace needs to be eager loaded for the framework to function properly.
|
605
|
+
|
606
|
+
Please, note that loaders only eager load namespaces they manage, as documented above. Therefore, this method does not allow you to eager load namespaces not managed by Zeitwerk loaders.
|
607
|
+
|
608
|
+
This method does not require that all registered loaders have `setup` already invoked, since that is out of your control. If there's any in that state, it is simply skipped.
|
609
|
+
|
467
610
|
<a id="markdown-global-eager-load" name="global-eager-load"></a>
|
468
611
|
#### Global eager load
|
469
612
|
|
@@ -479,9 +622,31 @@ Note that thanks to idempotence `Zeitwerk::Loader.eager_load_all` won't eager lo
|
|
479
622
|
|
480
623
|
This method does not accept the `force` flag, since in general it wouldn't be a good idea to force eager loading in 3rd party code.
|
481
624
|
|
625
|
+
This method does not require that all registered loaders have `setup` already invoked, since that is out of your control. If there's any in that state, it is simply skipped.
|
626
|
+
|
627
|
+
<a id="markdown-loading-individual-files" name="loading-individual-files"></a>
|
628
|
+
### Loading individual files
|
629
|
+
|
630
|
+
The method `Zeitwerk::Loader#load_file` loads an individual Ruby file:
|
631
|
+
|
632
|
+
```ruby
|
633
|
+
loader.load_file("#{__dir__}/custom_web_app/routes.rb")
|
634
|
+
```
|
635
|
+
|
636
|
+
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.
|
637
|
+
|
638
|
+
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.
|
639
|
+
|
640
|
+
`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.
|
641
|
+
|
642
|
+
If you want to eager load a directory, `Zeitwerk::Loader#eager_load_dir` is more efficient than invoking `Zeitwerk::Loader#load_file` on its files.
|
643
|
+
|
482
644
|
<a id="markdown-reloading" name="reloading"></a>
|
483
645
|
### Reloading
|
484
646
|
|
647
|
+
<a id="markdown-configuration-and-usage" name="configuration-and-usage"></a>
|
648
|
+
#### Configuration and usage
|
649
|
+
|
485
650
|
Zeitwerk is able to reload code, but you need to enable this feature:
|
486
651
|
|
487
652
|
```ruby
|
@@ -495,7 +660,7 @@ loader.reload
|
|
495
660
|
|
496
661
|
There is no way to undo this, either you want to reload or you don't.
|
497
662
|
|
498
|
-
Enabling reloading after setup raises `Zeitwerk::Error`. Attempting to reload without having it enabled raises `Zeitwerk::ReloadingDisabledError`.
|
663
|
+
Enabling reloading after setup raises `Zeitwerk::Error`. Attempting to reload without having it enabled raises `Zeitwerk::ReloadingDisabledError`. Attempting to reload without previously calling `setup` raises `Zeitwerk::SetupRequired`.
|
499
664
|
|
500
665
|
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.
|
501
666
|
|
@@ -503,12 +668,34 @@ Reloading removes the currently loaded classes and modules and resets the loader
|
|
503
668
|
|
504
669
|
It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
|
505
670
|
|
506
|
-
|
671
|
+
<a id="markdown-thread-safety" name="thread-safety"></a>
|
672
|
+
#### Thread-safety
|
673
|
+
|
674
|
+
In order to reload safely, no other thread can be autoloading or reloading concurrently. Client code is responsible for this coordination.
|
675
|
+
|
676
|
+
For example, a web framework that serves each request in its own thread and has reloading enabled could create a read-write lock on boot like this:
|
677
|
+
|
678
|
+
```ruby
|
679
|
+
require "concurrent/atomic/read_write_lock"
|
680
|
+
|
681
|
+
MyFramework::RELOAD_RW_LOCK = Concurrent::ReadWriteLock.new
|
682
|
+
```
|
683
|
+
|
684
|
+
You acquire the lock for reading for serving each individual request:
|
685
|
+
|
686
|
+
```ruby
|
687
|
+
MyFramework::RELOAD_RW_LOCK.with_read_lock do
|
688
|
+
serve(request)
|
689
|
+
end
|
690
|
+
```
|
507
691
|
|
508
|
-
|
509
|
-
* You should not autoload while another thread is reloading.
|
692
|
+
Then, when a reload is triggered, just acquire the lock for writing in order to execute the method call safely:
|
510
693
|
|
511
|
-
|
694
|
+
```ruby
|
695
|
+
MyFramework::RELOAD_RW_LOCK.with_write_lock do
|
696
|
+
loader.reload
|
697
|
+
end
|
698
|
+
```
|
512
699
|
|
513
700
|
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 reloadable controller class objects or instances in internal structures, on reload it has to refresh them somehow, possibly reevaluating routes.
|
514
701
|
|
@@ -823,6 +1010,8 @@ However, sometimes it might still be convenient to tell Zeitwerk to completely i
|
|
823
1010
|
|
824
1011
|
You can ignore file names, directory names, and glob patterns. Glob patterns are expanded when they are added and again on each reload.
|
825
1012
|
|
1013
|
+
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.
|
1014
|
+
|
826
1015
|
Let's see some use cases.
|
827
1016
|
|
828
1017
|
<a id="markdown-use-case-files-that-do-not-follow-the-conventions" name="use-case-files-that-do-not-follow-the-conventions"></a>
|
@@ -905,10 +1094,39 @@ loader.ignore(tests)
|
|
905
1094
|
loader.setup
|
906
1095
|
```
|
907
1096
|
|
1097
|
+
<a id="markdown-shadowed-files" name="shadowed-files"></a>
|
1098
|
+
### Shadowed files
|
1099
|
+
|
1100
|
+
In Ruby, if you have several files called `foo.rb` in different directories of `$LOAD_PATH` and execute
|
1101
|
+
|
1102
|
+
```ruby
|
1103
|
+
require "foo"
|
1104
|
+
```
|
1105
|
+
|
1106
|
+
the first one found gets loaded, and the rest are ignored.
|
1107
|
+
|
1108
|
+
Zeitwerk behaves in a similar way. If `foo.rb` is present in several root directories (at the same namespace level), the constant `Foo` is autoloaded from the first one, and the rest of the files are not evaluated. If logging is enabled, you'll see something like
|
1109
|
+
|
1110
|
+
```
|
1111
|
+
file #{file} is ignored because #{previous_occurrence} has precedence
|
1112
|
+
```
|
1113
|
+
|
1114
|
+
(This message is not public interface and may change, you cannot rely on that exact wording.)
|
1115
|
+
|
1116
|
+
Even if there's only one `foo.rb`, if the constant `Foo` is already defined when Zeitwerk finds `foo.rb`, then the file is ignored too. This could happen if `Foo` was defined by a dependency, for example. If logging is enabled, you'll see something like
|
1117
|
+
|
1118
|
+
```
|
1119
|
+
file #{file} is ignored because #{constant_path} is already defined
|
1120
|
+
```
|
1121
|
+
|
1122
|
+
(This message is not public interface and may change, you cannot rely on that exact wording.)
|
1123
|
+
|
1124
|
+
Shadowing only applies to Ruby files, namespace definition can be spread over multiple directories. And you can also reopen third-party namespaces if done [orderly](#reopening-third-party-namespaces).
|
1125
|
+
|
908
1126
|
<a id="markdown-edge-cases" name="edge-cases"></a>
|
909
1127
|
### Edge cases
|
910
1128
|
|
911
|
-
|
1129
|
+
[Explicit namespaces](#explicit-namespaces) like `Trip` here:
|
912
1130
|
|
913
1131
|
```ruby
|
914
1132
|
# trip.rb
|
@@ -922,14 +1140,15 @@ module Trip::Geolocation
|
|
922
1140
|
end
|
923
1141
|
```
|
924
1142
|
|
925
|
-
|
1143
|
+
have to be defined with the `class`/`module` keywords, as in the example above.
|
926
1144
|
|
927
1145
|
For technical reasons, raw constant assignment is not supported:
|
928
1146
|
|
929
1147
|
```ruby
|
930
1148
|
# trip.rb
|
931
|
-
Trip = Class
|
932
|
-
Trip = Struct.new { ... }
|
1149
|
+
Trip = Class { ...} # NOT SUPPORTED
|
1150
|
+
Trip = Struct.new { ... } # NOT SUPPORTED
|
1151
|
+
Trip = Data.define { ... } # NOT SUPPORTED
|
933
1152
|
```
|
934
1153
|
|
935
1154
|
This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
|
@@ -984,7 +1203,7 @@ require "active_job"
|
|
984
1203
|
require "active_job/queue_adapters"
|
985
1204
|
|
986
1205
|
require "zeitwerk"
|
987
|
-
# By
|
1206
|
+
# By passing the flag, we acknowledge the extra directory lib/active_job
|
988
1207
|
# has to be managed by the loader and no warning has to be issued for it.
|
989
1208
|
loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
|
990
1209
|
loader.setup
|
@@ -1012,6 +1231,8 @@ loader.push_dir(Pathname.new("/bar"), namespace: Bar)
|
|
1012
1231
|
loader.dirs(namespaces: true) # => { "/foo" => Object, "/bar" => Bar }
|
1013
1232
|
```
|
1014
1233
|
|
1234
|
+
By default, ignored root directories are filtered out. If you want them included, please pass `ignored: true`.
|
1235
|
+
|
1015
1236
|
These collections are read-only. Please add to them with `Zeitwerk::Loader#push_dir`.
|
1016
1237
|
|
1017
1238
|
<a id="markdown-encodings" name="encodings"></a>
|
@@ -1044,22 +1265,9 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
|
|
1044
1265
|
<a id="markdown-debuggers" name="debuggers"></a>
|
1045
1266
|
### Debuggers
|
1046
1267
|
|
1047
|
-
|
1048
|
-
#### debug.rb
|
1049
|
-
|
1050
|
-
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.
|
1051
|
-
|
1052
|
-
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).
|
1053
|
-
|
1054
|
-
<a id="markdown-byebug" name="byebug"></a>
|
1055
|
-
#### Byebug
|
1056
|
-
|
1057
|
-
Zeitwerk and [Byebug](https://github.com/deivid-rodriguez/byebug) have a similar edge incompatibility.
|
1058
|
-
|
1059
|
-
<a id="markdown-break" name="break"></a>
|
1060
|
-
#### Break
|
1268
|
+
Zeitwerk works fine with [debug.rb](https://github.com/ruby/debug) and [Break](https://github.com/gsamokovarov/break).
|
1061
1269
|
|
1062
|
-
|
1270
|
+
[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).
|
1063
1271
|
|
1064
1272
|
<a id="markdown-pronunciation" name="pronunciation"></a>
|
1065
1273
|
## Pronunciation
|
data/lib/zeitwerk/error.rb
CHANGED
@@ -11,28 +11,28 @@ module Zeitwerk
|
|
11
11
|
module ExplicitNamespace # :nodoc: all
|
12
12
|
class << self
|
13
13
|
include RealModName
|
14
|
+
extend Internal
|
14
15
|
|
15
16
|
# Maps constant paths that correspond to explicit namespaces according to
|
16
17
|
# the file system, to the loader responsible for them.
|
17
18
|
#
|
18
|
-
# @private
|
19
19
|
# @sig Hash[String, Zeitwerk::Loader]
|
20
20
|
attr_reader :cpaths
|
21
|
+
private :cpaths
|
21
22
|
|
22
|
-
# @private
|
23
23
|
# @sig Mutex
|
24
24
|
attr_reader :mutex
|
25
|
+
private :mutex
|
25
26
|
|
26
|
-
# @private
|
27
27
|
# @sig TracePoint
|
28
28
|
attr_reader :tracer
|
29
|
+
private :tracer
|
29
30
|
|
30
31
|
# Asserts `cpath` corresponds to an explicit namespace for which `loader`
|
31
32
|
# is responsible.
|
32
33
|
#
|
33
|
-
# @private
|
34
34
|
# @sig (String, Zeitwerk::Loader) -> void
|
35
|
-
def register(cpath, loader)
|
35
|
+
internal def register(cpath, loader)
|
36
36
|
mutex.synchronize do
|
37
37
|
cpaths[cpath] = loader
|
38
38
|
# We check enabled? because, looking at the C source code, enabling an
|
@@ -41,24 +41,28 @@ module Zeitwerk
|
|
41
41
|
end
|
42
42
|
end
|
43
43
|
|
44
|
-
# @private
|
45
44
|
# @sig (Zeitwerk::Loader) -> void
|
46
|
-
def unregister_loader(loader)
|
45
|
+
internal def unregister_loader(loader)
|
47
46
|
cpaths.delete_if { |_cpath, l| l == loader }
|
48
47
|
disable_tracer_if_unneeded
|
49
48
|
end
|
50
49
|
|
51
|
-
|
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
|
52
56
|
|
53
57
|
# @sig () -> void
|
54
|
-
def disable_tracer_if_unneeded
|
58
|
+
private def disable_tracer_if_unneeded
|
55
59
|
mutex.synchronize do
|
56
60
|
tracer.disable if cpaths.empty?
|
57
61
|
end
|
58
62
|
end
|
59
63
|
|
60
64
|
# @sig (TracePoint) -> void
|
61
|
-
def tracepoint_class_callback(event)
|
65
|
+
private def tracepoint_class_callback(event)
|
62
66
|
# If the class is a singleton class, we won't do anything with it so we
|
63
67
|
# can bail out immediately. This is several orders of magnitude faster
|
64
68
|
# than accessing its name.
|
@@ -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,12 +42,12 @@ 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
|
|
45
49
|
basename_without_ext = basename.delete_suffix(".rb")
|
46
|
-
cname = inflector.camelize(basename_without_ext, abspath)
|
50
|
+
cname = inflector.camelize(basename_without_ext, abspath).to_sym
|
47
51
|
ftype = dir?(abspath) ? "directory" : "file"
|
48
52
|
|
49
53
|
warn(<<~EOS)
|
data/lib/zeitwerk/kernel.rb
CHANGED
@@ -19,6 +19,9 @@ module Kernel
|
|
19
19
|
# included in Object, and changes in ancestors don't get propagated into
|
20
20
|
# already existing ancestor chains on Ruby < 3.0.
|
21
21
|
alias_method :zeitwerk_original_require, :require
|
22
|
+
class << self
|
23
|
+
alias_method :zeitwerk_original_require, :require
|
24
|
+
end
|
22
25
|
|
23
26
|
# @sig (String) -> true | false
|
24
27
|
def require(path)
|
@@ -11,18 +11,18 @@ module Zeitwerk::Loader::Callbacks
|
|
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
|
+
crem(*cref)
|
24
|
+
to_unload[cpath] = [file, cref] if reloading_enabled?
|
25
|
+
raise Zeitwerk::NameError.new(msg, cref.last)
|
26
26
|
end
|
27
27
|
end
|
28
28
|
|
@@ -42,7 +42,7 @@ module Zeitwerk::Loader::Callbacks
|
|
42
42
|
# Without the mutex and subsequent delete call, t2 would reset the module.
|
43
43
|
# That not only would reassign the constant (undesirable per se) but, worse,
|
44
44
|
# the module object created by t2 wouldn't have any of the autoloads for its
|
45
|
-
# children, since t1 would have correctly deleted its
|
45
|
+
# children, since t1 would have correctly deleted its namespace_dirs entry.
|
46
46
|
mutex2.synchronize do
|
47
47
|
if cref = autoloads.delete(dir)
|
48
48
|
autovivified_module = cref[0].const_set(cref[1], Module.new)
|
@@ -71,9 +71,9 @@ module Zeitwerk::Loader::Callbacks
|
|
71
71
|
# @private
|
72
72
|
# @sig (Module) -> void
|
73
73
|
def on_namespace_loaded(namespace)
|
74
|
-
if
|
75
|
-
|
76
|
-
set_autoloads_in_dir(
|
74
|
+
if dirs = namespace_dirs.delete(real_mod_name(namespace))
|
75
|
+
dirs.each do |dir|
|
76
|
+
set_autoloads_in_dir(dir, namespace)
|
77
77
|
end
|
78
78
|
end
|
79
79
|
end
|