Modules and imports

Module declarations, import forms, workspace crates and the filesystem resolution order.

vlatest

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:

  1. The directory of the importing file.
  2. Each ancestor of that directory, up to and including the process working directory.
  3. <cwd>/src/.

At each base it tries, in order:

  1. A module file, the remaining segments joined with / and given a .pkl extension.
  2. 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