main_like_module 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77dd7a196964c1966a43660852408ba60eee5a6cea176b286ff822ad602acbf5
-  data.tar.gz: 1eb7d996917ce87927a4064806efc183a00fb0e5062b1e5708dd7d8bc0577652
+  metadata.gz: 1b20df879329c7be3e7e04d3eac2206590db083cd1003c227dd4bded56c29fe8
+  data.tar.gz: 63897091aa9d8e8f9d7860529e1eeb4e42594f70ca3db5208298dbd322b455cd
 SHA512:
-  metadata.gz: 6f1b021260ba408ab94d9dd0f12f4e103313daf32286554883bda7f5ab0d6783cd1b4aaf900216bf0d753317caeaae244eff911016f821f67ba3b789c7330d82
-  data.tar.gz: 753e1fd13c10d9f5509a1ce976a73c84911d29f713458b13f9b7a64af74bf383cd9e70cef701f625834995c9982a90b02ac615420e8e9644533fc12462b20ca7
+  metadata.gz: 46e8a794dd5815f037f91159a62bb7d8a3a9f4ff68569831a416bc1dbbb54ed03f5547d16765a898acc30f4a984edc75f86c3858cc164cc903db841b2a2ac86f
+  data.tar.gz: 0eb79799a209e4798e2a6fa2ed8688183a43cfbf4460fe45a7014409e3daa3b761c516d3b8ae0287832c5c32cf6be175215c99ffefc9444b126c048251157b0d

data/HISTORY.md

@@ -1,5 +1,20 @@
 # RELEASE HISTORY
 
+## 0.3.0 / 2026-04-08
+
+Fold in the `import`/`import_relative` feature from rubyworks/finder.
+
+Changes:
+
+* Add `Kernel#import` and `Kernel#import_relative` (require
+  `'main_like_module/import'`) as scope-aware alternatives to `require`
+  and `require_relative`. They evaluate the loaded script into the
+  current scope rather than into the toplevel, providing a partial
+  workaround for Problem 1 (toplevel pollution of Object).
+* Update README to document the new feature and explain how the two
+  pieces of the library address Ruby's two toplevel design quirks.
+
+
 ## 0.2.0 / 2026-04-07
 
 Maintenance release modernizing the project.

data/README.md

@@ -87,11 +87,14 @@ not a hand-picked subset.
 
 ## What This Library Does
 
-The first problem — toplevel polluting `Object` — cannot be fixed from
-userland. It is baked into the parser and the interpreter. Only a change
-to Ruby itself could address it.
+This library addresses both problems, though only one of them fully.
+
+### Completing the Toplevel Proxy (Problem 2)
+
+```ruby
+    require 'main_like_module'
+```
 
-The second problem *can* be addressed, and that is what this library does.
 On `require`, it walks `Module`'s instance methods and, for each one not
 already available at the toplevel, defines a singleton method on `main`
 that forwards the call to `Object.class_eval`. The result is that anything
@@ -108,9 +111,45 @@ you can do inside a `module` body, you can now do at the toplevel as well.
 Public, private, and protected `Module` methods are all proxied with their
 correct visibility.
 
-Note carefully: this does *nothing* about Problem 1. The methods you define
-at the toplevel still end up on `Object`. This library only completes the
-proxy; it does not redesign the toplevel.
+### A Partial Workaround for Toplevel Pollution (Problem 1)
+
+```ruby
+    require 'main_like_module/import'
+```
+
+The parser-level pollution of `Object` cannot be fixed from userland —
+that ship sailed when the Ruby grammar was written. But for code you
+*write yourself*, this library provides `Kernel#import` and
+`Kernel#import_relative` as scope-aware alternatives to `require` and
+`require_relative`. They evaluate the loaded script directly into the
+*current scope* rather than into the toplevel:
+
+```ruby
+    require 'main_like_module/import'
+
+    module MyApp
+      import 'helpers'   # helpers.rb is evaluated into MyApp,
+                         # not into Object
+    end
+
+    MyApp.some_helper_method   #=> works
+    Object.private_instance_methods.include?(:some_helper_method)
+    #=> false  -- Object stays clean
+```
+
+`import` searches `$LOAD_PATH` the way `require` does. `import_relative`
+resolves its argument relative to the calling file the way
+`require_relative` does. Both raise `LoadError` on miss.
+
+This is a *partial* workaround. It only helps for code that uses `import`
+explicitly — toplevel code in scripts you don't control still pollutes
+`Object`. But for organizing your own libraries into clean module
+namespaces without ceremony, it is genuinely useful.
+
+`import` was originally part of the `rubyworks/finder` gem, which has
+been folded into `main_like_module` because the two libraries are really
+about the same thing: making Ruby's toplevel/module loading semantics
+behave more sensibly.
 
 
 ## Should You Use This?

data/lib/main_like_module/import.rb

@@ -0,0 +1,61 @@
+# Kernel#import and Kernel#import_relative are variants of #require and
+# #require_relative that evaluate the loaded script *into the current scope*
+# instead of into the toplevel. This provides a partial workaround for the
+# fact that toplevel definitions in Ruby pollute Object globally.
+#
+#   module MyApp
+#     import 'somefile'   # somefile's contents are loaded into MyApp,
+#                         # not into Object
+#   end
+#
+# Originally extracted from rubyworks/finder.
+
+module Kernel
+
+  private
+
+  # Find +feature+ in $LOAD_PATH and evaluate it into the current scope.
+  #
+  # Unlike #require, definitions in the loaded file are added to whatever
+  # scope #import was called from rather than to Object.
+  def import(feature)
+    file = nil
+    if File.file?(feature) && File.absolute_path(feature) == feature
+      file = feature
+    else
+      candidates = feature.end_with?('.rb') ? [feature] : ["#{feature}.rb", feature]
+      $LOAD_PATH.each do |dir|
+        candidates.each do |c|
+          path = File.expand_path(c, dir)
+          if File.file?(path)
+            file = path
+            break
+          end
+        end
+        break if file
+      end
+    end
+    raise LoadError, "no such file to import -- #{feature}" unless file
+    instance_eval(::File.read(file), file)
+  end
+
+  # Like #import, but resolves +fname+ relative to the file that called
+  # #import_relative (mirroring how #require_relative works).
+  def import_relative(fname)
+    call = caller.first
+    fail "Can't parse #{call}" unless call.rindex(/:\d+(:in [`'].*[`'])?$/)
+    path = $`
+    if /\A\((.*)\)/ =~ path # eval, etc.
+      raise LoadError, "import_relative is called in #{$1}"
+    end
+    base = File.expand_path(fname, File.dirname(path))
+    file = if File.file?(base)
+             base
+           elsif File.file?("#{base}.rb")
+             "#{base}.rb"
+           end
+    raise LoadError, "no such file to import -- #{base}" unless file
+    instance_eval(::File.read(file), file)
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: main_like_module
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Trans
@@ -49,6 +49,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/main_like_module.rb
+- lib/main_like_module/import.rb
 homepage: https://github.com/rubyworks/main_like_module
 licenses:
 - BSD-2-Clause