MLBasisSyntaxAndSemantics
=========================

An <:MLBasis: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+ _basid~1~_ ... _basid~n~_
* +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 <:LineDirective:>s 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 <:MLBasisPathMap: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.

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

== Semantics ==

There is a <!Attachment(MLBasis,mlb-formal.pdf,formal semantics)> for
ML Basis files in the style of the
<:DefinitionOfStandardML: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.