use — Importing Modules

Syntax

use "path/to/module.npk".*;           // wildcard import (all pub symbols)
use "stdlib_file.npk".*;              // stdlib import (bare filename)
use "math.npk".{square, pi};          // selective import
use "utils.npk" as utils;             // namespace import

Path Resolution

• Relative paths: resolved relative to the importing source file
• Bare filenames: compiler searches the stdlib directory and configured search paths

Import Types

Wildcard Import (.*)

Imports all public (pub) declarations from the module directly into the current scope.

use "math.npk".*;
int32:val = square(5);

Selective Import (.{a, b})

Imports only the specified symbols from the module into the current scope.

use "math.npk".{square, pi};
int32:val = square(5);
// cube(5) // Error: undefined identifier

Namespace Import (as M)

Imports the module as a namespace. Symbols are accessed using the namespace prefix.

use "math.npk" as math;
int32:val = math.square(5);

Module Search Path

When resolving modules, the compiler searches directories in the following order:

1. Current Directory: Relative to the importing source file (for file path imports).
2. User Search Paths: Directories added via the -I <dir> command-line flags.
3. Stdlib: The compiler's root directory and its stdlib/ subdirectory.
4. System Directories: /usr/lib/aria (on Linux).
5. Environment Variables: Directories listed in the NITPICK_PATH environment variable.

Diamond Import Behavior

Nitpick guarantees type identity across multiple paths. If module A and module B both import C, and your file imports both A and B, the types from C will match perfectly. There are no duplicate type definitions for the same logical imported module.

Error Handling Patterns

• Missing Module: If the compiler cannot find the module in the search paths, it emits Failed to load module 'path/to/module.npk'. Ensure your -I flags and NITPICK_PATH are set correctly.
• Private Symbol: Attempting to selectively import or access a non-pub symbol emits an error like Symbol 'private_func' is private and cannot be used outside its defining module. Use the pub keyword in the defining module.

Example

// file: math_utils.npk
pub func:square = int32(int32:x) {
    pass (x * x);
};
pub const int32:pi = 3;

// file: main.npk
use "math_utils.npk" as math;

func:main = int32() {
    int32:val = raw math.square(math.pi);
    println(`&{val}`);    // 9
    exit 0;
};

func:failsafe = int32(tbb32:err) { exit 1; };

Notes

• All pub declarations (func:, struct, enum, Rules, Type, const, fixed, mod) are importable.
• Borrow summaries cross use (v0.30.3+). Every imported pub func: brings its FunctionBorrowSummary along with the declaration. The borrow checker consumes that summary identically to local functions, so cross-module ARIA-032 (handle outlives arena), $$i return-borrow source tracking, and the #[destroys_arena(<param>)] extern attribute all flow transparently. See ../handles/cross_module.md. No sidecar file is involved — the checker walks the in-memory ASTs that the module loader already holds.
• Local re-declaration wins. A local extern or func: with the same name as an imported symbol overwrites the imported summary (no duplicate-declaration error). This preserves the pre-v0.30.3 workaround pattern for cases where you want to override an imported summary.

File Extension Conventions

Nitpick source files use the following accepted extension:

use path: include the extension explicitly in the import path.

use "math_utils.npk".*;   // canonical

Related

• mod.md — defining modules
• cfg.md — conditional compilation
• visibility.md — public vs private symbols
• search_paths.md — path resolution
• packages.md — package structure