zeitwerk 2.1.9 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e58e19aad2055cd64f4ac3018cd6425e8f29f83d765b2410a28bef02f3fee381
-  data.tar.gz: e23bb3b21e15667fb8be922b0ced718ba135a5610cc0c6965304701ff580e404
+  metadata.gz: 2af50b4d74832ccd3c08e3445c09a941ed56758c57acd20e8d88436f79e16ea2
+  data.tar.gz: 23f693ca2b9fc44870c26991cd91c587031825e9d29c90dd5285f2c7a3731f6a
 SHA512:
-  metadata.gz: 3e6e6271f1f9cce47fb81b50d495aeb1159819ee68b0675752bb329494d77524ac624cb067d96f638a1580c2ad342832e3eab9f8cf8ad6b296d83524ef590f03
-  data.tar.gz: 7b4c4bae3b1fdf0214eeb7881ab855ad1babd5a28d1ab640105405b073bc1fcc54b08df1d6d0c416584363804268d7428b082a9822d8a0870f59224462ded513
+  metadata.gz: 1d47e1a735c5314ec56f9c16d66695222209109dddb7da3a663969b852295eed82d8eee56fc48a48cb6b0604e508940f474533e98c7d824175c344420a64baec
+  data.tar.gz: be275743889771c745fc90d300a4cbd01911b5b4547c41ea1df6429af1357b9328fb69293a03a282677295f27528220f180f1ca943f43b5567677b856baa3e06

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2019–ω Xavier Noria
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -3,7 +3,7 @@
 
 
 [![Gem Version](https://img.shields.io/gem/v/zeitwerk.svg?style=for-the-badge)](https://rubygems.org/gems/zeitwerk)
-[![Build Status](https://img.shields.io/travis/com/fxn/zeitwerk.svg?style=for-the-badge&branch=master)](https://travis-ci.com/fxn/zeitwerk)
+[![Build Status](https://img.shields.io/travis/com/fxn/zeitwerk/master?style=for-the-badge)](https://travis-ci.com/fxn/zeitwerk)
 
 <!-- TOC -->
 
@@ -29,6 +29,7 @@
         - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
     - [Edge cases](#edge-cases)
     - [Rules of thumb](#rules-of-thumb)
+    - [Autoloading, explicit namespaces, and debuggers](#autoloading-explicit-namespaces-and-debuggers)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
 - [Motivation](#motivation)
@@ -199,6 +200,22 @@ loader.setup
 
 The loader returned by `Zeitwerk::Loader.for_gem` has the directory of the caller pushed, normally that is the absolute path of `lib`. In that sense, `for_gem` can be used also by projects with a gem structure, even if they are not technically gems. That is, you don't need a gemspec or anything.
 
+If the main module of a library references project constants at the top-level, Zeitwerk has to be ready to load them. Their definitions, in turn, may reference other project constants. And this is recursive. Therefore, it is important that the `setup` call happens above the main module definition:
+
+```ruby
+# lib/my_gem.rb (main file)
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module MyGem
+  # Since the setup has been performed, at this point we are already able
+  # to reference project constants, in this case MyGem::MyLogger.
+  include MyLogger
+end
+```
+
 Zeitwerk works internally only with absolute paths to avoid costly file searches in `$LOAD_PATH`. Indeed, the root directories do not even need to belong to `$LOAD_PATH`, everything just works by design if they don't.
 
 <a id="markdown-reloading" name="reloading"></a>
@@ -221,7 +238,7 @@ Enabling reloading after setup raises `Zeitwerk::Error`. Similarly, calling `rel
 
 Generally speaking, reloading is useful while developing running services like web applications. Gems that implement regular libraries, so to speak, or services running in testing or production environments, won't normally have a use case for reloading. If reloading is not enabled, Zeitwerk is able to use less memory.
 
-Reloading removes the currently loaded classes and modules, resets the loader so that it will pick whatever is in the file system now, and runs preloads if there are any.
+Reloading removes the currently loaded classes and modules and resets the loader so that it will pick whatever is in the file system now.
 
 It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
 
@@ -247,6 +264,8 @@ loader.setup
 loader.eager_load # won't eager load the database adapters
 ```
 
+In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](https://github.com/fxn/zeitwerk#synopsis).
+
 Eager loading is synchronized and idempotent.
 
 If you want to eager load yourself and all dependencies using Zeitwerk, you can broadcast the `eager_load` call to all instances:
@@ -275,14 +294,34 @@ users_controller -> UsersController
 html_parser      -> HtmlParser
 ```
 
+The camelize logic can be overridden easily for individual basenames:
+
+```ruby
+loader.inflector.inflect(
+  "html_parser"   => "HTMLParser",
+  "mysql_adapter" => "MySQLAdapter"
+)
+```
+
+The `inflect` method can be invoked several times if you prefer this other style:
+
+```ruby
+loader.inflector.inflect "html_parser" => "HTMLParser"
+loader.inflector.inflect "mysql_adapter" => "MySQLAdapter"
+```
+
+Overrides need to be configured before calling `setup`.
+
 There are no inflection rules or global configuration that can affect this inflector. It is deterministic.
 
-This is the default inflector.
+Loaders instantiated with `Zeitwerk::Loader.new` have an inflector of this type, independent of each other.
 
 <a id="markdown-zeitwerkgeminflector" name="zeitwerkgeminflector"></a>
 #### Zeitwerk::GemInflector
 
-The loader instantiated behind the scenes by `Zeitwerk::Loader.for_gem` gets assigned by default an inflector that is like the basic one, except it expects `lib/my_gem/version.rb` to define `MyGem::VERSION`.
+This inflector is like the basic one, except it expects `lib/my_gem/version.rb` to define `MyGem::VERSION`.
+
+Loaders instantiated with `Zeitwerk::Loader.for_gem` have an inflector of this type, independent of each other.
 
 <a id="markdown-custom-inflector" name="custom-inflector"></a>
 #### Custom inflector
@@ -293,12 +332,9 @@ The inflectors that ship with Zeitwerk are deterministic and simple. But you can
 # frozen_string_literal: true
 
 class MyInflector < Zeitwerk::Inflector
-  def camelize(basename, _abspath)
-    case basename
-    when "api"
-      "API"
-    when "mysql_adapter"
-      "MySQLAdapter"
+  def camelize(basename, abspath)
+    if basename =~ /\Ahtml_(.*)/
+      "HTML" + super($1, abspath)
     else
       super
     end
@@ -318,6 +354,49 @@ loader.inflector = MyInflector.new
 
 This needs to be done before calling `setup`.
 
+If a custom inflector definition in a gem takes too much space in the main file, you can extract it. For example, this is a simple pattern:
+
+```ruby
+# lib/my_gem/inflector.rb
+module MyGem
+  class Inflector < Zeitwerk::GemInflector
+    ...
+  end
+end
+
+# lib/my_gem.rb
+require "zeitwerk"
+require_relative "my_gem/inflector"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector = MyGem::Inflector.new(__FILE__)
+loader.setup
+
+module MyGem
+  # ...
+end
+```
+
+Since `MyGem` is referenced before the namespace is defined in the main file, it is important to use this style:
+
+```ruby
+# Correct, effectively defines MyGem.
+module MyGem
+  class Inflector < Zeitwerk::GemInflector
+    # ...
+  end
+end
+```
+
+instead of:
+
+```ruby
+# Raises uninitialized constant MyGem (NameError).
+class MyGem::Inflector < Zeitwerk::GemInflector
+  # ...
+end
+```
+
 <a id="markdown-logging" name="logging"></a>
 ### Logging
 
@@ -501,6 +580,15 @@ This only affects explicit namespaces, those idioms work well for any other ordi
 
 6. In a given process, ideally, there should be at most one loader with reloading enabled. Technically, you can have more, but it may get tricky if one refers to constants managed by the other one. Do that only if you know what you are doing.
 
+<a id="markdown-autoloading-explicit-namespaces-and-debuggers" name="autoloading-explicit-namespaces-and-debuggers"></a>
+### Autoloading, explicit namespaces, and debuggers
+
+As of this writing, Zeitwerk is unable to autoload classes or modules that belong to [explicit namespaces](#explicit-namespaces) inside debugger sessions. You'll get a `NameError`.
+
+The root cause is that debuggers set trace points, and Zeitwerk does too to support explicit namespaces. A debugger session happens inside a trace point handler, and Ruby does not invoke other handlers from within a running handler. Therefore, the code that manages explicit namespaces in Zeitwerk does not get called by the interpreter. See [this issue](https://github.com/deivid-rodriguez/byebug/issues/564#issuecomment-499413606) for further details.
+
+As a workaround, you can eager load. Zeitwerk tries hard to succeed or fail consistently both autoloading and eager loading, so switching to eager loading should not introduce any interference in your debugging logic, generally speaking.
+
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation
 

data/lib/zeitwerk/error.rb

@@ -4,4 +4,7 @@ module Zeitwerk
 
   class ReloadingDisabledError < Error
   end
+
+  class NameError < ::NameError
+  end
 end

data/lib/zeitwerk/gem_inflector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  class GemInflector < Inflector # :nodoc:
+  class GemInflector < Inflector
     # @param root_file [String]
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
@@ -13,7 +13,7 @@ module Zeitwerk
     # @param abspath [String]
     # @return [String]
     def camelize(basename, abspath)
-      (basename == "version" && abspath == @version_file) ? "VERSION" : super
+      abspath == @version_file ? "VERSION" : super
     end
   end
 end

data/lib/zeitwerk/inflector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  class Inflector # :nodoc:
+  class Inflector
     # Very basic snake case -> camel case conversion.
     #
     #   inflector = Zeitwerk::Inflector.new
@@ -9,11 +9,41 @@ module Zeitwerk
     #   inflector.camelize("users_controller", ...) # => "UsersController"
     #   inflector.camelize("api", ...)              # => "Api"
     #
+    # Takes into account hard-coded mappings configured with `inflect`.
+    #
     # @param basename [String]
     # @param _abspath [String]
     # @return [String]
     def camelize(basename, _abspath)
-      basename.split('_').map!(&:capitalize).join
+      overrides[basename] || basename.split('_').map!(&:capitalize).join
+    end
+
+    # Configures hard-coded inflections:
+    #
+    #   inflector = Zeitwerk::Inflector.new
+    #   inflector.inflect(
+    #     "html_parser"   => "HTMLParser",
+    #     "mysql_adapter" => "MySQLAdapter"
+    #   )
+    #
+    #   inflector.camelize("html_parser", abspath)      # => "HTMLParser"
+    #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
+    #   inflector.camelize("users_controller", abspath) # => "PostsController"
+    #
+    # @param inflections [{String => String}]
+    # @return [void]
+    def inflect(inflections)
+      overrides.merge!(inflections)
+    end
+
+    private
+
+    # Hard-coded basename to constant name user maps that override the default
+    # inflection logic.
+    #
+    # @return [{String => String}]
+    def overrides
+      @overrides ||= {}
     end
   end
 end

data/lib/zeitwerk/loader.rb

@@ -474,21 +474,38 @@ module Zeitwerk
     # @return [void]
     def set_autoloads_in_dir(dir, parent)
       ls(dir) do |basename, abspath|
-        if ruby?(basename)
-          basename.slice!(-3, 3)
-          cname = inflector.camelize(basename, abspath).to_sym
-          autoload_file(parent, cname, abspath)
-        elsif dir?(abspath)
-          # In a Rails application, `app/models/concerns` is a subdirectory of
-          # `app/models`, but both of them are root directories.
-          #
-          # To resolve the ambiguity file name -> constant path this introduces,
-          # the `app/models/concerns` directory is totally ignored as a namespace,
-          # it counts only as root. The guard checks that.
-          unless root_dirs.key?(abspath)
+        begin
+          if ruby?(basename)
+            basename.slice!(-3, 3)
             cname = inflector.camelize(basename, abspath).to_sym
-            autoload_subdir(parent, cname, abspath)
+            autoload_file(parent, cname, abspath)
+          elsif dir?(abspath)
+            # In a Rails application, `app/models/concerns` is a subdirectory of
+            # `app/models`, but both of them are root directories.
+            #
+            # To resolve the ambiguity file name -> constant path this introduces,
+            # the `app/models/concerns` directory is totally ignored as a namespace,
+            # it counts only as root. The guard checks that.
+            unless root_dirs.key?(abspath)
+              cname = inflector.camelize(basename, abspath).to_sym
+              autoload_subdir(parent, cname, abspath)
+            end
           end
+        rescue ::NameError => error
+          path_type = ruby?(abspath) ? "file" : "directory"
+
+          raise NameError, <<~MESSAGE
+            #{error.message} inferred by #{inflector.class} from #{path_type}
+
+              #{abspath}
+
+            Possible ways to address this:
+
+              * Tell Zeitwerk to ignore this particular #{path_type}.
+              * Tell Zeitwerk to ignore one of its parent directories.
+              * Rename the #{path_type} to comply with the naming conventions.
+              * Modify the inflector to handle this case.
+          MESSAGE
         end
       end
     end

data/lib/zeitwerk/real_mod_name.rb

@@ -8,7 +8,7 @@ module Zeitwerk::RealModName
   # The name method can be overridden, hence the indirection in this method.
   #
   # @param mod [Class, Module]
-  # @return [String]
+  # @return [String, nil]
   def real_mod_name(mod)
     UNBOUND_METHOD_MODULE_NAME.bind(mod).call
   end

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.1.9
+  version: 2.2.0
 platform: ruby
 authors:
 - Xavier Noria
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-16 00:00:00.000000000 Z
+date: 2019-10-09 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -20,6 +20,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- MIT-LICENSE
 - README.md
 - lib/zeitwerk.rb
 - lib/zeitwerk/error.rb