main_like_module 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77dd7a196964c1966a43660852408ba60eee5a6cea176b286ff822ad602acbf5
+  data.tar.gz: 1eb7d996917ce87927a4064806efc183a00fb0e5062b1e5708dd7d8bc0577652
+SHA512:
+  metadata.gz: 6f1b021260ba408ab94d9dd0f12f4e103313daf32286554883bda7f5ab0d6783cd1b4aaf900216bf0d753317caeaae244eff911016f821f67ba3b789c7330d82
+  data.tar.gz: 753e1fd13c10d9f5509a1ce976a73c84911d29f713458b13f9b7a64af74bf383cd9e70cef701f625834995c9982a90b02ac615420e8e9644533fc12462b20ca7

data/HISTORY.md

@@ -0,0 +1,23 @@
+# RELEASE HISTORY
+
+## 0.2.0 / 2026-04-07
+
+Maintenance release modernizing the project.
+
+Changes:
+
+* Replace .ruby/var metadata system with standard gemspec.
+* Replace Travis CI with GitHub Actions (Ruby 3.1–3.4).
+* Switch tests from citron/ae to minitest.
+* Add Rakefile.
+* Rewrite README to elaborate on the design argument.
+* Require Ruby >= 3.1.
+
+
+## 0.1.0 / 2011-12-23
+
+Initial and quite hopefully the only release ever needed.
+
+Changes:
+
+* Spun project off from Ruby Facets.

