Document record punning in patterns and static requirement for modules (#2006)

* document punning and static expressions/decs/patterns/modules bodies

Author: crusso

doc/modules/language-guide/pages/language-manual.adoc

@@ -24,7 +24,7 @@
 * [X] Remove Shared type
 * [X] Explain dot keys, dot vals and iterators
 * [X] Debug expressions
-* [ ] Document punning in type record patterns: https://github.com/dfinity-lab/motoko/pull/964
+* [X] Document punning in type record patterns: https://github.com/dfinity-lab/motoko/pull/964
 * [X] Update ErrorCode section
 * [Floats] Literals type and operations
 * [ ] Re-section so headings appear in content outline
@@ -539,6 +539,8 @@ The syntax of a _pattern_ is as follows:
 
 <pat-field> ::=                                object pattern fields
   <id> = <pat>                                   field
+  <id>                                           punned field
+  <id> : <typ>                                   typed punned field
 ```
 
 
@@ -1222,6 +1224,7 @@ During an upgrade, a trap occuring in the implicit call to `preupgrade()` or `po
 [[decl-seq]]
 === Sequence of declarations
 
+
 A sequence of declarations `<dec>;*` occurring in a block, a program or embedded in the `<dec-field>;*` sequence of an object body has type `T`
 provided:
 
@@ -1293,6 +1296,10 @@ The object pattern `{ <pat-field>;* }` matches an object value, a collection of
 The set of identifiers bound by each field of the object pattern must be distinct.
 The names of the pattern fields in the object pattern must be distinct.
 
+Object patterns support _punning_ for concision.
+A punned field `<id>` is shorthand for `<id> = <id>`; Similarly, a typed, punned field `<id> : <typ> ` is short-hand for `<id> = <id> : <typ>`. Both
+bind the matched value of the field named `<id>` to the identifier `<id>`.
+
 Pattern matching fails if one of the pattern fields fails to match the corresponding field value of the object value.
 Pattern matching succeeds if every pattern field matches the corresponding named field of the object value.
 The binding returned by a successful match is the union of the bindings returned by the field matches.
@@ -1409,7 +1416,7 @@ Fields can be declared with `public` or `private` visibility; if the visibility
 
 The qualifier `<sort>` (one of `actor`, `module` or `object`) specifies the *sort* of the object's type. The sort imposes restrictions on the types of the public object fields.
 
-Let `T = sort { [var0] id0 : T0, ... , [varn] idn : T0 }` denote the type of the object.
+Let `T = <sort> { [var0] id0 : T0, ... , [varn] idn : T0 }` denote the type of the object.
 Let `<dec>;*` be the sequence of declarations embedded in `<dec-field>;*`.
 The object declaration has type `T` provided that:
 
@@ -1419,21 +1426,58 @@ The object declaration has type `T` provided that:
      with types `T(id)` for `id` in `Id == Id_private union Id_public`, and
    * `{ id0, ..., idn } == Id_public`, and
    * for all `i in 0 \<= i \<= n`, `[vari] Ti == T(idi)`.
+3. If `<sort>` is `module`, then the declarations in `<dec>;*` must be _static_ (see <<decl-static>>).
 
 Note that requirement 1. imposes further constraints on the field types of `T`.
 In particular:
 
 * if the sort is `actor` then all public fields must be non-`var` (immutable) `shared` functions (the public interface of an actor can only provide asynchronous messaging via shared functions).
 
-Evaluation of `(object|actor)? <id>? =? { <exp-field>;* }` proceeds by
+Evaluation of `<sort>? <id>? =? { <dec-field>;* }` proceeds by
 evaluating the declarations in `<dec>;*`. If the evaluation of `<dec>;*` traps, so does the object declaration.
 Otherwise, `<dec>;*` produces a set of bindings for identifiers in `Id`.
 let `v0`, ..., `vn` be the values or locations bound to identifiers `<id0>`, ..., `<idn>`.
 The result of the object declaration is the object `v == sort { <id0> = v1, ..., <idn> = vn}`.
 
 If `<id>?` is present, the declaration binds `<id>` to `v`. Otherwise, it produces the empty set of bindings.
 
-// TBR do we actually propagate trapping of actor creation?
+[[decl-static]]
+==== Static declarations
+
+A declaration is _static_ if it is:
+
+*   a `type` declaration, or
+*   a `class` declaration, or
+*   a `let` declaration with a static pattern and a static expression, or
+*   a module, function or object declaration that desugars to a static `let` declaration, or
+*   a static expression, or
+*   an `ignore` with static expression.
+
+An expression is _static_ if it is:
+
+*  a literal expression, or
+*  a tuple of static expressions, or
+*  an object of static expressions, or
+*  a variant or option with a static expression, or
+*  an immutable array, or
+*  field access and projection from a static expression, or
+*  a module expression, or
+*  a function expression, or
+*  a static declaration, or
+*  a block, all of whose declarations are static, or
+*  a type annotation with a static expression.
+
+A pattern is _static_ if it is:
+
+* an identifier, or
+* a wildcard, or
+* a tuple of static patterns, or
+* type annotation with a static pattern.
+////
+why not record patterns?
+////
+
+Static phrases are designed to be side-effect free, allowing the coalescing of duplicate library imports (a.k.a deduplication).
 
 [[decl-func]]
 === Function declaration
@@ -2044,7 +2088,9 @@ Note: type annotations have no-runtime cost and cannot be used to perform the (c
 
 The declaration expression `<dec>` has type `T` provided the declaration `<dec>` has type `T`.
 
-Evaluating the expression `<dec>` proceed by evaluating `<dec>`, returning the result of `<dec>` but discarding the bindings introduced by `<dec>` (if any).
+Evaluating the expression `<dec>` proceeds by evaluating `<dec>`, returning the result of `<dec>` but discarding the bindings introduced by `<dec>` (if any).
+
+(The expression `<dec>` is actually shorthand for the block expression `{ <dec> }`.)
 
 [[exp-debug]]
 === Debug