im 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a146ab43403d85ad1ba24849e235c4c3f9c6f1f344c350f93f7815163ad0ec17
-  data.tar.gz: 88f76dc7b193e2566b6603f4828ba07cade314dc08853b4941bce01df442954f
+  metadata.gz: e1708fffea9fb79c809dbfa34669e5471556e4d969ae8d95e689cfccc5c6f3e4
+  data.tar.gz: bce10f72bc879a53bda624ced7534bd0c74fc5666c6ff8545ea9371521edc8b0
 SHA512:
-  metadata.gz: 53b9300337db2c3c716b9527f16ad78b29e65629da09306e22f48312907ef18d9e66f34e5b7a627dd7cf5daee00fd79953b222984937e43c49dd9f20934d6af2
-  data.tar.gz: 706be184a19a39e665c8324c69b98bcd847f908c206382338b933470e803a7503c3b376227c6be6913ebe8630c83f4c865d9f943a76bcaaa224931139b8e09f9
+  metadata.gz: a112f1ee72916d690c0227a94a16f87d283b93a059f1e01d8681649ac9405ce46add46650234b2e337ace8b8571c64ba4f722f256099263eea04cfaafb3f02e1
+  data.tar.gz: b7a03df97bcbac97f09c8637f9c8b82fbaaddcd58640aecc2406e821910fe5cb2ed4200ddc2d6490bc0d0d2d42e6a65173bb7a52ba78c7ed2c05126a0edc669b

data/README.md

@@ -1,7 +1,9 @@
 # Im
 
