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:
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:
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.
| Import | Brings 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:
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:
[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:
printandpanic;Option, withSomeandNone;List, withcons,headandtail;- the classes
Semigroup,MonoidandFunctor.
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.