Skip to the content
Diaspar

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) gives Shape.
  • (use path as: name) makes it available under another name (labels, D030).
  • (use path [item …]) makes several items under path available. 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 exports list 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's package.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) makes Bbox available to the module's users as geom.Bbox, so a public module can present items that live in internal ones (a facade, as Rust's pub 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::area is just a three-segment path. Clojure mixes two separators (clojure.string inside 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.x gets 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 use line, never at a distant call site, and reading a file tells where every name comes from.

  • use as a top-level form works the same in files and in the REPL, unlike Clojure's ns with :require, :refer, and :rename packed 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 ns form 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, and crate.
  • The source root and package names, decided with the package system.