Modules and packages

use and every form after from, public at the top of a file, the prelude, packages and workspaces, what top-level code may do, and why an import cycle is not an error.

What belongs here#

What does not belong here: the members of a type or a trait, whose own visibility is in language/types/ and language/traits/. Every page in this folder is a reference page: an example first, then the syntax, then numbered rules, then what the construct is not.

Pages#

• use - use brings names into scope from a package or a file. Everything after from names a module; a path brings in a case of a type or a member another package attaches to it, and a use without names is an error.
• Visibility - A top-level declaration is private to its file unless marked public, and a public declaration may not expose a type that is private to its own file.
• Deprecation - A deprecated clause above a declaration or a member keeps it working for its callers, warns at every use outside its file, and names the replacement that torb lint --fix writes.
• The prelude - The prelude is the package whose public names are in scope in every file without an import, and it holds only the pure part of the standard library.
• Packages - A package is a directory with a project.trb, named owner/name, whose file names say what it produces - src/lib.trb, src/main.trb, *.test.trb - and it can only be reached by a project that lists it as a dependency.
• Workspaces - A workspace is one root project.trb naming several member projects that check, build and test as a group, and resolve their dependencies into one shared project.lock.trb.
• Top-level code - A statement outside every declaration is only allowed in an entry file, a script or a test file, and a top-level const of a module has to be known at compile time.
• Cyclic imports - Two modules may import each other, because nothing runs when a module is imported and its exports are computed to a fixpoint, but the same cycle between top-level statements is an error.