## MLton 20241230

# MLBasisAnnotations

ML Basis annotations control options that affect the elaboration of SML source files. Conceptually, a basis file is elaborated in a default annotation environment (just as it is elaborated in an empty basis). The declaration

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

merges the annotation `ann` with the "current" annotation environment for the elaboration of `basdec`. To allow for future expansion, `"ann"` is lexed as a single SML string constant. To conveniently specify multiple annotations, the following derived form is provided:

`ann` `"ann` ( `ann"` )+ `in` `basdec` `end` ⇒ `ann` `"ann"` `in` `ann` ( `"ann"` )+ `in` `basdec` `end` `end`

Here are the available annotations. In the explanation below, for annotations that take an argument, the first value listed is the default.

- `allowFFI {false|true}`

  If `true`, allow `_address`, `_export`, `_import`, and `_symbol` expressions to appear in source files. See ForeignFunctionInterface.

- `allowSuccessorML {false|true}`

  Allow or disallow all of the SuccessorML features. This is a proxy for all of the following annotations.

  - `allowDoDecls {false|true}`

    If `true`, allow a `do exp` declaration form.

  - `allowExtendedConsts {false|true}`

    Allow or disallow all of the extended constants features. This is a proxy for all of the following annotations.

    - `allowExtendedNumConsts {false|true}`

      If `true`, allow extended numeric constants.

    - `allowExtendedTextConsts {false|true}`

      If `true`, allow extended text constants.

  - `allowLineComments {false|true}`

    If `true`, allow line comments beginning with the token `(*)`.

  - `allowOptBar {false|true}`

    If `true`, allow a bar to appear before the first match rule of a `case`, `fn`, or `handle` expression, allow a bar to appear before the first function-value binding of a `fun` declaration, and allow a bar to appear before the first constructor binding or description of a `datatype` declaration or specification.

  - `allowOptSemicolon {false|true}`

    If `true`, allows a semicolon to appear after the last expression in a sequence expression or `let` body.

  - `allowOrPats {false|true}`

    If `true`, allows disjunctive (a.k.a., "or") patterns of the form `pat | pat`.

  - `allowRecordPunExps {false|true}`

    If `true`, allows record punning expressions.

  - `allowSigWithtype {false|true}`

    If `true`, allows `withtype` to modify a `datatype` specification in a signature.

  - `allowVectorExpsAndPats {false|true}`

    Allow or disallow vector expressions and vector patterns. This is a proxy for all of the following annotations.

    - `allowVectorExps {false|true}`

      If `true`, allow vector expressions.

    - `allowVectorPats {false|true}`

      If `true`, allow vector patterns.

- `forceUsed`

  Force all identifiers in the basis denoted by the body of the `ann` to be considered used; use in conjunction with `warnUnused true`.

- `nonexhaustiveBind {warn|error|ignore}`

  If `error` or `warn`, report nonexhaustive patterns in `val` declarations (i.e., pattern-match failures that raise the `Bind` exception). An error will abort a compile, while a warning will not.

- `nonexhaustiveExnBind {default|ignore}`

  If `ignore`, suppress errors and warnings about nonexhaustive matches in `val` declarations that arise solely from unmatched exceptions. If `default`, follow the behavior of `nonexhaustiveBind`.

- `nonexhaustiveExnMatch {default|ignore}`

  If `ignore`, suppress errors and warnings about nonexhaustive matches in `fn` expressions, `case` expressions, and `fun` declarations that arise solely from unmatched exceptions. If `default`, follow the behavior of `nonexhaustiveMatch`.

- `nonexhaustiveExnRaise {ignore|default}`

  If `ignore`, suppress errors and warnings about nonexhaustive matches in `handle` expressions that arise solely from unmatched exceptions. If `default`, follow the behavior of `nonexhaustiveRaise`.

- `nonexhaustiveMatch {warn|error|ignore}`

  If `error` or `warn`, report nonexhaustive patterns in `fn` expressions, `case` expressions, and `fun` declarations (i.e., pattern-match failures that raise the `Match` exception). An error will abort a compile, while a warning will not.

- `nonexhaustiveRaise {ignore|warn|error}`

  If `error` or `warn`, report nonexhaustive patterns in `handle` expressions (i.e., pattern-match failures that implicitly (re)raise the unmatched exception). An error will abort a compile, while a warning will not.

- `redundantBind {warn|error|ignore}`

  If `error` or `warn`, report redundant patterns in `val` declarations. An error will abort a compile, while a warning will not.

- `redundantMatch {warn|error|ignore}`

  If `error` or `warn`, report redundant patterns in `fn` expressions, `case` expressions, and `fun` declarations. An error will abort a compile, while a warning will not.

- `redundantRaise {warn|error|ignore}`

  If `error` or `warn`, report redundant patterns in `handle` expressions. An error will abort a compile, while a warning will not.

- `resolveScope {strdec|dec|topdec|program}`

  Used to control the scope at which overload constraints are resolved to default types (if not otherwise resolved by type inference) and the scope at which unresolved flexible record constraints are reported.

  The syntactic-class argument means to perform resolution checks at the smallest enclosing syntactic form of the given class. The default behavior is to resolve at the smallest enclosing strdec (which is equivalent to the largest enclosing dec). Other useful behaviors are to resolve at the smallest enclosing topdec (which is equivalent to the largest enclosing strdec) and at the smallest enclosing program (which corresponds to a single `.sml` file and does not correspond to the whole `.mlb` program).

- `sequenceNonUnit {ignore|error|warn}`

  If `error` or `warn`, report when `e1` is not of type `unit` in the sequence expression `(e1; e2)`. This can be helpful in detecting curried applications that are mistakenly not fully applied. To silence spurious messages, you can use `ignore e1`.

- `valrecConstr {warn|error|ignore}`

  If `error` or `warn`, report when a `val rec` (or `fun`) declaration redefines an identifier that previously had constructor status. An error will abort a compile, while a warning will not.

- `warnUnused {false|true}`

  Report unused identifiers.

## Next Steps

- MLBasisAnnotationExamples

- WarnUnusedAnomalies