feat: refine scoping rules & names

resolves #1

* `self` -> `mod`
* `super` -> `pre`
* external dependencies are merged with `atom` in scope.
* on collision, local references take precedent.
* externals are always available via `atom.extern`.

README.md

@@ -16,7 +16,7 @@ code without having to perform a full evaluation. This could be used, e.g. to sh
 - **Isolation**: Modules are imported into the Nix store, enforcing boundaries and preventing relative path access.
 - **Introspection**: Unlike legacy modules, code is specified in its final form instead of as prototypes (functions), leading to much better and simpler introspective analysis.
 - **Simplicity**: The system is kept purposefully simple and flexible in order to remain performant and flexible.
-- **Scoping**: Each module and member has access to `self`, `super`, `atom`, `pub` and `std`.
+- **Scoping**: Each module and member has access to `mod`, `pre`, `atom`, and `std`.
 - **Standard Library**: Includes a standard library (`std`) augmented with `builtins`.
 
 ## How It Works
@@ -27,11 +27,10 @@ code without having to perform a full evaluation. This could be used, e.g. to sh
    - Subdirectories with `mod.nix`: Treated as nested modules.
 
 2. **Scoping**:
-   - `self`: Current module, includes `outPath` for accessing non-Nix files.
-   - `super`: Parent module (if applicable).
-   - `atom`: Top-level module.
+   - `mod`: Current module, includes `outPath` for accessing non-Nix files.
+   - `pre`: Parent module (if applicable).
+   - `atom`: Top-level module and external dependencies.
    - `std`: Standard library and `builtins`.
-   - `pub`: External resources, such as other atoms, free-form nix expressions, remote sources, etc.
 
 3. **Composition**: Modules are composed recursively, with `mod.nix` contents taking precedence.
 
@@ -53,7 +52,7 @@ in
 * Break out large functions or code blocks into their own files
 * Organize related functionality into subdirectories with their own "mod.nix" files.
 * Leverage provided scopes for clean, modular code.
-* Use `"${self}"` when needing to access non-Nix files within a module.
+* Use `"${mod}/foo.nix"` when needing to access non-Nix files within a module.
 
 ## Future Work
 

default.nix

@@ -15,13 +15,17 @@ let
 
 in
 {
-  pub ? { },
+  extern ? { },
 }:
 dir:
 let
   std = compose { } ./std // builtins;
+  atom' = builtins.removeAttrs (extern // atom // { inherit extern; }) [
+    "atom"
+    (baseNameOf dir)
+  ];
   atom = fix (
-    f: super: dir:
+    f: pre: dir:
     let
       contents = builtins.readDir dir;
 
@@ -31,18 +35,15 @@ let
 
       scope = scopedImport (
         {
-          inherit atom std;
-          self = self // {
+          inherit std;
+          atom = atom';
+          mod = builtins.removeAttrs self [ "mod" ] // {
             outPath = filterMod dir;
           };
         }
         // cond {
-          _if = super != { };
-          inherit super;
-        }
-        // cond {
-          _if = pub != { };
-          inherit pub;
+          _if = pre != { };
+          inherit pre;
         }
       );
 
@@ -57,8 +58,8 @@ let
             ${name} = f (
               self
               // cond {
-                _if = super != { };
-                inherit super;
+                _if = pre != { };
+                inherit pre;
               }
             ) path;
           }

dev/pkgs.nix

@@ -1,4 +1,4 @@
 let
-  inherit (pub.pins) nixpkgs;
+  inherit (atom.pins) nixpkgs;
 in
 import nixpkgs { }

dev/shell.nix

