carton 0.1.0 → 0.3.0

data/USAGE.md

@@ -1,173 +0,0 @@
-# Usage
-
-## Requirements
-
-- Ruby 4.0+
-- `RUBY_BOX=1`
-- `require 'carton'` before using `import`, `import_relative`, `export_default`, or `export`
-
-In Carton, an importable package is called a carton. This guide still says "package" sometimes in plain English, but "carton" is the project term.
-
-## Exporting
-
-### Single export
-
-Use a single export when the file represents one main thing.
-
-```ruby
-# user.rb
-class User
-  def initialize(name) = @name = name
-
-  def greet = "Hello, #{@name}!"
-end
-
-export_default User
-```
-
-Importing that file returns the exported object itself:
-
-```ruby
-User = import_relative 'user'
-User.new('Alice').greet
-```
-
-### Named exports
-
-Use keyword arguments when the file exports a small namespace.
-
-```ruby
-# math.rb
-def add(a, b) = a + b
-
-export(
-  PI: 3.14159,
-  version: '1.0.0',
-  add: method(:add)
-)
-```
-
-Importing named exports returns a `Carton::Exports` object, which behaves like a namespace module.
-
-```ruby
-MathTools = import_relative 'math'
-
-MathTools::PI
-MathTools.version
-MathTools.add(2, 3)
-```
-
-`Carton::Exports` and bare `Carton::Box` imports share a small lookup API: `[]`, `fetch`, `fetch_values`, `values_at`, and `key?`.
-
-Only one export call is allowed per imported file. Use `export_default value` for single exports or `export foo:, bar:` for named exports.
-
-## Importing
-
-### `import_relative`
-
-`import_relative path` resolves relative to the calling file, like `require_relative`.
-
-```ruby
-User = import_relative 'user'
-```
-
-### `import`
-
-`import path` resolves using the current box's `$LOAD_PATH` or an absolute path.
-
-```ruby
-Quest = import 'quest'
-Widget = import '/absolute/path/to/widget.rb'
-```
-
-When you want `import 'name'` to work across local cartons, add their `lib/` directories to `$LOAD_PATH` first.
-
-```ruby
-cartons_dir = File.expand_path('cartons', __dir__)
-
-Dir.glob(File.join(cartons_dir, '*/lib')).sort.each do |dir|
-  $LOAD_PATH.unshift(dir) unless $LOAD_PATH.include?(dir)
-end
-```
-
-The complex example keeps that setup explicit in `examples/complex/main.rb`.
-
-## Destructuring
-
-Named exports support pattern matching through `deconstruct_keys`.
-
-```ruby
-import_relative('math') => { add:, version: }
-
-add.(2, 3)
-version
-```
-
-You can rename during destructuring:
-
-```ruby
-import_relative('math') => { add: sum }
-sum.(10, 10)
-```
-
-## Constants
-
-For exported constants, the simplest options are namespace access, `[]`, or `fetch`.
-
-```ruby
-MathTools = import_relative 'math'
-PI = MathTools::PI
-```
-
-```ruby
-PI = import('math')[:PI]
-```
-
-For multiple values:
-
-```ruby
-PI, version = import_relative('math').fetch_values(:PI, :version)
-```
-
-## Bare imports
-
-If a file does not call `export`, importing it returns the `Carton::Box` itself.
-
-```ruby
-Toolbox = import 'some_script'
-
-Toolbox::SomeConstant
-Toolbox.fetch(:helper)
-```
-
-## Bundler inside cartons
-
-The library works with or without Bundler. Plain cartons need no extra setup. For a bundled carton, the reliable pattern today is still: select the Gemfile around the `import` that loads that carton.
-
-```ruby
-gemfile = File.expand_path('cartons/adventure/Gemfile', __dir__)
-
-Adventure = Carton.with_bundle(gemfile) { import 'adventure' }
-```
-
-`Carton.with_bundle` is just a small wrapper around the same `BUNDLE_GEMFILE` handoff. The underlying constraint is still Bundler's: `bundler/setup` discovers the active Gemfile from env/process state, and RubyGems activation state (`Gem.loaded_specs`) is still shared across boxes in practice, so conflicting bundles still cannot be switched reliably in one process today.
-
-Current limits:
-
-- one carton-local bundle can be activated cleanly from an unbundled parent
-- a bundled parent process is not a reliable place to import a child carton with its own bundle
-- conflicting bundles in one process still need a subprocess workaround
-
-See [TODO.md](TODO.md) for the upstream Bundler work that would make this cleaner.
-
-## Examples
-
-```sh
-RUBY_BOX=1 ruby examples/minimal/main.rb
-RUBY_BOX=1 bundle exec rake example:complex
-```
-
-See the example READMEs for details:
-
-- [examples/minimal/README.md](examples/minimal/README.md)
-- [examples/complex/README.md](examples/complex/README.md)

