Modules¶
A program is an entry file plus every module it uses, directly or through other modules. The Modules tutorial walks through an example.
Names and files¶
The root is the directory of the entry file, the file given to stone run, stone build, or
stone check. Every other .stn file under the root is a module, named by its path from the root
with . between the parts and without .stn:
file |
module |
|---|---|
|
none; it cannot be used |
|
|
|
|
|
|
A directory is only part of a module’s name, never a module itself, so there are no files that
only declare or re-export others. A module and a directory can share a name, as geometry.stn and
geometry/ do above. File and directory names must be valid stone names to be used.
use¶
use geometry.shapes
use geometry.shapes.area
use geometry.shapes.area as shape_area
use takes a dotted path from the root and binds one name in the file:
If the path names a module file,
usebinds the module by its last name, and its functions are called asshapes.area(r). A module is not a value, sox = shapesis an error.Otherwise, if everything before the last name is a module,
usebinds that module’s function by its own name, and it is called asarea(r).If that module defines an enum by the last name,
usebinds the enum, as inuse geometry.shapes.Shape, and its values are writtenShape.Circle(1.0). Through the module, they areshapes.Shape.Circle(1.0), and its type isshapes.Shape.If that module defines a struct by the last name,
usebinds the struct, as inuse geometry.shapes.Point, and its values are writtenPoint(x=1.0, y=2.0). Through the module, they areshapes.Point(x=1.0, y=2.0), and its type isshapes.Point.If that module defines a trait by the last name,
usebinds the trait, as inuse geometry.shapes.Shape, for bounds ([T: Shape]) andimpl Shape for Circle:blocks. Through the module, it isshapes.Shape.asbinds the name after it instead.
So when both geometry/shapes.stn and a function shapes in geometry.stn exist,
use geometry.shapes is the module. Use use geometry and call geometry.shapes() to reach the
function.
The rules for use:
rule |
error |
|---|---|
the path must name a module or a function in one |
|
a directory alone cannot be used |
|
the function must exist |
|
the function must be |
|
the entry file cannot be used |
|
each name is bound once per file |
|
a name cannot be both used and defined in a file |
|
a builtin’s name cannot be bound |
|
|
|
|
|
A function’s parameters and locals may shadow a name bound by use, just as they shadow
functions.
Builtin modules¶
os, math, random, time, fs, net, gui, and json are builtin modules, so
use math, use math.sqrt, and use math as m work in any file without a math.stn. The first
five have no file, and net, gui, and json are written in stone and linked with a program
that uses them. A program cannot have
a module of its own with one of those names: using it is the error
'math' is a builtin module, so rename math.stn. prelude is taken too, since the functions of
stone’s prelude are linked as if in a module of that name. See the builtins for
their functions:
module |
for |
|---|---|
the machine and process a program runs on |
|
absolute values, least and greatest, square roots, rounding down, trigonometry, and the constants |
|
pseudo-random numbers, the same in every backend after a seed |
|
the time of day, timing code, and sleeping |
|
reading and writing files and directories |
|
TCP and Unix-socket connections, and finding hosts’ addresses |
|
drawing pictures and showing them in windows |
|
reading and writing JSON text |
A builtin module’s functions are only reachable through it, so a program can still name its
own variables and functions min, max, sleep, or env.
pub¶
pub fn makes a function usable from other files, pub const a constant, pub enum an enum,
pub struct a struct, and pub trait a trait. Every other function, constant, enum, struct, and
trait is private to the file it is in. A constant is used as a function is: use limits and then
limits.most, or use limits.most and then most. pub makes no difference in the entry file, so a
module can also be run on its own.
A struct’s impl blocks are in the file that defines the struct, and its methods and associated
functions need no pub: they can be used wherever the struct can, as p.area() and
shapes.Square.unit() or, after use shapes.Square, Square.unit(). An impl block for a
struct of another file is an error, except one that implements a trait for it in the trait’s
file: impl Shape for Square: goes in the file of Shape or of Square, and one implementing a
trait for int, float, bool, or str in the trait’s.
Module bodies¶
A module other than the entry file holds only use statements, fns, consts, enums,
structs, impl blocks, and traits.
Any other top-level statement is an error: only use, fn, const, enum, struct, impl, and trait are allowed at the top level of a module. A constant’s value is worked out when the program is
built, so using a module never runs code, and modules may use each other in a cycle.
A module’s functions see their parameters and locals, their own file’s functions, builtins, and
the names their file binds with use. They never see the entry file’s variables or functions:
reading one is undefined name or undefined function, as for any unknown name.
Packages¶
A program whose entry file has a stone.toml beside it can use packages, other directories of
modules that it names under [dependencies] (see Using packages and
stone.toml). A path that starts with a dependency’s name is in that package: use geo loads
the package’s lib.stn, use geo.shapes its shapes.stn, and use geo.area the pub fn area
of its lib.stn. A dependency cannot share its name with a module or directory of the program.
A package’s files follow the same rules as any module, see only the package’s own modules and
dependencies, and name their own modules by their paths within the package.
Types¶
The checker checks the whole program at once, the same way it does within one file. A module’s
functions have the types their signatures write, so pub fn first(xs: list[str]) -> str: ret xs[0]
can be called from any file with a list[str], and a call with anything else is an error in the
calling file. Errors point at the file they are in, as in
app/geometry/shapes.stn:4:12: error: ....