Decision D011 · accepted; the `/` separator superseded by D029
Modules and imports: one path separator, Rust-style use
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-15); importing an enum's variants by name, in the module that defines the enum too (D010 §3b), implemented on 2026-11-18; the open questions below are not yet decided
Decision
Paths use / at every level
Superseded (2026-11-16) by D029: paths and members use the dot,
std.term.style.parse,geom.Shape.area. The rest of this decision (modules are files,use, visibility, exports,std) stays, with.in place of/in its examples.
A path is a sequence of segments separated by /, at every level: module, nested module, item, protocol method.
std/rt/alloc ; a module
std/rt/alloc/bump ; a function in that module
geom/Shape ; a protocol in a module
geom/Shape/area ; a protocol method
A symbol that is exactly / is the division function, as in Clojure.
A module is a file
A module's path is its file's path relative to the source root: src/geom/shapes.dias is the module geom.shapes. Files contain no ns form. In the REPL, a command switches the current module.
A full path always works
Any public item can be reached by its full path without an import: (geom.Shape.area c).
use only shortens paths
use is an ordinary top-level form, as in Rust, so it can also be typed in the REPL.
| Rust | Diaspar |
|---|---|
use geom; |
(use geom) |
use geom as g; |
(use geom as: g) |
use geom::Shape; |
(use geom.Shape) |
use geom::{Shape, Land}; |
(use geom [Shape Land]) |
use geom::Shape as S; |
(use geom.Shape as: S) |
use std::{fs, io::Read}; |
(use std [fs io.Read]) |
geom::Shape::area(&c) |
(geom.Shape.area c) |
The forms:
(use path)makes the last segment of the path available:(use geom.Shape)givesShape.(use path as: name)makes it available under another name (labels, D030).(use path [item …])makes several items underpathavailable. An item is a name, a sub-path (io.Read), or(name as: alias). The brackets are a list (D008).
Short names appear only through use
Nothing becomes available implicitly: a file shows where every short name comes from. This includes protocol methods (D010): area is available only after (use geom.Shape [area]). The one exception is inside defprotocol P and extend-type T P, where method names refer to P's methods.
Name conflicts can therefore happen in only one place, the use line, and are resolved there:
(use geom.Shape [area])
(use geom.Land [area]) ; error: area is already imported from geom.Shape
(use geom.Land [(area as: land-area)]) ; renamed at import
There is no import of everything (Rust's use geom::*) for now.
An enum's variants are imported the same way, (use geom.Shape [Circle Rect]), and in the module that defines the enum too (D010 §3b): each imported name is that enum's variant, even when another enum of the module has a variant of the same name. A variant that is not imported is reached through its enum, so its name never hides a name of the prelude.
Visibility (accepted at module level)
Items are public by default, as in Clojure; private ones are marked, as with Elixir's defp, and privacy is checked at compile time, with no escape hatch such as Clojure's #'ns/name.
;; src/geom.dias
(defn area [s] …) ; public
(defn- normalize [s] …) ; private to geom
(def ^:private cache …) ; a private value
(deftype Account [balance] opaque: true) ; the type is visible; its constructor and fields are not (D010)
;; src/app.dias
(use geom)
(geom.area s) ; works
(geom.normalize s) ; compile error: geom.normalize is private
defn- covers the most common case; ^:private marks any other definition, types included: (deftype ^:private Layout [width gutter]), (defenum ^:private Step …), and the same for defeffect and defprotocol (stated 2026-11-17, when std needed it and only def and functions honoured the mark). A module's own deftests see its private items; tests in tests/ see only the public API (D016). In the REPL, privacy holds as in any module; (in-module geom) switches the REPL into geom, where its private items are visible as to its own code, and the prompt shows it (geom=>). The debugger's in-frame evaluates in the frame's module, so it sees that module's private items (D017). Remote sessions get this only with the debug or redefine capability (D020). in-module is the final name.
Package-level visibility: exports in the manifest (accepted)
Definitions have two levels, private to their module (defn-, ^:private) or public. Whether a module is visible outside its package is decided in one place, the package manifest:
;; package.dias (D025)
#{:name "someone/geom"
:exports #["geom" "geom.shapes.*"]} ; everything else is internal to the package
- Without an
exportslist every module is public, as in Clojure, for scripts and small packages; an empty list is an error. - Patterns open a branch of modules in one line (
"geom.shapes.*"), as subpath patterns in JavaScript'spackage.json. - A public signature that exposes a type from an internal module is reported when the package is built, with a hint to export the module or re-export the type, as Rust's "private type in public interface".
- Re-export is an option of
use:(use geom.impl.bbox [Bbox] export: true)makesBboxavailable to the module's users asgeom.Bbox, so a public module can present items that live in internal ones (a facade, as Rust'spub use), with no new form. - Protocol implementations in internal modules apply everywhere: an implementation belongs to a type and a protocol, not to a module.
tests/sees only exported modules (D016); documentation and version-compatibility tools read the list.- The error names the cause, with the package's full name: "geom.impl.bbox is internal to the package someone/geom; it is not listed in exports".
The standard library lives under std
Every standard module has a path under std: std.math, std.random, std.json, std.cli, std.term, std.test, std.bench, std.ffi, std.unsafe, the runtime's std.rt.…; the prelude, used implicitly by every module, is std.core. User and package modules never clash with them: a file src/random.dias is the module random, and the standard one is std.random, as Rust's std:: and Ferron's std.; Python's flat names, where a local random.py shadows the standard module, are the case this avoids. No package may define modules under std.
(use std.random) ; then random.between, random.shuffle …
(use std.math [close?])
(std.math.close? a b) ; the full path works without use
Example
;; src/geom.dias — the module geom
(defprotocol Shape (area [s]) (perimeter [s]))
(defprotocol Land (area [l]) (owner [l]))
;; src/app.dias — the module app
(use geom as: g)
(use geom [Shape Land])
(use geom.Shape [area perimeter])
(g.Shape.area c) ; a full path through the alias always works
(Shape.area c) ; the protocol is imported
(area c) ; the method is imported explicitly
(Land.area plot) ; Land's area is not imported, so it goes through the protocol
Why
-
One rule for every level. In Rust,
geom::Shape::areais just a three-segment path. Clojure mixes two separators (clojure.stringinside module names,/before the item), and a protocol method (g/Shape/area) fits neither rule. -
/rather than.. Both work; the choice was weighed:/keeps the most frequent Clojure form,(alias/name …), matching the Clojure vocabulary (D009);- a module path and its file path are the same string;
- the dot stays free, so a habitual
p.xgets a clear error instead of another meaning (fields are read with(:x p), D010); .is more familiar to people coming from Python, Go, and JS, and that was the main argument for it;- the cost of
/is a special case for division, as in Clojure.
(This choice was reversed by D029: the dot for paths and members.)
-
Explicit imports. Conflicts can arise only on a
useline, never at a distant call site, and reading a file tells where every name comes from. -
useas a top-level form works the same in files and in the REPL, unlike Clojure'snswith:require,:refer, and:renamepacked into one construct. -
A module is a file, as in Rust, Go, and Python: the name is not written twice, and tools map modules to files directly.
Rejected alternatives
.as the separator (geom.Shape.area): viable and more familiar outside Lisps; rejected for the reasons above. (Accepted later, D029.)::as in Rust: collides with keywords (:x) and with Clojure's::kw.:as in Common Lisp (geom:area): collides with keywords.- Two separators, as in Clojure (
.in module names,/before the item). - Clojure's
nsform with:require,:refer,:rename: one overloaded construct. - Short names of protocol methods appearing implicitly when unambiguous: conflicts would surface at call sites.
- Import of everything: possible later, for example for preludes.
Open questions
- How the first segment of a path resolves: names in the current module and aliases first, then top-level modules, or explicit prefixes like Rust's
self,super, andcrate. - The source root and package names, decided with the package system.