## MLton 20241230+git20251029+dfsg-5

# MLBasisSyntaxAndSemantics

An ML Basis (MLB) file should have the `.mlb` suffix and should contain a basis declaration.

## Syntax

A basis declaration (`basdec`) must be one of the following forms.

- `basis` `basid` `=` `basexp` (`and` `basid` `=` `basexp`)*

- `open` `basid1` …​ `basidn`

- `local` `basdec` `in` `basdec` `end`

- `basdec` [`;`] `basdec`

- `structure` `strid` [`=` `strid`] (`and` `strid`[`=` `strid`])*

- `signature` `sigid` [`=` `sigid`] (`and` `sigid` [`=` `sigid`])*

- `functor` `funid` [`=` `funid`] (`and` `funid` [`=` `funid`])*

- `path.sml`, `path.sig`, or `path.fun`

- `path.mlb`

- `ann` `"ann"` `in` `basdec` `end`

A basis expression (`basexp`) must be of one the following forms.

- `bas` `basdec` `end`

- `basid`

- `let` `basdec` `in` `basexp` `end`

Nested SML-style comments (enclosed with `(*` and `*)`) are ignored (but LineDirectives are recognized).

Paths can be relative or absolute. Relative paths are relative to the directory containing the MLB file. Paths may include path variables and are expanded according to a path map. Unquoted paths may include alpha-numeric characters and the symbols `-` and `_`, along with the arc separator `/` and extension separator `.`. More complicated paths, including paths with spaces, may be included by quoting the path with `"`. A quoted path is lexed as an SML string constant.

Annotations allow a library author to control options that affect the elaboration of SML source files.

## Semantics

There is a formal semantics for ML Basis files in the style of the Definition. Here, we give an informal explanation.

An SML structure is a collection of types, values, and other structures. Similarly, a basis is a collection, but of more kinds of objects: types, values, structures, fixities, signatures, functors, and other bases.

A basis declaration denotes a basis. A structure, signature, or functor declaration denotes a basis containing the corresponding module. Sequencing of basis declarations merges bases, with later definitions taking precedence over earlier ones, just like sequencing of SML declarations. Local declarations provide name hiding, just like SML local declarations. A reference to an SML source file causes the file to be elaborated in the basis extant at the point of reference. A reference to an MLB file causes the basis denoted by that MLB file to be imported — the basis at the point of reference does not affect the imported basis.

Basis expressions and basis identifiers allow binding a basis to a name.

An MLB file is elaborated starting in an empty basis. Each MLB file is elaborated and evaluated only once, with the result being cached. Subsequent references use the cached value. Thus, any observable effects due to evaluation are not duplicated if the MLB file is referred to multiple times.