doc/guide/src/MLBasisAnnotations.adoc

   1 MLBasisAnnotations
   2 ==================
   3
   4 <:MLBasis:ML Basis> annotations control options that affect the
   5 elaboration of SML source files.  Conceptually, a basis file is
   6 elaborated in a default annotation environment (just as it is
   7 elaborated in an empty basis).  The declaration
   8 ++ann++{nbsp}++"++__ann__++"++{nbsp}++in++{nbsp}__basdec__{nbsp}++end++
   9 merges the annotation _ann_ with the "current" annotation environment
  10 for the elaboration of _basdec_.  To allow for future expansion,
  11 ++"++__ann__++"++ is lexed as a single SML string constant.  To
  12 conveniently specify multiple annotations, the following derived form
  13 is provided:
  14
  15 ****
  16 +ann+ ++"++__ann__++"++ (++"++__ann__++"++ )^\+^ +in+ _basdec_ +end+
  17 =>
  18 +ann+ ++"++__ann__++"++ +in+ +ann+ (++"++__ann__++"++)^\+^ +in+ _basdec_ +end+ +end+
  19 ****
  20
  21 Here are the available annotations.  In the explanation below, for
  22 annotations that take an argument, the first value listed is the
  23 default.
  24
  25 * +allowFFI {false|true}+
  26 +
  27 If `true`, allow `_address`, `_export`, `_import`, and `_symbol`
  28 expressions to appear in source files.  See
  29 <:ForeignFunctionInterface:>.
  30
  31 * +allowSuccessorML {false|true}+
  32 +
  33 --
  34 Allow or disallow all of the <:SuccessorML:> features.  This is a
  35 proxy for all of the following annotations.
  36
  37 ** +allowDoDecls {false|true}+
  38 +
  39 If `true`, allow a +do _exp_+ declaration form.
  40
  41 ** +allowExtendedConsts {false|true}+
  42 +
  43 --
  44 Allow or disallow all of the extended constants features.  This is a
  45 proxy for all of the following annotations.
  46
  47 *** +allowExtendedNumConsts {false|true}+
  48 +
  49 If `true`, allow extended numeric constants.
  50
  51 *** +allowExtendedTextConsts {false|true}+
  52 +
  53 If `true`, allow extended text constants.
  54 --
  55
  56 ** +allowLineComments {false|true}+
  57 +
  58 If `true`, allow line comments beginning with the token ++(*)++.
  59
  60 ** +allowOptBar {false|true}+
  61 +
  62 If `true`, allow a bar to appear before the first match rule of a
  63 `case`, `fn`, or `handle` expression, allow a bar to appear before the
  64 first function-value binding of a `fun` declaration, and allow a bar
  65 to appear before the first constructor binding or description of a
  66 `datatype` declaration or specification.
  67
  68 ** +allowOptSemicolon {false|true}+
  69 +
  70 If `true`, allows a semicolon to appear after the last expression in a
  71 sequence expression or `let` body.
  72
  73 ** +allowOrPats {false|true}+
  74 +
  75 If `true`, allows disjunctive (a.k.a., "or") patterns of the form
  76 +_pat_ | _pat_+.
  77
  78 ** +allowRecordPunExps {false|true}+
  79 +
  80 If `true`, allows record punning expressions.
  81
  82 ** +allowSigWithtype {false|true}+
  83 +
  84 If `true`, allows `withtype` to modify a `datatype` specification in a
  85 signature.
  86
  87 ** +allowVectorExpsAndPats {false|true}+
  88 +
  89 --
  90 Allow or disallow vector expressions and vector patterns.  This is a
  91 proxy for all of the following annotations.
  92
  93 *** +allowVectorExps {false|true}+
  94 +
  95 If `true`, allow vector expressions.
  96
  97 *** +allowVectorPats {false|true}+
  98 +
  99 If `true`, allow vector patterns.
 100 --
 101 --
 102
 103 * +forceUsed+
 104 +
 105 Force all identifiers in the basis denoted by the body of the `ann` to
 106 be considered used; use in conjunction with `warnUnused true`.
 107
 108 * +nonexhaustiveBind {warn|error|ignore}+
 109 +
 110 If `error` or `warn`, report nonexhaustive patterns in `val`
 111 declarations (i.e., pattern-match failures that raise the `Bind`
 112 exception).  An error will abort a compile, while a warning will not.
 113
 114 * +nonexhaustiveExnBind {default|ignore}+
 115 +
 116 If `ignore`, suppress errors and warnings about nonexhaustive matches
 117 in `val` declarations that arise solely from unmatched exceptions.
 118 If `default`, follow the behavior of `nonexhaustiveBind`.
 119
 120 * +nonexhaustiveExnMatch {default|ignore}+
 121 +
 122 If `ignore`, suppress errors and warnings about nonexhaustive matches
 123 in `fn` expressions, `case` expressions, and `fun` declarations that
 124 arise solely from unmatched exceptions.  If `default`, follow the
 125 behavior of `nonexhaustiveMatch`.
 126
 127 * +nonexhaustiveExnRaise {ignore|default}+
 128 +
 129 If `ignore`, suppress errors and warnings about nonexhaustive matches
 130 in `handle` expressions that arise solely from unmatched exceptions.
 131 If `default`, follow the behavior of `nonexhaustiveRaise`.
 132
 133 * +nonexhaustiveMatch {warn|error|ignore}+
 134 +
 135 If `error` or `warn`, report nonexhaustive patterns in `fn`
 136 expressions, `case` expressions, and `fun` declarations (i.e.,
 137 pattern-match failures that raise the `Match` exception).  An error
 138 will abort a compile, while a warning will not.
 139
 140 * +nonexhaustiveRaise {ignore|warn|error}+
 141 +
 142 If `error` or `warn`, report nonexhaustive patterns in `handle`
 143 expressions (i.e., pattern-match failures that implicitly (re)raise
 144 the unmatched exception).  An error will abort a compile, while a
 145 warning will not.
 146
 147 * +redundantBind {warn|error|ignore}+
 148 +
 149 If `error` or `warn`, report redundant patterns in `val` declarations.
 150 An error will abort a compile, while a warning will not.
 151
 152 * +redundantMatch {warn|error|ignore}+
 153 +
 154 If `error` or `warn`, report redundant patterns in `fn` expressions,
 155 `case` expressions, and `fun` declarations.  An error will abort a
 156 compile, while a warning will not.
 157
 158 * +redundantRaise {warn|error|ignore}+
 159 +
 160 If `error` or `warn`, report redundant patterns in `handle`
 161 expressions.  An error will abort a compile, while a warning will not.
 162
 163 * +resolveScope {strdec|dec|topdec|program}+
 164 +
 165 Used to control the scope at which overload constraints are resolved
 166 to default types (if not otherwise resolved by type inference) and the
 167 scope at which unresolved flexible record constraints are reported.
 168 +
 169 The syntactic-class argument means to perform resolution checks at the
 170 smallest enclosing syntactic form of the given class.  The default
 171 behavior is to resolve at the smallest enclosing _strdec_ (which is
 172 equivalent to the largest enclosing _dec_).  Other useful behaviors
 173 are to resolve at the smallest enclosing _topdec_ (which is equivalent
 174 to the largest enclosing _strdec_) and at the smallest enclosing
 175 _program_ (which corresponds to a single `.sml` file and does not
 176 correspond to the whole `.mlb` program).
 177
 178 * +sequenceNonUnit {ignore|error|warn}+
 179 +
 180 If `error` or `warn`, report when `e1` is not of type `unit` in the
 181 sequence expression `(e1; e2)`.  This can be helpful in detecting
 182 curried applications that are mistakenly not fully applied.  To
 183 silence spurious messages, you can use `ignore e1`.
 184
 185 * +valrecConstr {warn|error|ignore}+
 186 +
 187 If `error` or `warn`, report when a `val rec` (or `fun`) declaration
 188 redefines an identifier that previously had constructor status.  An
 189 error will abort a compile, while a warning will not.
 190
 191 * +warnUnused {false|true}+
 192 +
 193 Report unused identifiers.
 194
 195 == Next Steps ==
 196
 197  * <:MLBasisAnnotationExamples:>
 198  * <:WarnUnusedAnomalies:>