+[![Gem Version](https://badge.fury.io/rb/im.svg)][gem]
 [![Build Status](https://github.com/shioyama/im/actions/workflows/ci.yml/badge.svg)][actions]
 
+[gem]: https://rubygems.org/gems/im
 [actions]: https://github.com/shioyama/im/actions
 
 <!-- TOC -->
@@ -28,13 +30,12 @@ any way touching the global namespace.
 To do this, Im leverages code autoloading, Zeitwerk conventions around file
 structure and naming, and two features added in Ruby 3.2: `Kernel#load`
 with a module argument[^1] and `Module#const_added`[^2]. Since these Ruby
-features are essential to its design, it cannot be used with earlier versions
+features are essential to its design, Im is not usable with earlier versions
 of Ruby.
 
-Im started its life as a fork of Zeitwerk and has a very similar interface. The
-gem strives to follow the Zeitwerk pattern as much as possible. Im and Zeitwerk
-can be used alongside each other provided there is no overlap between file
-paths managed by each gem.
+Im started its life as a fork of Zeitwerk and has a very similar interface. Im
+and Zeitwerk can be used alongside each other provided there is no overlap
+between file paths managed by each gem.
 
 Im is in active development and should be considered experimental until the
 eventual release of version 1.0. Versions 0.1.6 and earlier of the gem were
@@ -43,12 +44,12 @@ part of a different experiment and are unrelated to the current gem.
 <a id="markdown-synopsis" name="synopsis"></a>
 ## Synopsis
 
-Im follows an interface that is in most respects identical to Zeitwerk.
-The central difference is that whereas Zeitwerk loads constants into the global
+Im's public interface is in most respects identical to that of Zeitwerk. The
+central difference is that whereas Zeitwerk loads constants into the global
 namespace (rooted in `Object`), Im loads them into anonymous namespaces rooted
-on the loader itself. Loaders in Im are a subclass of the `Module` class, and
-thus each one can define its own namespace. Since there can be arbitrarily many
-loaders, there can also be arbitrarily many autoloaded namespaces.
+on the loader itself. `Im::Loader` is a subclass of `Module`, and thus each
+loader instance can define its own namespace. Since there can be arbitrarily
+many loaders, there can also be arbitrarily many autoloaded namespaces.
 
 Im's gem interface looks like this:
 
@@ -66,7 +67,7 @@ end
 loader.eager_load # optionally
 ```
 
-The generic interface is likewise identical to Zeitwerk's:
+The generic interface is identical to Zeitwerk's:
 
 ```ruby
 loader = Zeitwerk::Loader.new
@@ -84,7 +85,7 @@ Object.const_defined?(:MyGem)
 ```
 
 In order to prevent leakage, the gem's entrypoint, in this case
-`lib/my_gem.rb`), must not define anything at toplevel, hence the use of
+`lib/my_gem.rb`, must not define anything at toplevel, hence the use of
 `module loader::MyGem`.
 
 Once the entrypoint has been required, all constants defined within the gem's
@@ -107,7 +108,7 @@ foo = loader::MyGem::Foo
 # loads `Foo` from lib/my_gem/foo.rb
 
 foo.new.hello_world
-# "Hello World!"
+#=> "Hello World!"
 ```
 
 Constants under the loader can be given permanent names that are different from
@@ -116,16 +117,12 @@ the one defined in the gem itself:
 ```ruby
 Bar = loader::MyGem::Foo
 Bar.new.hello_world
-# "Hello World!"
+#=> "Hello World!"
 ```
 
-Since Im uses loaders as its namespace roots, it is important that consumers of
-gems have a way to fetch the loader for a given file path.
-
-The loader variable can go out of scope. Like Zeitwerk, Im keeps a registry
-with all of them, and so the object won't be garbage collected. For
-convenience, Im also provides a method, `Im#import`, to fetch a loader for
-a given file path:
+Like Zeitwerk, Im keeps a registry of all loaders, so the loader objects won't
+be garbage collected. For convenience, Im also provides a method, `Im#import`,
+to fetch a loader for a given file path:
 
 ```ruby
 require "im"
@@ -133,7 +130,7 @@ require "my_gem"
 
 extend Im
 my_gem = import "my_gem"
-#=> loader::MyGem is autoloadable
+#=> my_gem::MyGem is autoloadable
 ```
 
 Reloading works like Zeitwerk:
@@ -209,15 +206,15 @@ anywhere in the global namespace.
 ### Relative and absolute cpaths
 
 Im uses two types of constant paths: relative and absolute, wherever possible
-defaulting to relative ones. A relative cpath is a constant name relative to
+defaulting to relative ones. A _relative cpath_ is a constant name relative to
 the loader in which it was originally defined, regardless of any other names it
-was assigned. Whereas Zeitwerk uses absolute cpaths, Im uses relative cpaths for
-all external loader APIs (see usage for examples).
+was later assigned. Whereas Zeitwerk uses absolute cpaths, Im uses relative
+cpaths for all external loader APIs (see usage for examples).
 
 To understand these concepts, it is important first to distinguish between two
 types of names in Ruby: _temporary names_ and _permanent names_.
 
-A temporary name is a constant name on an anonymous-rooted namespace, for
+A _temporary name_ is a constant name on an anonymous-rooted namespace, for
 example a loader:
 
 ```ruby
@@ -228,7 +225,7 @@ my_gem::Foo.name
 ```
 
 Here, the string `"#<Im::Loader ...>::Foo"` is called a temporary name. We can
-give this module a permanent name by assigning it to a toplevel constant:
+give this module a _permanent name_ by assigning it to a toplevel constant:
 
 ```ruby
 Bar = my_gem::Foo
@@ -244,12 +241,12 @@ keys in Im's internal registries to index constants and their autoloads, which
 is critical for successful autoloading.
 
 To get around this issue, Im tracks all module names and uses relative naming
-inside loader code. You can get the name of a module relative to the loader
-that loaded it with `Im::Loader#relative_cpath`:
+inside loader code. Internally, Im has a method, `relative_cpath`, which can
+generate any module name under a module in the loader namespace:
 
 ```ruby
-my_gem.relative_cpath(my_gem::Foo)
-#=> "Foo"
+my_gem.send(:relative_cpath, loader::Foo, :Baz)
+#=> "Foo::Baz"
 ```
 
 Using relative cpaths frees Im from depending on `Module#name` for

data/lib/im/loader.rb

@@ -390,7 +390,7 @@ module Im
     def autoload_subdir(parent, cname, subdir)
       if autoload_path = autoload_path_set_by_me_for?(parent, cname)
         absolute_cpath = cpath(parent, cname)
-        relative_cpath = relative_cpath(parent, cname)
+        relative_cpath = relative_cpath(absolute_cpath, cname)
         register_explicit_namespace(cpath, relative_cpath) if ruby?(autoload_path)
 
         # We do not need to issue another autoload, the existing one is enough

data/lib/im/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Im
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: im
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Chris Salzberg