Modules

Do modules are named namespaces of values. A module can export functions, classes, constants, and other public bindings.

A module cannot use return to exit its top level or replace its namespace with another value. Functions and methods declared in a module may return normally.

Importing Modules

Whole-Module Imports

Import a module by name:

import math
math.add 1 2

Module names may be dotted:

import build.tools
build.tools.compile sources

When a dotted module name is imported without renaming, the local binding is the first component. That binding is a namespace object whose nested fields mirror the rest of the dotted name.

import build.tools
import build.images

build.tools.compile sources
build.images.pack rootfs

Conceptually, import build.tools binds a local build object, then inserts the imported module at build.tools. A later import build.images extends the same local build namespace instead of replacing it.

Renaming

Use module: alias to bind the imported module directly under a different local name:

import math: m
m.add 1 2

This also works with dotted module names:

import build.tools: tools
tools.compile sources

Unlike import build.tools, this binds tools directly to the imported module. It does not create a local build namespace object.

Importing Specific Items

Import selected public items from a module:

import math:
  - add
  - subtract

add 1 2

Renaming Imported Items

Rename individual imported items:

import math:
  add: plus

plus 1 2

The left-hand side is the exported name in the module; the right-hand side is the local binding.

Combined Forms

import math:
  add subtract
  subtract: minus

Plain item names can share a continuation line. The - form keeps an item on its own line; renamed items use one line each. An item written @Item, - @Item, or @Item: name is named only in types, and is not imported.

The vertical form is useful when importing multiple modules at once:

import
  build.tools math
  build.images: images
  build.deploy:
    - push
    status: deploy_status

Plain module names, including checker-only imports such as @math, may share a vertical continuation line. Renamed imports and imports with item lists use one vertical continuation line each. The first import line may contain multiple renamed imports.

Exporting with pub

Mark definitions as public with pub:

pub def helper x
  (x + 1)

pub let VERSION = "1.0"

# Private (not exported)
def internal_detail()
  42

Only pub items are visible when a module is imported.

Imports can re-export their bindings:

pub import math

pub import build.tools: tools

pub import errors:
  - BuildError
  ParseError: SyntaxError

A public dotted module import must be renamed. An unrenamed pub import build.tools creates a namespace object and is rejected. Rename it instead:

pub import build.tools: tools

Module Resolution

Modules are resolved according to the host application. See the Shell Guide for details on module path configuration for dolang.