@@ -1,5 +1,5 @@
 {
-  pkgs ? self.pkgs,
+  pkgs ? mod.pkgs,
 }:
 pkgs.mkShell {
   packages = with pkgs; [

shell.nix

@@ -1,6 +1,6 @@
 let
   dev = import ./. {
-    pub = {
+    extern = {
       pins = import ./npins;
     };
   } ./dev;

test/bld/bar/mod.nix

@@ -1,5 +1,5 @@
 {
   foo = 1;
   bar = atom.foo + 2;
-  baz = self.bar + 4;
+  baz = mod.bar + 4;
 }

test/bld/bar/next/mod.nix

@@ -1,5 +1,5 @@
 {
 
-  g = super.foo + 4;
-  h = self.g + 3;
+  g = pre.foo + 4;
+  h = mod.g + 3;
 }

test/bld/buzz/bar/mod.nix

@@ -1,5 +1,5 @@
 {
   foo = 1;
   bar = atom.foo + 2;
-  baz = self.bar + 4;
+  baz = mod.bar + 4;
 }

test/bld/buzz/bar/next/mod.nix

@@ -1,5 +1,5 @@
 {
 
-  g = super.foo + 4;
-  h = self.g + 3;
+  g = pre.foo + 4;
+  h = mod.g + 3;
 }

test/bld/buzz/fuzz/bar/mod.nix

@@ -1,5 +1,5 @@
 {
   foo = 1;
   bar = atom.foo + 2;
-  baz = self.bar + 4;
+  baz = mod.bar + 4;
 }

test/bld/buzz/fuzz/bar/next/mod.nix

@@ -1,5 +1,5 @@
 {
 
-  g = super.foo + 4;
-  h = self.g + 3;
+  g = pre.foo + 4;
+  h = mod.g + 3;
 }

test/bld/buzz/fuzz/mod.nix

@@ -1,5 +1,5 @@
 {
   foo = 1;
-  bar = super.bar + 2;
-  baz = self.bar + 4;
+  bar = pre.bar + 2;
+  baz = mod.bar + 4;
 }

test/bld/buzz/fuzz/next/mod.nix

@@ -1,5 +1,5 @@
 {
 
-  g = super.foo + 4;
-  h = self.g + 3;
+  g = pre.foo + 4;
+  h = mod.g + 3;
 }

test/bld/buzz/fuzz/wuzz/bar/mod.nix

@@ -1,5 +1,5 @@
 {
   foo = 1;
   bar = atom.foo + 2;
-  baz = self.bar + 4;
+  baz = mod.bar + 4;
 }

test/bld/buzz/fuzz/wuzz/bar/next/mod.nix

@@ -1,5 +1,5 @@
 {
 
-  g = super.foo + 4;
-  h = self.g + 3;
+  g = pre.foo + 4;
+  h = mod.g + 3;
 }

test/bld/buzz/fuzz/wuzz/cuzz/bar/mod.nix

@@ -1,5 +1,5 @@
 {
   foo = 1;
   bar = atom.foo + 2;
-  baz = self.bar + 4;
+  baz = mod.bar + 4;
 }

test/bld/buzz/fuzz/wuzz/cuzz/bar/next/mod.nix

@@ -1,5 +1,5 @@
 {
 
-  g = super.foo + 4;
-  h = self.g + 3;
+  g = pre.foo + 4;
+  h = mod.g + 3;
 }

test/bld/buzz/fuzz/wuzz/cuzz/mod.nix

@@ -1,5 +1,5 @@
 {
   foo = 1;
   bar = atom.foo + 2;
-  baz = self.bar + 4;
+  baz = mod.bar + 4;
 }

test/bld/buzz/fuzz/wuzz/cuzz/next/mod.nix

@@ -1,5 +1,5 @@
 {
 
-  g = super.foo + 4;
-  h = self.g + 3;
+  g = pre.foo + 4;
+  h = mod.g + 3;
 }

test/bld/buzz/fuzz/wuzz/mod.nix

@@ -1,5 +1,5 @@
 {
   foo = 1;
-  bar = super.bar + 2;
-  baz = self.bar + 4;
+  bar = pre.bar + 2;
+  baz = mod.bar + 4;
 }

test/bld/buzz/fuzz/wuzz/next/mod.nix

@@ -1,5 +1,5 @@
 {
 
-  g = super.foo + 4;
-  h = self.g + 3;
+  g = pre.foo + 4;
+  h = mod.g + 3;
 }

test/bld/buzz/mod.nix

@@ -1,5 +1,5 @@
 {
   foo = 1;
-  bar = super.foo + 2;
-  baz = self.bar + 4;
+  bar = pre.foo + 2;
+  baz = mod.bar + 4;
 }

test/bld/buzz/next/mod.nix

@@ -1,5 +1,5 @@
 {
 
-  g = super.foo + 4;
-  h = self.g + 3;
+  g = pre.foo + 4;
+  h = mod.g + 3;
 }

test/bld/mod.nix

@@ -1,7 +1,7 @@
 {
   foo = 1;
   bar = atom.foo + 2;
-  baz = self.bar + 4;
+  baz = mod.bar + 4;
   test = std.set.filterMap;
-  x = builtins.readFile "${self}/bum";
+  x = builtins.readFile "${mod}/bum";
 }

test/bld/next/mod.nix

@@ -1,5 +1,5 @@
 {
 
-  g = super.foo + 4;
-  h = self.g + 3;
+  g = pre.foo + 4;
+  h = mod.g + 3;
 }