rixby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fc379f400b5e2b6213b52f64b4cc87c30138fab3f3ced3a0935b1e13a6a133ae
+  data.tar.gz: b6d14233a8f412d5a8de2bd9daa284e0a96ef22dd2c59e741909abe513bb186a
+SHA512:
+  metadata.gz: 761bea6040e72373f4a2d58591b8b4240c8678bfd1ba60cd2b7c545e268c89caefd16a25a92df2cccce002d52545d1c1f864bc0faa758ec9e9c4d6e166784f40
+  data.tar.gz: 6bddb361c92dd554440bed262f621d0fdeb1c0ccf423915dab7787cde2e484d69dd9b25e0ed2eb2b40c5b2fc54e38f99e4d866ac762b3f64d446db1f2c1aafd7

data/.tool-versions

@@ -0,0 +1 @@
+ruby 4.0.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Aaron Christiansen
+
+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/NOTES.md

@@ -0,0 +1,16 @@
+explicit export is vital so you don't throw out all of your imports as exports
+
+the idea doesn't really work without this
+
+```ruby
+export def x
+
+end
+
+export class X
+
+end
+
+export 3, as: Something
+```
+

data/README.md

@@ -0,0 +1,125 @@
+# Rixby
+
+Rixby uses Ruby 4.0's new `Ruby::Box` namespacing system to add explicit `import`/`export` syntax to Ruby, similar to ES Modules.
+
+Export the items you want to make public, and import only the items you need.
+This makes the source of methods or classes explicit.
+
+Unlike `require`, it also prevents files from "leaking" into each other.
+(That is, if `b` imports `a` and `c` imports `b`, `c` does not see `b`'s imports from `a`.)
+
+<table>
+<tr>
+  <td>shapes.rb</td><td>main.rb</td>
+</tr>
+<tr>
+  <td>
+
+```ruby
+class Rectangle export
+  # ...
+end
+
+class Circle export
+  # ...
+end
+
+export def unit_square = Rectangle.new(1, 1)
+```
+
+  </td>
+  <td>
+
+```ruby
+import { from 'shapes', :Circle, :unit_square }
+
+p Circle.new(...)
+p unit_square
+# `Rectangle` is not available here
+```
+
+  </td>
+
+</tr>
+
+> [!TIP]
+> For a more complete example, see the `example` directory.
+> Start from `canvas.rb`.
+
+
+> [!CAUTION]
+> This is a proof-of-concept/experiment.
+> **Do not use this in production!**
+
+
+## Usage
+
+Rixby requires Ruby 4.0+.
+
+1. Install the gem: `gem install rixby` or `bundle add rixby`
+2. Enable the experimental box feature: `export RUBY_BOX=1`
+3. Run Ruby with `-rixby` to make `import` and `export` available everywhere:
+  * (This is an `ubygems`-style alias - it's really `-r ixby`)
+
+```
+ruby -rixby main.rb
+```
+
+Export classes or modules by calling `export` within their body:
+
+```ruby
+class X
+  export
+  # ...
+end
+
+# or, more concisely, this also works
+class X export
+  # ...
+end
+```
+
+Export methods by prepending `export` to their definition:
+
+```ruby
+export def something
+  # ...
+end
+```
+
+To import classes, modules, or methods, use one of these two forms of `import`:
+
+```ruby
+#                     symbol names of each item to import ...........
+import { from 'file', :something_to_import, :something_else_to_import }
+
+# Or, import everything
+import { all 'file' }
+```
+
+## How does it work?
+
+`Ruby::Box` is Ruby 4.0's new namespacing feature.
+You can execute code in a box, and it acts as an isolated namespace for that code.
+
+Rixby works by executing each imported file in a box.
+Rixby injects `export` into the top-level namespace of the box, and tracks calls to it using an instance variable on the box.
+Later, `import` reads from that instance variables to extract classes/modules/methods and copy them into the current box.
+
+The `import` syntax needs some explaining - it uses a block even though there's no obvious need to:
+
+```ruby
+# This is what Rixby uses:
+import { from 'file', :A, :B }
+
+# Couldn't this just be...?
+import 'file', :A, :B
+```
+
+This is a sly trick to give `import` a `Binding` for the parent scope.
+This enables Rixby to define the imported methods or constants within that parent scope.
+The alternative would be to require `binding` to be passed explicitly to each `import` call, but this is much uglier.
+
+## Why is it called that?
+
+**R**u**by** **I**mport E**x**port... look, it's not the name that matters ;)

data/example/assertion.rb

@@ -0,0 +1,5 @@
+export def assert_equal(expected, actual)
+  if expected != actual
+    raise "assertion failed: #{expected} != #{actual}"
+  end  
+end

data/example/canvas.rb

@@ -0,0 +1,18 @@
+import { from 'shapes', :Circle, :Rectangle }
+
+class Canvas export
+  def initialize
+    @shapes = []
+  end
+  attr_reader :shapes
+
+  def add_circle(radius)
+    shapes << Circle.new(radius)
+  end
+
+  def add_rectangle(width, height)
+    shapes << Rectangle.new(width, height)
+  end
+
+  def total_area = shapes.map(&:area).sum
+end

data/example/canvas_test.rb

@@ -0,0 +1,17 @@
+import { from 'canvas', :Canvas }
+import { from 'shapes', :Rectangle, :Circle }
+import { from 'assertion', :assert_equal }
+
+export def canvas_demo
+  canvas = Canvas.new
+  canvas.add_circle(2)
+  canvas.add_rectangle(4, 5)
+
+  assert_equal 2, canvas.shapes.length
+  assert_equal Circle.new(2), canvas.shapes[0]
+  assert_equal Rectangle.new(4, 5), canvas.shapes[1]
+
+  puts canvas.total_area
+end
+
+canvas_demo

data/example/shapes.rb

@@ -0,0 +1,24 @@
+class Rectangle export
+  def initialize(width, height)
+    @width = width
+    @height = height
+  end
+
+  attr_reader :width, :height
+  def area = width * height
+
+  def ==(other) = other.is_a?(Rectangle) && width == other.width && height == other.height
+  def hash = [width, height].hash
+end
+
+class Circle export
+  def initialize(radius)
+    @radius = radius
+  end
+
+  attr_reader :radius
+  def area = radius * radius * Math::PI
+
+  def ==(other) = other.is_a?(Circle) && radius == other.radius
+  def hash = [radius].hash
+end

data/lib/ixby.rb

@@ -0,0 +1 @@
+require 'rixby'

data/lib/rixby/import_dsl.rb

@@ -0,0 +1,44 @@
+module Rixby
+  module ImportDsl
+    # Evaluation target for the `import` block
+    class ImportDslReceiver
+      def initialize
+        @filename = nil
+        @imports = []
+      end
+
+      attr_reader :filename, :imports
+
+      def from(filename, *imports)
+        @filename = filename
+        @imports = imports
+
+        if @imports.empty?
+          raise ArgumentError, 'import list cannot be empty. if you want to import everything, use `all` instead'
+        end
+
+        @imports.each do |import|
+          unless import.is_a?(Symbol)
+            raise TypeError, "imported names must be symbols, but got: #{import}"
+          end
+        end
+      end
+      
+      def all(filename)
+        @filename = filename
+        @imports = :all
+      end
+    end
+
+    def self.evaluate(&blk)
+      recv = ImportDslReceiver.new
+      recv.instance_exec(&blk)
+
+      if recv.filename.nil?
+        raise RuntimeError, 'import block did not specify anything to import'
+      end
+
+      recv
+    end
+  end
+end

data/lib/rixby/version.rb

@@ -0,0 +1,3 @@
+module Rixby
+  VERSION = '1.0.0'
+end

data/lib/rixby.rb

@@ -0,0 +1,93 @@
+require_relative 'rixby/import_dsl'
+
+# Store boxes for imported files as an instance variable on the main box.
+# Unlike a constant, this means all boxes are accessing the same value.
+if Ruby::Box.current == Ruby::Box.main
+  Ruby::Box.main.instance_variable_set(:@__rixby_boxes, {})
+end
+
+def import(&blk)
+  unless block_given?
+    raise 'you must pass a block to `import` describing the items to import'
+  end
+  block_binding = blk.binding
+
+  import_desc = Rixby::ImportDsl.evaluate(&blk)
+  filename = import_desc.filename
+
+  relative_to = File.dirname(block_binding.source_location[0])
+  absolute_filename = File.expand_path(filename, relative_to)
+
+  # Add `.rb` automatically if that would create a valid path
+  if !File.exist?(absolute_filename) && File.exist?(absolute_filename + '.rb')
+    absolute_filename += '.rb'
+  end
+
+  imported_boxes = Ruby::Box.main.instance_variable_get(:@__rixby_boxes)
+  if imported_boxes.has_key?(absolute_filename)
+    box = imported_boxes[absolute_filename]
+  else
+    box = Ruby::Box.new
+    box.instance_variable_set(:@__rixby_imported, true)
+    box.require(__FILE__)
+    box.require(absolute_filename)
+    imported_boxes[absolute_filename] = box
+  end
+
+  exports = box.instance_variable_get(:@__rixby_exports)
+  case import_desc.imports
+  when :all
+    imports = exports.keys
+  when Array
+    imports = import_desc.imports
+  else
+    raise 'internal error: malformed import array'
+  end
+
+  imports.each do |import|
+    export = exports[import] or raise(KeyError, "no export named `#{import}`")
+
+    case export
+    when Method
+      block_binding.receiver.define_singleton_method(import, &export)
+    when Module
+      block_binding.receiver.class.const_set(import, export)
+    else
+      raise "internal error: unsupported export type #{export}"
+    end
+  end
+end
+
+def export(item)
+  # If this file isn't being imported, we can ignore `export`.
+  # This is relevant if you `export` from the main file, where `singleton_method` doesn't seem to be
+  # able to look up methods correctly.
+  unless Ruby::Box.current.instance_variable_get(:@__rixby_imported)
+    return
+  end
+
+  case item
+  when Symbol
+    key = item
+    # Try both - sometimes one works, sometimes the other, I'm not sure why.
+    value = method(item) rescue singleton_method(item)
+  when Module
+    key = item.name.split('::').last.to_sym
+    value = item
+  else
+    raise ArgumentError, "unsupported item for export: #{item}"
+  end
+
+  box = Ruby::Box.current
+  unless box.instance_variable_defined?(:@__rixby_exports)
+    box.instance_variable_set(:@__rixby_exports, {})
+  end
+
+  exports = box.instance_variable_get(:@__rixby_exports)
+  exports[key] = value
+end
+EXPORT_METHOD = method(:export)
+
+Module.define_method(:export) do
+  EXPORT_METHOD.(self)
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: rixby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Aaron Christiansen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+email:
+- aaronc20000@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".tool-versions"
+- LICENSE
+- NOTES.md
+- README.md
+- example/assertion.rb
+- example/canvas.rb
+- example/canvas_test.rb
+- example/shapes.rb
+- lib/ixby.rb
+- lib/rixby.rb
+- lib/rixby/import_dsl.rb
+- lib/rixby/version.rb
+homepage: https://github.com/aaronc81/rixby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aaronc81/rixby
+  source_code_uri: https://github.com/aaronc81/rixby
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Modular file import/export for Ruby
+test_files: []