Skip to main content

Modules

Every file is a module​

In Bolt, each file is a module. There's nothing to declare: a file's top-level items are its contents, and other files use them by importing the file.

Here's a file with some geometry:

geometry.bolt
pub struct Point { pub x: i32, pub y: i32 }

pub fn origin() -> Point = Point { x: 0, y: 0 };

pub fn manhattan(a: Point, b: Point) -> i32 = abs(a.x - b.x) + abs(a.y - b.y);

fn abs(n: i32) -> i32 = if n < 0 { -n } else { n };

and a file next to it that uses it:

main.bolt
import "./geometry" (Point, origin, manhattan);

manhattan(origin(), Point { x: 3, y: -4 });
bolt run main.bolt
7

Visibility​

Items are private by default: only their own file can use them. pub makes an item usable from other files. In geometry.bolt, abs is private, so main.bolt can't import it:

[E0104] Error: `abs` is private

pub(package) is in between: the item can be used by the files of the same package, but not by other packages.

The fields of a struct are private in the same way, even when the struct is pub. That's why Point's fields are pub: main.bolt builds a Point with them. Outside its file, a private field can't be read or changed, given in Point { … } or to a tuple struct like Meters(3), copied with .., or matched by a pattern. A pattern can still leave it to .., as in Point { x, .. }. This lets a type keep its fields to itself, so that only its own functions make and change its values:

pub struct Celsius(f64);

pub fn Celsius.new(degrees: f64) -> Celsius =
Celsius(if degrees < -273.15 { -273.15 } else { degrees });

Other files make one with Celsius.new(20.0), and Celsius(-500.0) is an error there:

[E0118] Error: the field `Celsius.0` is private to the file of its struct; make it `pub` to use it here

The fields of an enum's variants are always as visible as the enum.

Kinds of imports​

The path of an import is a string. A path starting with ./ or ../ is relative to the importing file, and .bolt is added to it, unless it ends with .bolt already: ./parser.v2 is the file parser.v2.bolt.

ImportBrings into scope
import "./geometry" (Point, origin);the names in the list
import "./geometry" (Point as P);Point, under the name P
import "./geometry" (==, -);the operators == and -; - is both fn -a and fn a - b
import "./geometry" as geo;the file, as geo: write geo.origin()
import "./geometry" *;every public name of the file
import "./geometry";nothing, but the file's impls become visible
import Shape.*;the variants of the enum Shape

With as, the file's names are used through the name you give it:

main.bolt
import "./geometry" as geo;

geo.manhattan(geo.origin(), geo.Point { x: 1, y: 1 });
2

An import can be public too. pub import "./geometry" *; makes the names of geometry.bolt available to the files that import this one.

Impls and imports​

Impls don't have names, so they aren't imported one by one. A file can use the impls of every file it imports, directly or through other imports, and those of the prelude.

Packages​

A path that doesn't start with ./ or ../ names a package. A package is a directory with a bolt.toml, which gives its name and the packages it uses:

my-project/bolt.toml
[package]
name = "my-project"

[dependencies]
shapes = { path = "../shapes" }
my-project/
├── bolt.toml
└── main.bolt
shapes/
├── bolt.toml
├── lib.bolt
└── circle.bolt

A file is in the package of the nearest bolt.toml, in its directory or one of its parents. In main.bolt, import "shapes"; imports lib.bolt of the dependency shapes, and import "shapes/circle"; imports circle.bolt. A package can only use its own dependencies: shapes has a bolt.toml of its own, which lists what it uses.

std isn't a dependency: it comes with the compiler, and every file can use it. A file without a bolt.toml above it can only use std, and other files by their path.

The prelude​

Every file gets the names of the prelude of the std package without importing them. The prelude is std's __prelude__/lib.bolt, which bolt --version shows where to find. It includes:

  • print and panic;
  • Option, with Some and None;
  • List, with cons, head and tail;
  • the classes Semigroup, Monoid and Functor.

The names of the prelude can be shadowed: a file that defines its own Option uses that one. Functions are different: a function with the name of one of the prelude is one more function with that name, so it must take other arguments (see Functions with the same name).

A package can choose another prelude in its bolt.toml: prelude = false for none, or the name of a dependency, whose prelude is used. A package's prelude is its __prelude__.bolt, or its __prelude__/lib.bolt for one of several files, which can import each other. To check a file without the prelude, use bolt check --no-prelude.

What's next​

That's the end of the tutorial! From here you can:

  • read the language internals to see how the type checker works;
  • read the standard library in packages/std;
  • look at the issues on GitHub for what's coming, and what you could help with.