Modules and imports
Module declarations, import forms, workspace crates and the filesystem resolution order.
Every .pkl file is a module. A module declaration names it, and import
brings other modules into scope.
Declaring a module
module my.app.util
The name is conventional, not enforced. A file declaring module my.app.util
compiles and runs exactly like one declaring module anything. The one thing
that matters is where the file lives, because that determines what its imports
resolve to. A module without a module declaration is valid.
Importing
The form is import with braces around the names you want, and from before
the path:
import { divmod } from util
import { json } from std.json
Because from is a keyword, it cannot be used as an identifier, see
Variables and constants.
An import is a declaration, so it goes at the top of the file with the other declarations, and a name must be imported before it is used.
What an import path means
The first segment of the path decides how the rest is resolved.
1. A workspace member name
If the first segment matches a name in the [workspace] members list of
picklescript.toml, resolution happens only inside that member's directory.
A crate name is authoritative and never falls back to the filesystem.
With the shipped manifest, std points at stdlib/, so:
import { json } from std.json
resolves to stdlib/json.pkl. A single-segment import of a crate name maps to
lib.pkl or main.pkl in that crate's directory.
This is also why the standard library is importable from any file inside the
repository but not from an unrelated directory: there is no picklescript.toml
to declare the std member.
2. A filesystem path
Otherwise the loader searches the filesystem. It tries these bases in order:
- The directory of the importing file.
- Each ancestor of that directory, up to and including the process working directory.
<cwd>/src/.
At each base it tries, in order:
- A module file, the remaining segments joined with
/and given a.pklextension. - A package directory, the segments joined with
/and given a/.
A failed lookup reports:
error[E0206] cannot find module `std.collections.stack`
= note: searched up the importing file's directory tree, then `<cwd>/src/`
A worked example
project/
main.pkl
helper.pkl
geo/
point.pkl
main.pkl:
import { greet } from helper
import { Point } from geo.point
fn main() {
println(greet("ada"))
println(Point(1, 2).x)
}
helper.pkl:
fn greet(name: string) -> string {
return "hello, {name}"
}
geo/point.pkl:
struct Point {
var x: int
var y: int
constructor(x: int, y: int) {
this.x = x
this.y = y
}
}
helper resolves against the directory of main.pkl; geo/point resolves
against the same directory as a path. Both are in the importing file's own
directory, so the program is independent of the working directory.
Import order
Imports are declarations, so a module that depends on another must be imported below that dependency's own imports. Import everything you need at the top of the file.
Exporting
There is no export keyword and no pub. Every top-level declaration in a
module is importable. Importing a name that does not exist is an
undeclared-name error.
Next steps
- The workspace manifest: declaring workspace members.
- Collections in the standard library
