Glossary

These are the words Carton’s docs, code, and errors use. Each entry lists the words to avoid.

Cartons

Carton: An importable unit of Ruby code, gem-sized or domain-sized, with an Interior and a Public Surface: an Entrypoint plus the directory named after it. Avoid: Package, pack, unit, component, box, plain carton, unbundled carton

Entrypoint: The file an Import loads to establish a Carton boundary, such as billing.rb. A file with no directory beside it is a Carton of one file. Avoid: Manifest, index file, main file

Interior: The files under the directory beside a Carton’s Entrypoint, such as billing/invoice.rb, including implicit-namespace subdirectories. They cannot be imported; the outermost Entrypoint above them owns them. A Carton may nest inside another Carton’s tree, but not inside its Interior. Avoid: Internals, private files, namespace directory

Gem-shaped Directory: A directory such as billing/ holding lib/billing.rb, which an Import of the directory resolves to as the Entrypoint. Avoid: Package directory, component directory

Boxes

Ruby names three kinds of Box: the Master Box, the Root Box, and User Boxes. A User Box is the Main Box or an Optional Box, and Carton adds one kind of Optional Box, the Carton Box.

Box: A Ruby execution environment with isolated loading and definitions. Every Carton runs in its own Carton Box; the top-level application runs in the Main Box. Avoid: Namespace (Ruby’s pre-release name for Box), Carton instance, runtime carton, sandbox

Master Box: Ruby’s master copy of every Box: the Root Box and every User Box start as copies of it. Ruby intends no code to run in it, and Carton never writes to it. Avoid: Template box, source box, root box

Root Box: Ruby’s single Box for bootstrap, where builtin classes are defined and their methods run. It is not a User Box. Avoid: Builtin box, bootstrap box

User Box: A Box that runs user code rather than Ruby’s bootstrap: the Main Box or an Optional Box. Avoid: Application box

Main Box: The User Box Ruby creates for the program named on the ruby command line and its -r files. The top-level application runs and imports Cartons there; it is not itself a Carton. Avoid: Root Box, root carton, main carton, app box, main (Ruby’s top-level object)

Optional Box: A User Box created with Ruby::Box.new: every User Box except the Main Box. Avoid: Child box, sub-box, extra box

Carton Box: The Optional Box Carton creates for a Carton’s first Import, where the Carton’s code and gems load. Importers never receive it. Avoid: Child box, Import box

Template Box: A Box that other Boxes would start from, carrying a shared baseline such as patches to builtins. Ruby has none yet, and Carton asks for one; the Master Box is not one. Avoid: Prelude box, base box

Importing

Import: Loading a Carton into its Carton Box and receiving its Export or Namespace. Only an Import crosses a Carton boundary; code loaded without one remains inside the current Carton. Avoid: Require, load

Importer: The code that runs an Import: the application in the Main Box, or another Carton. Avoid: Caller, parent

First Importer: The Importer whose Import loads a Carton. It fixes the Carton’s gem versions for the whole process. Avoid: Owner

Shared Import: An Import of a Carton already loaded in the process. It returns the same Export or Namespace as the First Importer received, so every Importer shares one Carton. Avoid: Cached carton, singleton carton

Imported Carton: A Carton an Importer imports directly. It remains a separate boundary and exposes only its Public Surface. Avoid: Child carton, nested carton, dependency

Transitive Carton: A Carton reached indirectly through an Imported Carton. Avoid: Imported carton when the relationship is indirect

Second Copy: A Carton’s code loaded outside its boundary by a plain require of its Entrypoint or Interior. Its classes are separate objects from the Imported Carton’s. Avoid: Duplicate load, reach-in

Dynamic Import: An Import whose path is computed at runtime, so static tools cannot follow it. Avoid: Runtime import, unchecked import

Exporting

Export: The one value a Carton’s Entrypoint gives export, returned as is when the Carton is imported: usually its root module, or a Hash from keywords. Calls in any other file, including files loaded by plain require, declare nothing. A Bare Carton has none. Avoid: Default export, named exports, export declaration

Public Surface: Everything a Carton deliberately makes reachable across its boundary: its Export or Namespace, and what those expose. Avoid: API, public API, exports

Bare Carton: A Carton whose Entrypoint never calls export. The constants and Helpers its Entrypoint defines are its Public Surface, returned as a Namespace. Avoid: Unexported carton, script carton

Helper: A top-level method a Bare Carton’s Entrypoint defines, callable through its Namespace. Avoid: Function, Bare Carton method

Namespace: The Carton::Namespace module a Bare Carton’s Importers receive, holding its constants and Helpers. Avoid: Exports, export namespace

Gems and bundles

Gem Carton: A Carton whose Entrypoint belongs to a gem the Importer has activated, such as a path gem in the app’s Gemfile. Its Carton Box gets the gem’s Gem Closure at the Importer’s versions. Avoid: Gem package

Gem Closure: The gem that owns a Gem Carton’s Entrypoint plus the runtime dependencies the Importer has activated for it, transitively. Avoid: Dependency closure, dependency tree

Carton Bundle: A bundle a Carton sets up in its own Carton Box from its own Gemfile, separate from its Importer’s. Avoid: Nested bundle, sub-bundle

Undeclared Gem: A gem a Gem Carton loads that its gemspec does not declare as a runtime dependency. It loads under a bundled Importer but fails wherever the gem is not installed. Avoid: Implicit dependency, transitive leak