data/LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2006 Rubyworks
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,163 @@
+# Main Like Module
+
+[Source Code](https://github.com/rubyworks/main_like_module) |
+[Report Issue](https://github.com/rubyworks/main_like_module/issues)
+
+[![Gem Version](https://img.shields.io/gem/v/main_like_module.svg?style=flat)](https://rubygems.org/gems/main_like_module)
+[![Build Status](https://github.com/rubyworks/main_like_module/actions/workflows/test.yml/badge.svg)](https://github.com/rubyworks/main_like_module/actions/workflows/test.yml)
+
+**Main Like Module** is a small demonstration library that fills in the
+missing parts of Ruby's toplevel object so that it behaves more like a
+fully functional module context.
+
+This library is *not* meant to be a useful tool that you should depend on
+in real code. It exists to make a point about a quirk in Ruby's design,
+and to do what it can about that quirk given the language as it stands.
+
+
+## The Argument
+
+When you start a Ruby program, you are not in some abstract "global" space.
+You are inside an object — a real, live object that Ruby refers to internally
+as `main`. You can prove it to yourself trivially:
+
+```ruby
+    puts self            #=> main
+    puts self.class      #=> Object
+```
+
+So `main` is just an instance of `Object`. That, by itself, is not strange.
+What *is* strange is what Ruby does when you define methods or constants
+at the toplevel.
+
+### Problem 1: Toplevel Pollutes Object
+
+When you write a method definition at the toplevel of a Ruby program, Ruby
+does not attach it to `main` — it attaches it to `Object` itself, as a
+private instance method. The consequence is that *every* object in the
+entire system inherits it.
+
+```ruby
+    def hello
+      'hi'
+    end
+
+    "any string".send(:hello)   #=> "hi"
+    42.send(:hello)             #=> "hi"
+    Class.new.new.send(:hello)  #=> "hi"
+```
+
+That is a remarkable amount of action-at-a-distance for what looks like a
+simple, innocuous toplevel definition. The toplevel — which one might
+reasonably expect to be the *least* invasive scope in the language — is
+in fact the *most* invasive.
+
+A more sensible design would be for `main` to be a self-extended module:
+
+```ruby
+    module Toplevel
+      extend self
+      # the user's program runs here
+    end
+```
+
+Under that design, methods defined at the toplevel would be confined to the
+`Toplevel` module. They would still be available for the user's script (because
+`extend self` makes them callable as instance methods on the module itself),
+but they would not silently bolt themselves onto every object in the system.
+Constants defined at the toplevel would be `Toplevel::FOO` rather than the
+ambient `::FOO` they are today.
+
+### Problem 2: The Toplevel Proxy Is Incomplete
+
+Ruby already does a partial job of making `main` *behave like* a module.
+Methods such as `private`, `public`, and `include` work at the toplevel —
+they are forwarded to `Object`. But the proxy is incomplete: many of the
+methods you would expect to find on a module context simply do not work
+there. For example:
+
+```ruby
+    define_method(:foo) { 'bar' }
+    #=> NoMethodError: undefined method `define_method' for main:Object
+```
+
+This is inconsistent. If `main` is meant to act like the module body of
+`Object`, then *all* of `Module`'s instance methods ought to work there,
+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.
+
+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
+you can do inside a `module` body, you can now do at the toplevel as well.
+
+```ruby
+    require 'main_like_module'
+
+    define_method(:greet) { |name| "Hello, #{name}!" }
+
+    greet('World')   #=> "Hello, World!"
+```
+
+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.
+
+
+## Should You Use This?
+
+Probably not. If you want a clean module context, the right thing to do is
+to write one:
+
+```ruby
+    module MyApp
+      extend self
+
+      def greet(name)
+        "Hello, #{name}!"
+      end
+    end
+
+    MyApp.greet('World')
+```
+
+That gives you everything `main_like_module` aspires to, without monkey-
+patching the toplevel and without polluting `Object`. Treat the toplevel
+as a launch pad into your own namespace and you will avoid the whole
+mess.
+
+This gem exists as a demonstration: a small, working illustration of how
+*close* Ruby comes to having a sane toplevel, and how a few dozen lines
+of metaprogramming are enough to close part of the gap.
+
+
+## Installation
+
+```
+    $ gem install main_like_module
+```
+
+Or in a `Gemfile`:
+
+```ruby
+    gem 'main_like_module'
+```
+
+
+## Copyrights
+
+Main Like Module is copyrighted open source software.
+
+    Copyright (c) 2006 Rubyworks (BSD-2-Clause)
+
+It can be distributed and modified in accordance with the **BSD-2-Clause**
+license. See LICENSE.txt for details.

data/lib/main_like_module.rb

@@ -0,0 +1,62 @@
+# Main like Module
+#
+# Main, ie. the top-level object, is not fully in-sync with
+# Module. So, certain methods like #define_method do not work.
+# This library fixes this.
+#
+# Techinally it is this authors opinion that the top-level object
+# most likely would be better-off as a self-extended module, and
+# methods defined in it do not automatically get added to the
+# Object class.
+#
+# On the other hand. It is probably best to never use the toplevel
+# except as a jumping in point to youre own namespace.
+#
+# Note that none of this would be needed if Main were just a self extended
+# module.
+
+def_meth = Proc.new do |m|
+  if /=$/ =~ m.to_s
+    eval <<-END
+      def self.#{m}(arg)
+        Object.class_eval do
+          #{m}(arg)
+        end
+      end
+    END
+  else
+    eval <<-END
+      def self.#{m}( *args, &block )
+        Object.class_eval do
+          #{m}( *args, &block )
+        end
+      end
+    END
+  end
+end
+
+public
+
+(Module.public_instance_methods - public_methods).each do |m|
+  next if m == "initialize"
+  next if m =~ /^\W+$/
+  def_meth[m]
+end
+
+private
+
+(Module.private_instance_methods - private_methods).each do |m|
+  next if m == "initialize"
+  next if m =~ /^\W+$/
+  def_meth[m]
+end
+
+protected
+
+(Module.protected_instance_methods - protected_methods).each do |m|
+  next if m == "initialize"
+  next if m =~ /^\W+$/
+  def_meth[m]
+end
+
+# Copyright (c) 2006 Thomas Sawyer (Ruby License)

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: main_like_module
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Trans
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+description: A small demonstration library that fills in the missing parts of Ruby's
+  toplevel object so that it behaves like a fully functional module context.
+email:
+- transfire@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- HISTORY.md
+- LICENSE.txt
+- README.md
+- lib/main_like_module.rb
+homepage: https://github.com/rubyworks/main_like_module
+licenses:
+- BSD-2-Clause
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Completes the toplevel proxy of the Object class.
+test_files: []