Modules and imports.

Syntax#

ImportDecl  = 'pub'? 'import' ModulePath ('as' Identifier)? MemberList?
ModulePath  = Segment ('.' Segment)*
MemberList  = '{' Member (',' Member)* ','? '}'
Member      = Identifier ('as' Identifier)?

• pub import requires a member list.

• Imports are module-level declarations. They may also sit inside a top-level static if, as std lib modules do.

Files are modules#

• The module name is the file's path below [package].source, without .silk, with / written as .. src/geometry/Point.silk is geometry.Point when the source root is src.

• The source root defaults to src. See The manifest.

• Names match file names exactly, case included. import geometry.point does not find Point.silk.

• A directory is a module only through its barrel file mod.silk. import geometry finds src/geometry.silk or src/geometry/mod.silk, and fails when only geometry/ exists. See Barrel modules.

• There is no module declaration inside the file.

• A module named tests and a directory tests/ can sit side by side: tests is src/tests.silk, tests.Fakes is src/tests/Fakes.silk.

Import forms#

• A module binding gives qualified access: Point.normSquared(&p).

• Members are types, functions, constants, interfaces and services the module declares or re-exports.

• A module path whose last segment is a keyword, such as silk.match, needs as or a member list (PAR0004).

• Std lib modules start with silk.. A dependency's modules start with the dependency name: import pricing.lib { discounted }. See The standard library and Dependencies.

Re-exports#

pub import makes the imported names part of the importing module's public surface.

pub import geometry.Point { Point, normSquared as norm2 }

Another module can then write import geometry.Shapes { Point, norm2 }, or call S.norm2(...) through a module binding.

Barrel modules#

A directory's mod.silk is the module named by the directory's path, like mod.rs in Rust. It usually re-exports what the directory's other modules declare, so an importer names one module:

src/
  main.silk
  shapes/
    mod.silk
    circle.silk
    square.silk

src/shapes/mod.silk:

pub import shapes.circle { Circle }
pub import shapes.square { Square, area }

src/main.silk:

import shapes { Circle, Square, area }

• import shapes reads src/shapes.silk or src/shapes/mod.silk, whichever exists. Both existing is MOD0005.

• A barrel is named only by its directory: import shapes.mod is MOD0006.

• Imports inside mod.silk still start at the source root: shapes.circle, not circle.

• The children stay importable on their own: import shapes.circle { Circle } still works.

• import shapes inside shapes/mod.silk imports itself (MOD0002).

• The same rule holds for a dependency's modules and for exports: exports = ["shapes"] publishes the barrel. Its children stay internal unless listed too.

• src/mod.silk at the top of the source root is an ordinary module that no import can name.

Visibility#

• Without pub, a declaration is visible only inside its own module. The boundary is the module, not the package.

• pub applies separately to the type, to each field, to each method, and to the fields of each union variant.

• A struct whose fields are not all visible cannot be built with a literal outside its module (SEM0021). Reading a private field is SEM0028.

• A pub declaration may not mention a private type in its signature (SEM0019).

• Impls take no pub. An impl is usable wherever its type is visible.

• Across packages, the module must also be listed in the dependency's exports (MOD0003). See Libraries and exports.

Cycles and reachability#

• Modules of one package may import each other in a cycle. A importing B while B imports A is fine.

• In a program, check, build and test see the root module and every module reachable from it by imports. A file nothing imports is not checked. A library also covers every module in exports.

• A module may import the root module: import main { execute }.

Example#

src/
  main.silk
  geometry/
    Point.silk
    Shapes.silk

src/geometry/Point.silk:

/// A point on the plane.
pub struct Point {
  pub x: i32,
  pub y: i32,
}

/// The squared distance from the origin.
pub fn normSquared(point: &Point) -> i32 {
  return point.x * point.x + point.y * point.y
}

fn secret() -> i32 {
  return 42
}

src/geometry/Shapes.silk:

pub import geometry.Point { Point, normSquared as norm2 }

/// A rectangle given by two corners.
pub struct Rect {
  pub low: Point,
  pub high: Point,
}

pub fn area(rect: &Rect) -> i32 {
  return (rect.high.x - rect.low.x) * (rect.high.y - rect.low.y)
}

src/main.silk:

import geometry.Point
import geometry.Shapes as S { Rect, area }

pub fn main() -> i32 {
  let corner = Point.Point { x: 3, y: 4 }
  let rect = Rect { low: Point.Point { x: 0, y: 0 }, high: move corner }
  if Point.normSquared(&rect.high) != 25 {
    return 1
  }
  if S.norm2(&rect.high) != 25 {
    return 2
  }
  return area(&rect)
}

silk run; echo "exit $?"

exit 12

Adding an import of the private secret to src/main.silk:

import geometry.Point { secret }

Checking shapes (x86_64-unknown-linux-gnu)
  load     139 modules, 3 in package         0.03s
  check    failed: 4 modules, 1 error        0.06s
[x86_64-unknown-linux-gnu]
src/main.silk:1:25: error[SEM0015] `secret` is private to geometry.Point; mark it `pub` there to use it here
Failed shapes in 0.11s

Diagnostics#

See also#

The manifest, The standard library, Dependencies, Libraries and exports; Structs, tuples and arrays, Enums and unions and Package parameters in the reference (parameters may only be declared in the root module); chapter 12 of the book.