Keyword use

Definition

use is a module-surface keyword used to organize visibility, imports, or sharing.

The keyword use organizes symbol circulation across modules. It clarifies what is imported, shared, renamed, or attached to a visibility boundary.

Grammatical role

Imports symbols into the current module.

This grammatical role is essential: if a reader understands the structural place of use, they already understand much of the diagnostics that will appear when it is moved or truncated.

Canonical syntax

Canonical form: `use path.{symbols} as alias`.

The canonical form matters because it gives the compiler and the reader the same reference structure. A large share of diagnostics related to use come from an abbreviated, displaced, or incomplete form.

Detailed semantics

Semantically, use modifies symbol visibility. It influences how a reader reconstructs the origin of names and how the compiler resolves references.

In an encyclopedic reading, use should not be reduced to a dictionary definition. Its effect on scope, block shape, value visibility, control progression, and the diagnostic family it activates when misused must also be considered.

Specific profile

Targeted import keyword. It documents where symbols come from and directly contributes to the architectural readability of a module.

Design notes

• A clean `use` is architecture information: it shows where names come from and which couplings the file accepts.
• In a large codebase, the quality of a `use` is measured by how easily one can trace a symbol back to its source.

Reading questions

• Which symbols are imported, and why those ones?
• Does the chosen alias really help reduce ambiguity?
• Does the import express legitimate coupling or an overly broad dependency?

Targeted anti-patterns

• Importing too broadly when a smaller symbol subset would document the dependency more cleanly.
• Using an alias that hides more than it clarifies about the real origin of symbols.

Effect on execution

use acts mainly on name resolution and cross-module visibility. Its execution-time effect is indirect but decisive for the structure of the compiled code.

In other words, the presence of use is not merely syntactic: it helps the reader predict what will be executed, produced, exposed, or forbidden from this point in the program.

Valid variants

• `use path.{symbols}`
• `use path.{symbols} as alias`

These variants are not free synonyms. They indicate the legitimate forms from which one can reason about diagnostics, scope differences, or contract readability.

Vitte example

space app/core
use std.io.{read, write} as io

proc ping() -> int {
  give 0
}

This example shows use in a nominal context. It should be read globally: where the contract begins, which values are constrained, which output becomes observable, and why the presence of the keyword is justified.

Guided reading of the example

1. First locate the full construction that contains use, not the isolated word.
2. Then identify which contract becomes visible because of use: type, branch, binding, module, exit, or advanced boundary.
3. Finish by checking the observable effect produced by the construction that contains use.
4. For a module keyword, verify the origin and destination of visible symbols.

This guided reading is intentionally closer to a reference page than to a tutorial: it helps reconstruct the exact role of use in a complete block.

Comparison with C

/* C comparison: imports are usually done with includes and naming conventions instead of module aliases. */

For this keyword, the parallel with C remains approximate. The comparison mainly indicates that in C the same idea is often spread across file conventions, operators, or less explicit control structures.

The source of truth remains Vitte grammar and semantics. The comparison with C should be read as a cultural marker, not as a parallel specification.

Recommended uses

use deserves to appear when it simplifies the reading of the block's global contract, not when it merely adds one more surface form.

When to use it

• When use makes the block contract more explicit at first reading.
• When it reduces the number of implicit assumptions the reader must reconstruct mentally.
• When the origin or outward exposure of a symbol must stay visible at module level.

When to avoid it

• Avoid use when another, more precise keyword already carries the block's intent.
• Avoid use when it adds only surface noise without clarifying the contract.
• Avoid reading or teaching it as an isolated token with no relation to the full structure.

Common pitfalls

• Using use in a grammatical layer where it does not belong.
• Confusing the role of the keyword with the role of the full surrounding block.
• Showing only the nominal form and never how the contract fails.

Invalid example and diagnostic

proc bad_use() -> int {
  use
  give 0
}

The module-level surface is misplaced or incomplete.

The counter-example is not merely wrong: it is wrong in an instructive way. It shows which grammar or execution-contract assumption is no longer accepted when use is moved, truncated, or combined with the wrong context. Concretely, the import does not provide a full target or resolution structure.

A good encyclopedic counter-example does not show arbitrarily broken code: it isolates the precise reason why use can no longer support the expected contract. Its teaching value is diagnostic before it is syntactic.

Common compilation errors

This table does not replace the compiler's exact diagnostics. It serves as a mental map: when use fails, the problem usually comes from an invalid grammatical form, an incoherent type contract, or an incomplete construction.

Neighbor keywords

Comparison with neighboring keywords is essential on a wiki-style page: use is better understood when one knows precisely what it does not do.

Common misreadings

• Reducing use to a local token instead of reading it as part of a full construction.
• Explaining only the syntax and forgetting the reading or diagnostic contract it imposes.

Implementation and diagnostic notes

• Common errors concern name resolution, alias collisions, or a shared surface that is too broad or incomplete.
• In a compiler, these keywords participate in cross-file resolution and visible API construction.

Presence in the book

• docs/book/chapters/09-modules.html
• docs/book/chapters/17-stdlib.html
• docs/book/chapters/27-grammar.html

See also

• docs/book/chapters/keywords/erreurs-compilateur.html
• docs/book/chapters/keywords/pull.html
• docs/book/glossary.html