Import organization

A project is a set of files, and each file starts by saying which other files it needs. These rules keep that part tidy, so a reader can see at a glance what a file depends on and find anything in it.

By the end of this page you will

Name files so the import line matches.
Group and sort the import lines at the top of a file.
Know which modules never need an import.
Put a file's declarations in the order readers expect.

TSG-301 Files are named in snake_case

RequiredNo tool checks this yet

A file’s name becomes its module’s name: src/route_plan.tr is imported as import route_plan;. Name files the way you name modules, in lower case with _ between words, so the import line and the file name are spelled the same.

my_project/

src/your code
main.trthe entry point: what turf run runs
route_plan.trimported as import route_plan;
price_table.trimported as import price_table;
tests/the tests turf test runs
route_plan_test.trtests for route_plan

TSG-302 Imports go at the top, in groups

RecommendedNo tool checks this yet

All import lines come first in the file, before any declaration, one module per line. Group them in this order, with a blank line between groups, and sort each group alphabetically:

modules from the standard library,
modules from other packages your project depends on,
modules from your own project.

tsg_302.tr

import list::List;import map::Map;fn main(): int {    mut names: List<string> = List::default();    mut ages: Map<string, int> = Map::default();    names.push("Mira");    ages.put("Mira", 34);    printline(names.length());    return 0;}

Don't

tsg_302_avoid.tr

import map::Map;fn main(): int {    mut names: List<string> = List::default();    mut ages: Map<string, int> = Map::default();    names.push("Mira");    ages.put("Mira", 34);    printline(names.length());    return 0;}import list::List;

TSG-303 Do not import the prelude

RecommendedNo tool checks this yet

Nine modules are already loaded into every file: io, math, sys, int, double, bool, char, strings and array (the prelude). Do not import them, and call the io, math and sys functions by their bare names: printline, abs, max, panic. Write the qualified form, such as math::max, only when one of your own functions has the same name.

tsg_303.tr

fn main(): int {    printline(abs(-5));    printline("turf".length());    return 0;}

Don't

tsg_303_avoid.tr

import io;import math;import strings;fn main(): int {    io::printline(math::abs(-5));    io::printline(strings::length("turf"));    return 0;}

TSG-304 Put things in a file in a fixed order

RecommendedNo tool checks this yet

Inside a file, put things in this order, so that a reader always knows where to look:

imports,
constants (export immut),
types: struct, enum, error and machine, each followed straight away by its own methods,
other functions,
main, last.

tsg_304.tr

export immut START: int = 10;struct Counter {    n: int,}fn Counter.bump(): void {    self.n++;}fn make_counter(): Counter {    mut c: Counter = Counter::default();    c.n = START;    return c;}fn main(): int {    mut c: Counter = make_counter();    c.bump();    printline(c.n);    return 0;}

Don't

tsg_304_avoid.tr

fn Counter.bump(): void {    self.n++;}fn main(): int {    mut c: Counter = make_counter();    c.bump();    printline(c.n);    return 0;}struct Counter {    n: int,}export immut START: int = 10;fn make_counter(): Counter {    mut c: Counter = Counter::default();    c.n = START;    return c;}