Bring records proposal up to date

proposals/records.md

@@ -1,75 +1,60 @@
-# Records Work-in-Progress
 
-Unlike the other records proposals, this is not a proposal in itself, but a work-in-progress designed to record consensus design
-decisions for the records feature. Specification detail will be added as necessary to resolve questions.
+# Records
 
-The syntax for a record is proposed to be added as follows:
+This proposal tracks the specification for the C# 9 records feature, as agreed to by the C#
+language design team.
 
-```antlr
-class_declaration
-    : attributes? class_modifiers? 'partial'? 'class' identifier type_parameter_list?
-      parameter_list? type_parameter_constraints_clauses? class_body
-    ;
+The syntax for a record is as follows:
 
-struct_declaration
-    : attributes? struct_modifiers? 'partial'? 'struct' identifier type_parameter_list?
-      parameter_list? struct_interfaces? type_parameter_constraints_clauses? struct_body
+```antlr
+record_declaration
+    : attributes? class_modifier* 'partial'? 'record' identifier type_parameter_list?
+      parameter_list? record_base? type_parameter_constraints_clause* record_body
     ;
 
-class_body
-    : '{' class_member_declarations? '}'
-    | ';'
+record_base
+    : ':' class_type argument_list?
+    | ':' interface_type_list
+    | ':' class_type argument_list? interface_type_list
     ;
 