data/examples/complex/README.md

@@ -1,33 +0,0 @@
-# Complex example
-
-Multi-carton example showing the library directly: explicit load-path setup, a bundled single export loaded by name, a plain carton loaded by name, and a destructured import.
-
-## Cartons
-
-| Carton | Purpose |
-| --- | --- |
-| `main` | explicit feature tour of the library |
-| `adventure` | bundled carton imported by name |
-| `quest` | plain carton imported by name |
-| `loot` | carton that demonstrates a conflicting `dotenv` version via subprocess |
-
-`main.rb` keeps the load-path setup and bundled import explicit on purpose so the example reads like a direct Carton feature tour. `Carton.with_bundle` shortens the `BUNDLE_GEMFILE` handoff, but it is still the same Bundler constraint under the hood.
-
-## Why `loot` still uses a subprocess
-
-One carton-local bundle can be activated from an unbundled parent today. The trouble starts when another box tries to activate a conflicting version: box-local `$LOAD_PATH` is not enough because RubyGems activation state is still shared. `loot` therefore loads its `dotenv` data in a subprocess and selects its Gemfile there instead of using `Carton.with_bundle` during the import itself. That is tracked in [../../TODO.md](../../TODO.md).
-
-## Run
-
-```sh
-RUBY_BOX=1 bundle exec rake example:complex
-```
-
-Or manually:
-
-```sh
-cd examples/complex/cartons/adventure && BUNDLE_GEMFILE=Gemfile bundle install
-cd ../loot && BUNDLE_GEMFILE=Gemfile bundle install
-cd ../../..
-RUBY_BOX=1 ruby examples/complex/main.rb
-```

data/examples/complex/cartons/adventure/.env

@@ -1 +0,0 @@
-BANNER=single export loaded from a bundled carton

data/examples/complex/cartons/adventure/Gemfile

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-gem 'dotenv', '~> 3.0'

data/examples/complex/cartons/adventure/Gemfile.lock

@@ -1,17 +0,0 @@
-GEM
-  remote: https://rubygems.org/
-  specs:
-    dotenv (3.2.0)
-
-PLATFORMS
-  arm64-darwin-25
-  ruby
-
-DEPENDENCIES
-  dotenv (~> 3.0)
-
-CHECKSUMS
-  dotenv (3.2.0) sha256=e375b83121ea7ca4ce20f214740076129ab8514cd81378161f11c03853fe619d
-
-BUNDLED WITH
-  4.0.3

data/examples/complex/cartons/adventure/lib/adventure.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require 'dotenv'
-
-module Adventure
-  CONFIG = Dotenv.parse(File.expand_path('../.env', __dir__))
-  def self.banner = CONFIG.fetch('BANNER')
-
-  def self.dotenv_version = Gem.loaded_specs.fetch('dotenv').version.to_s
-end
-
-export_default Adventure

data/examples/complex/cartons/loot/.env

@@ -1 +0,0 @@
-MESSAGE=loaded through a conflicting bundle in a subprocess

data/examples/complex/cartons/loot/Gemfile

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-gem 'dotenv', '~> 2.0'

data/examples/complex/cartons/loot/Gemfile.lock

@@ -1,17 +0,0 @@
-GEM
-  remote: https://rubygems.org/
-  specs:
-    dotenv (2.8.1)
-
-PLATFORMS
-  arm64-darwin-25
-  ruby
-
-DEPENDENCIES
-  dotenv (~> 2.0)
-
-CHECKSUMS
-  dotenv (2.8.1) sha256=c5944793349ae03c432e1780a2ca929d60b88c7d14d52d630db0508c3a8a17d8
-
-BUNDLED WITH
-  4.0.3

data/examples/complex/cartons/loot/lib/loot.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'open3'
-require 'rbconfig'
-
-Plans = import 'quest'
-
-# This carton is imported plainly by name. The subprocess below is where it
-# selects its own Gemfile, because doing the conflicting dotenv activation
-# directly in another box still collides through shared RubyGems activation
-# state and can even crash under Ruby::Box today.
-dotenv_payload =
-  begin
-    env_file = File.expand_path('../.env', __dir__)
-    gemfile = File.expand_path('../Gemfile', __dir__)
-    script = <<~'RUBY'
-      require 'json'
-      require 'bundler/setup'
-      require 'dotenv'
-
-      config = Dotenv.parse(ARGV.fetch(0))
-      version = Gem.loaded_specs.fetch('dotenv').version.to_s
-      puts JSON.generate(version:, config:)
-    RUBY
-
-    output, status =
-      Open3.capture2e(
-        { 'BUNDLE_GEMFILE' => gemfile },
-        RbConfig.ruby,
-        '-e',
-        script,
-        env_file,
-      )
-
-    unless status.success?
-      raise RuntimeError, "failed to load loot dotenv bundle: #{output}"
-    end
-
-    JSON.parse output
-  end
-
-dotenv_version = dotenv_payload.fetch 'version'
-legacy_message =
-  "#{dotenv_payload.fetch('config').fetch('MESSAGE')} | quest says: #{Plans.fetch :summary}"
-
-export legacy_message:, DOTENV_VERSION: dotenv_version

