18. Modules, projects and dependencies
Every program in the first seventeen chapters fits in one file. Real programs grow past that, and they use code other people wrote. This chapter covers three things:
- Modules: split code across
.sprfiles that import each other; - Projects: pin one entry point, a set of sources and a dependency list in
sprig.toml; - Dependencies: use Sprig packages that live in a local directory, a Git repository or a package registry.
In this chapter you will learn:
- one
.sprfile is one module; afterimport "./math_module.spr" as math, you reach its top-level functions, classes andletbindings asmath.name; - a module's top-level statements run once, the first time it is imported, and two modules that import each other are rejected by the compiler;
exportturns a module into a facade that re-exports only the names you choose;- a project is
sprig.toml+src/+tests/+ a committedsprig.lock; without a resolved lock,sprig runrefuses to run; sprig adddeclares a dependency,@alias/module.sprimports it, and only the modules in the dependency'sexportscan be imported.
18.1 One file is one module
Two things get mixed together in a program: helper functions (area, formatting, parsing) and the main flow that uses them. Keep the helpers in their own file and the main file stays short enough to read at a glance, while the helpers can be reused by another program. That unit — one file — is a module.
The smallest example: one module and one program that uses it. Both files go in the same directory.
math_module.spr:
# A plain module: one function and one top-level let binding.
func square(x: Int) -> Int:
return x * x
let pi_approx: Float = 3.14159main.spr:
# Import a module in the same directory; reach its top-level names through the alias.
import "./math_module.spr" as math
print(math.square(7))
print(math.pi_approx)49
3.14159Line by line:
import "./math_module.spr" as mathimportsmath_module.sprfrom the same directory and gives it the local aliasmath. A path starting with./means "relative to this file".print(math.square(7))reaches a function in the module through the alias, a dot and the name.square(7)returns49.print(math.pi_approx)reads a top-levelletbinding the same way. Themath.part is required; writingpi_approxalone is not something the compiler knows.- The other two lines,
49and3.14159, are simply the return value and the binding printed out.
A module has no private: every top-level function, class and let binding in an imported file is visible. To hide something, put it in another file that nobody imports.
Top-level statements run once
A module's top-level statements run the first time it is imported. If two modules depend on the same module, it still initializes only once. Three files:
d.spr:
# A base module imported by two other modules.
print("d initialized")b.spr:
# This module imports d, then prints its own line.
import "./d.spr" as d
print("b done")main.spr:
# The main module imports d directly and also gets it through b.
import "./b.spr" as b
import "./d.spr" as d
print("main done")d initialized
b done
main donemain.spr imports d directly and also gets it through b. The compiler handles b first; the first import of d runs the top-level statements of d.spr, printing d initialized, and then b.spr prints its own b done. Back in main.spr, importing d again does nothing because the module is already initialized, and the last line is main done. This rule guarantees that module setup code, such as reading a configuration file once, does not repeat.
Import cycles are rejected
If main.spr imports other.spr and other.spr imports main.spr, there is no sensible order in which to initialize them. The compiler does not guess; it reports an error:
other.spr:
import "./main.spr" as main
func beta() -> Int:
return 2main.spr:
import "./other.spr" as other
func alpha() -> Int:
return 1SPR-NAME-IMPORT-CYCLE [NAME] main.spr: Circular module import: main.spr -> other.spr -> main.sprRead the line: SPR-NAME-IMPORT-CYCLE is the error code, main.spr says where the problem is reported, and after the colon main.spr -> other.spr -> main.spr draws the import chain that loops back on itself. The fix is to break the cycle, usually by moving the code both files need into a third module.
Deliberate mistake: forgetting the alias
Importing under an alias and then using the bare name is the most common beginner error:
# The import has the alias math, but the call does not go through it.
import "./math_module.spr" as math
print(square(7))SPR-NAME-UNRESOLVED [NAME] main.spr:4:7: Unresolved name 'square'SPR-NAME-UNRESOLVED means "I cannot find this name". main.spr:4:7 points at line 4, column 7, the start of square. The compiler will not guess that you meant math.square; change square(7) to math.square(7) and it compiles.
Coming from another language?
- Python's
from math import squarecopies a name into the current file; Sprig has no such form, onlyimport ... as ..., and the alias is never optional. There is noimport *either. - Java ties package names to directory structure; a Sprig module is the file itself, the import path is relative, and you choose the alias.
18.2 export: a facade for others
A module may have many top-level names but only a few meant for outsiders. Sprig does not hide the rest; instead you write a facade module that re-exports just the names you want to publish. Everyone else imports the facade and sees only those names.
math_module.spr:
# A plain module: one function and one top-level let binding.
func square(x: Int) -> Int:
return x * xfacade.spr:
# A facade module: it re-exports another module's name.
import "./math_module.spr" as math
export math.squaremain.spr:
# Import the facade and use it like any other module.
import "./facade.spr" as facade
print(facade.square(5))25facade.sprfirst importsmath_module.sprnormally, thenexport math.squarere-exports the importedsquare.facade.spris now a module that providessquare.main.sprneither knows nor cares wheresquarecomes from; it deals only withfacade.- A re-exported name keeps the identity of the original declaration, so the facade does not copy the function, it adds an outward entry point.
importcomes first, thenexport, then ordinary declarations. Eachexportnames one symbol and there is no wildcard.
Deliberate mistake: a name the facade did not re-export
The facade re-exports square, but the caller wants pi_approx:
# The facade re-exports only square, so pi_approx is not visible.
import "./facade.spr" as facade
print(facade.pi_approx)SPR-NAME-UNRESOLVED [NAME] limited.spr:4:7: Module 'facade' has no member 'pi_approx'This time SPR-NAME-UNRESOLVED adds Module 'facade' has no member 'pi_approx': the name is fine, the facade module just does not have it. Either add export math.pi_approx to the facade or import math_module.spr directly.
Coming from another language?
Java's public modifier opens a window on a member; Sprig is the other way round: everything is public by default, and you narrow the surface with an extra facade file that lists the usable names. That resembles a package's __init__.py or a barrel index.js re-exporting submodules.
18.3 Projects: sprig.toml
A directory holding a set of modules, one entry point and a dependency list is a Sprig project. sprig init starts one:
$ sprig init
Created /private/tmp/sprig-book/my-tool/sprig.toml
Created /private/tmp/sprig-book/my-tool/src/main.spr
Run `sprig resolve` to create sprig.lock.(The paths in the output are absolute paths of the working directory; yours will differ.) The layout is:
my-tool/
├── sprig.toml # project configuration
├── sprig.lock # the lockfile sprig resolve writes
└── src/
└── main.spr # the program entry pointsprig.toml:
[project]
name = "my-tool"
version = "0.1.0"
language = "0.8"The generated src/main.spr:
# my-tool entry point.
func main() -> Unit:
print("Hello, Sprig!")
main()Commands run inside a project walk upward to the nearest sprig.toml and default to src/main.spr as the entry. Resolve the dependencies, then run:
$ sprig resolve
Resolved 0 Sprig dependency entries and 0 Maven artifacts/models into /private/tmp/sprig-book/my-tool/sprig.lock
$ sprig run
Hello, Sprig!sprig resolve writes sprig.lock, which pins every dependency to an exact version or commit. Three habits to remember:
- Commit
sprig.lock. Anyone with the same lock gets exactly the build you got; - Only
resolve,addandremovewrite it.check,runandbuildonly read it; - When the manifest and the lock disagree, commands refuse to run. Run
sprig resolveagain after editingsprig.toml.
Deliberate mistake: running before resolve
Right after init, before any resolve:
$ sprig run
SPR-PROJECT-LOCK-MISSING [CLI] Project 'my-tool' has no sprig.lock
hint: Run `sprig resolve`.SPR-PROJECT-LOCK-MISSING says the project has no lockfile, and the hint gives the next step. After a manual manifest edit with a lock that no longer matches, you get the related SPR-PROJECT-LOCK-STALE:
$ sprig run
SPR-PROJECT-LOCK-STALE [CLI] sprig.toml and sprig.lock do not match
hint: Run `sprig resolve`.One project, several entry points
A project can have more than one executable entry, declared with [[bin]]:
[project]
name = "tools"
version = "0.1.0"
language = "0.8"
[[bin]]
name = "hello"
entry = "src/hello.spr"
[[bin]]
name = "bye"
entry = "src/bye.spr"With several [[bin]] tables, sprig run must pick one with --bin name:
$ sprig run
SPR-PROJECT-ENTRY [CLI] sprig.toml: Multiple binaries require --bin or an explicit [project] entry
hint: Name one: --bin hello, --bin bye. sprig check with no file checks every bin.
$ sprig run --bin hello
hellosprig project prints the project's information and sprig project --json gives it to scripts or editors. The manifest accepts few keys: name, version, language, source (default src), entry (default <source>/main.spr), plus [[bin]], the [[dependency]], [[jvm]] and [[registry]] tables below. A misspelled key is rejected.
18.4 Dependencies
To use modules from another project, declare a dependency first. Say a colleague keeps math helpers in ../math:
$ sprig add math --path ../math
Added sprig-path dependency math and updated /private/tmp/sprig-book/dep/consumer/sprig.locksprig add edits sprig.toml and updates sprig.lock right away. The manifest gains:
[[dependency]]
name = "math"
path = "../math"Then the source imports through @ and the dependency name:
import "@math/vector.spr" as vector$ sprig run
25The dependency decides which of its modules can be imported through its own sprig.toml:
[project]
name = "math"
version = "0.1.0"
language = "0.8"
exports = ["vector.spr"]Only the modules listed in exports can be imported. If your colleague adds a hidden.spr without listing it, importing it gives:
SPR-PROJECT-NOT-EXPORTED [NAME] main.spr:1:1: Dependency 'math' does not export 'hidden.spr'
hint: Only modules listed in the dependency's [project] exports are importable.@std/... is the one exception: standard-library modules come with the compiler installation, need no dependency declaration and are not written into the lockfile.
Besides a local directory, sprig add understands Git and Maven sources:
sprig add math --path ../math # a local directory
sprig add format --git https://example.com/format.git --tag v1.0 # a Git repository
sprig add --jvm org.apache.commons:commons-text:1.12.0 # a Java library from MavenA Git dependency can point at a version with --branch, --tag or --rev, and resolve pins the result to an exact commit. Maven coordinates are for Java libraries and are covered in chapter 21. check, run, resolve, add, remove and test all accept --offline: verified caches only, and a missing piece reports SPR-DEP-OFFLINE instead of fetching silently.
Finding packages in a registry
When you cannot remember a package's Git URL, ask the registry:
$ sprig search json
json-codec 0.7.1-beta.1 https://github.com/ColinHouse/Sprig.git libraries/sprig-json-codec Apache-2.0
Path-aware JSON decoding and encoding over @std/json
1 package(s) in 1 registry(ies); add one with: sprig add NAME [--version V]sprig add json-codec looks it up and writes an ordinary Git dependency into your manifest; check and run never consult the registry again. A registry is only an index with no central server: the default index is the registry/ directory of the Sprig repository, and a team registers its own with [[registry]]. Publishing means committing an entry to that index; sprig publish --registry DIR --tag v1.0.0 writes the current package into it (the default registry also requires --license and --owner), and the command then tells you to open the pull request.
Summary
- One
.sprfile is one module.import "./x.spr" as x, then usex.name; top-level names are visible by default. - A module initializes once; importing in a cycle is
SPR-NAME-IMPORT-CYCLE. export x.namebuilds a facade; a name the facade did not re-export gives the callerSPR-NAME-UNRESOLVED.- A project is
sprig.toml+src/+tests/;sprig resolvewrites the lockfile, which is committed;check/run/buildreject a missing or stale lock. sprig adddeclares a dependency and@alias/module.sprimports it; only the dependency'sexportsare importable;--offlineuses caches only.@std/ships with the compiler; it is not a dependency.
Exercises
Exercise 1: pull out a first module
Split this program into two files: double.spr holding the function double, and main.spr importing it and printing double(21).
func double(x: Int) -> Int:
return x * 2
print(double(21))Hint: after the import, double is reached through the alias.
Answer
double.spr:
# The module for exercise 1.
func double(x: Int) -> Int:
return x * 2main.spr:
# The entry point for exercise 1.
import "./double.spr" as double
print(double.double(21))42Exercise 2: add a facade
Starting from exercise 1, add facade.spr that imports double.spr and re-exports only double; make main.spr import from the facade.
Hint: export alias.name.
Answer
double.spr:
# The module for exercise 2.
func double(x: Int) -> Int:
return x * 2facade.spr:
# The facade for exercise 2.
import "./double.spr" as source
export source.doublemain.spr:
# The entry point for exercise 2.
import "./facade.spr" as facade
print(facade.double(4))8Exercise 3: how many times does it print?
When one module is imported twice under two aliases, how many times do its top-level statements run? Guess first, then run the two files in the answer.
Hint: recall "run once" from 18.1.
Answer
base.spr:
# The base module for exercise 3: it can only initialize once.
print("base initialized")main.spr:
# Exercise 3: import the same module twice, under two aliases.
import "./base.spr" as first
import "./base.spr" as second
print("main done")base initialized
main doneThe top-level statements of base.spr run once, even though main.spr imports it under both first and second. The second import only adds another alias; it does not re-initialize the module.
Next chapter: Testing.