-struct_body
-    : '{' struct_members_declarations? '}'
+record_body
+    : '{' class_member_declaration* '}'
     | ';'
     ;
 ```
 
-The `attributes` non-terminal will also permit a new contextual attribute, `data`.
-
-A class (struct) declared with a parameter list or `data` modifier is called a record class (record struct), either of which is a record type.
-
-It is an error to declare a record type without both a parameter list and the `data` modifier.
+Record types are reference types, similar to a class declaration. It is an error for a record to provide
+a `record_base` `argument_list` if the `record_declaration` does not contain a `parameter_list`.
 
 ## Members of a record type
 
-In addition to the members declared in the class or struct body, a record type has the following additional members:
+In addition to the members declared in the record body, a record type has additional synthesized members.
+Members are synthesized unless an accessible concrete (non-abstract) member with a "matching" signature is 
+either inherited or declared in the record body. Two members are considered matching if they have the same
+signature or would be considered "hiding" in an inheritance scenario.
 
-### Primary Constructor
-
-A record type has a public constructor whose signature corresponds to the value parameters of the
-type declaration. This is called the primary constructor for the type, and causes the implicitly
-declared default class constructor, if present, to be suppressed. It is an error to have a primary
-constructor and a constructor with the same signature already present in the class.
-
-At runtime the primary constructor
-
-1. executes the instance field initializers appearing in the class-body; and then
-    invokes the base class constructor with no arguments.
-
-1. initializes compiler-generated backing fields for the properties corresponding to the value parameters (if these properties are compiler-provided
-
-### Properties
-
-For each record parameter of a record type declaration there is a corresponding public property member whose name and type are taken from the value parameter declaration. If no concrete (i.e. non-abstract) property with a get accessor and with this name and type is explicitly declared or inherited, it is produced by the compiler as follows:
-
-For a record struct or a record class:
-
-* A public `get` and `init` auto-property is created (see separate `init` accessor specification). Its value is initialized during construction with the value of the corresponding primary constructor parameter. Each "matching" inherited abstract property's get accessor is overridden.
+The synthesized members are as follows:
 
 ### Equality members
 
-Record types produce synthesized implementations for the following methods:
+Record types produce synthesized implementations for the following methods, where `T` is the
+containing type:
 
-* `object.GetHashCode()` override, unless it is sealed or user provided
-* `object.Equals(object)` override, unless it is sealed or user provided
+* `object.GetHashCode()` override
+* `object.Equals(object)` override
 * `T Equals(T)` method, where `T` is the current type
+* `Type EqualityContract` get-only property
+
+If either `object.GetHashCode()` or `object.Equals(object)` are sealed, an error is produced.
+
+`EqualityContract` is a virtual instance property which returns `typeof(T)`. If the base type
+defines an `EqualityContract` it is overridden in the derived record. If the base `EqualityContract`
+is sealed or non-virtual, an error is produced.
 
-`T Equals(T)` is specified to perform value equality such that `Equals` is
-true if and only if all the instance fields declared in the receiver type
-are equal to the fields of the other type.
+`T Equals(T)` is specified to perform value equality such that `Equals` is true if and only if
+all accessible instance fields in the receiver are equal to the fields of the parameter
+and `this.EqualityContract` equals `other.EqualityContract`.
 
 `object.Equals` performs the equivalent of
 
@@ -79,18 +64,60 @@ override Equals(object o) => Equals(o as T);
 
 ### Copy and Clone members
 
-A record type contains two synthesized copying members if methods with the same
-signature are not already declared within the record type:
+A record type contains two synthesized copying members:
 
 * A protected constructor taking a single argument of the record type.
-* A public parameterless instance method called `Clone` which returns the record type.
+* A public parameterless virtual instance "clone" method with a compiler-reserved name
 
 The protected constructor is referred to as the "copy constructor" and the synthesized
-body copies the values of all instance fields declared in the input type to the corresponding 
+body copies the values of all accessible instance fields in the input type to the corresponding
 fields of `this`.
 
-The `Clone` method returns the result of a call to a constructor with the same signature as the
-copy constructor.
+The "clone" method returns the result of a call to a constructor with the same signature as the
+copy constructor. The return type of the clone method is the containing type, unless a virtual
+clone method is present in the base class. In that case, the return type is the current containing
+type if the "covariant returns" feature is supported and the override return type otherwise. The
+synthesized clone method is an override of the base type clone method if one exists. An error is
+produced if the base type clone method is sealed.
+
+## Positional record members
+
+In addition to the above members, records with a parameter list ("positional records") synthesize
+additional members with the same conditions as the members above.
+
+### Primary Constructor
+
+A record type has a public constructor whose signature corresponds to the value parameters of the
+type declaration. This is called the primary constructor for the type, and causes the implicitly
+declared default class constructor, if present, to be suppressed. It is an error to have a primary
+constructor and a constructor with the same signature already present in the class.
+
+At runtime the primary constructor
+
+1. executes the instance initializers appearing in the class-body
+
+1. invokes the base class constructor with the arguments provided in the `record_base` clause, if present
+
+
+### Properties
+
+For each record parameter of a record type declaration there is a corresponding public property
+member whose name and type are taken from the value parameter declaration.
+
+For a record:
+
+* A public `get` and `init` auto-property is created (see separate `init` accessor specification).
+  Each "matching" inherited abstract accessor is overridden. The auto-property is initialized to
+  the value of the corresponding primary constructor parameter.
+
+### Deconstruct
+
+A positional record synthesizes a public void-returning method called Deconstruct with an out
+parameter declaration for each parameter of the primary constructor declaration. Each parameter
+of the Deconstruct method has the same type as the corresponding parameter of the primary
+constructor declaration. The body of the method assigns each parameter of the Deconstruct method
+to the value from an instance member access to a member of the same name.
+
 ## `with` expression
 
 A `with` expression is a new expression using the following syntax.
@@ -100,7 +127,7 @@ with_expression
     : switch_expression
     | switch_expression 'with' '{' member_initializer_list? '}'
     ;
-    
+
 member_initializer_list
     : member_initializer (',' member_initializer)*
     ;
@@ -114,13 +141,13 @@ A `with` expression allows for "non-destructive mutation", designed to
 produce a copy of the receiver expression with modifications in assignments
 in the `member_initializer_list`.
 
-A valid `with` expression has a receiver with a non-void type. The receiver type must contain an accessible
-parameterless instance method called `Clone` whose return type must be the receiver type, or a base type thereof.
+A valid `with` expression has a receiver with a non-void type. The receiver type must contain an
+accessible synthesized record "clone" method.
 
-On the right hand side of the `with` expression is an `member_initializer_list` with a
-sequence of assignments to *identifier*, which must an accessible instance field or property of the return
+On the right hand side of the `with` expression is a `member_initializer_list` with a sequence
+of assignments to *identifier*, which must be an accessible instance field or property of the return
 type of the `Clone()` method.
 
-Each `member_initializer` is processed the same way as an assignment to the field or property target on the return
-value of the `Clone()` method. The `Clone()` method is executed only once and the assignments are processed in
-lexical order.
+Each `member_initializer` is processed the same way as an assignment to a field or property
+access of the return value of the record clone method. The clone method is executed only once
+and the assignments are processed in lexical order.