data/examples/complex/cartons/quest/lib/quest.rb

@@ -1,6 +0,0 @@
-# frozen_string_literal: true
-
-FEATURES = ['single exports', 'named exports', 'import by name'].freeze
-SUMMARY = 'plain carton loaded by name'
-
-export FEATURES:, summary: SUMMARY

data/examples/complex/main.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../../lib/carton'
-
-cartons_dir = File.expand_path('cartons', __dir__)
-
-# Local carton lib directories still need to be on the caller's load path when
-# we want import 'name' to resolve inside nested boxes.
-Dir
-  .glob(File.join(cartons_dir, '*/lib'))
-  .sort
-  .each { |dir| $LOAD_PATH.unshift(dir) unless $LOAD_PATH.include?(dir) }
-
-adventure_gemfile = File.expand_path('cartons/adventure/Gemfile', __dir__)
-
-# Bundler still picks the active Gemfile from env/process state today, so the
-# bundled import stays explicit even though the wrapper is small.
-Adventure = Carton.with_bundle(adventure_gemfile) { import 'adventure' }
-
-Plans = import 'quest'
-
-# loot still imports by name, but it does not need Carton.with_bundle here
-# because the conflicting dotenv activation happens entirely in the subprocess
-# inside loot.rb, not during this import itself.
-import('loot') => { legacy_message:, DOTENV_VERSION: loot_dotenv_version }
-
-puts '-- Bundled single export --'
-puts "Adventure.banner = #{Adventure.banner}"
-puts "Adventure.dotenv_version = #{Adventure.dotenv_version}"
-puts
-puts '-- Named export loaded by name --'
-puts "Plans::FEATURES = #{Plans::FEATURES.join(', ')}"
-puts "Plans.summary = #{Plans.fetch :summary}"
-puts
-puts '-- Destructured named export --'
-puts "loot dotenv version = #{loot_dotenv_version}"
-puts "legacy_message = #{legacy_message}"

data/examples/minimal/README.md

@@ -1,16 +0,0 @@
-# Minimal example
-
-Smallest working example of the library.
-
-## What it shows
-
-- single export (`foo.rb`, `baz.rb`)
-- named exports (`bar.rb`)
-- `import_relative`
-- one carton importing another carton internally
-
-## Run
-
-```sh
-RUBY_BOX=1 ruby examples/minimal/main.rb
-```

data/examples/minimal/bar.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-# Bar depends on Baz via import_relative
-Baz = import_relative 'baz'
-
-def hello
-  "Hello from Bar! (#{Baz.hello})"
-end
-
-export hello: method(:hello), MAGIC: 42

data/examples/minimal/baz.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module Baz
-  def self.hello = 'Hello from Baz!'
-end
-
-export_default Baz

data/examples/minimal/foo.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module Foo
-  def self.hello = 'Hello from Foo!'
-end
-
-export_default Foo

data/examples/minimal/main.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../../lib/carton'
-
-# Single import — Foo exports a module
-Foo = import_relative 'foo'
-
-# Namespace import — Bar exports a hash with methods and constants
-Bar = import_relative 'bar'
-
-puts '-- Foo --'
-puts Foo.hello
-
-puts
-puts '-- Bar (uses Baz internally) --'
-puts Bar.hello
-puts "Bar::MAGIC = #{Bar::MAGIC}"

data/lib/carton/exports.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module Carton
-  class Exports < ::Module
-    include ExportMethods
-
-    def initialize(values = {})
-      super()
-      @values = values
-      @lookup = {}
-      define_exports
-    end
-
-    private
-
-    def define_exports
-      @values.each do |key, value|
-        @lookup[key.to_s] = value
-
-        if key.to_s.match?(/\A[A-Z]/)
-          const_set(key, value)
-        else
-          define_singleton_method(
-            key,
-          ) { |*args, **kwargs, &block| value.respond_to?(:call) ? value.call(*args, **kwargs, &block) : value }
-        end
-      end
-    end
-
-    def lookup_entry(key)
-      name = key.to_s
-      @lookup.key?(name) ? [true, @lookup[name]] : [false, nil]
-    end
-  end
-end