Merge branch 'develop' into release

Author: ice-phoenix

docs/src/md/commands.md

@@ -1,6 +1,6 @@
 <#mode quote>
 
-\newcommand{\currentKotlinMajorVersion}{\textrm{1.8}}
+\newcommand{\currentKotlinMajorVersion}{\textrm{1.9}}
 
 \newcommand{\opMathTT}[2]{%
   \expandafter\newcommand{#1}{\operatorname{\texttt{#2}}}%
@@ -82,6 +82,7 @@
 \opMathIT{\nested}{nested}
 \opMathIT{\dataClass}{dataClass}
 \opMathIT{\dataClassParam}{dp}
+\opMathIT{\dataObject}{dataObject}
 
 \opMathIT{\name}{name}
 \opMathIT{\type}{type}

docs/src/md/index.md

@@ -4,7 +4,7 @@ title: Kotlin language specification
 author:
 - Marat Akhin
 - Mikhail Belyaev
-subtitle: Version 1.8-rfc+0.1
+subtitle: Version 1.9-rfc+0.1
 ---
 
 <#include "commands.md">

docs/src/md/kotlin.core/annotations.md

@@ -17,6 +17,9 @@ An annotation type is a special kind of class type which is allowed to include r
 - Other annotation types;
 - [Arrays][Array types] of any type listed above.
 
+> Important: when we say "other annotation types", we mean an annotation type cannot reference itself, either directly or indirectly.
+> For example, if annotation type `A` references annotation type `B` which references an array of `A`, it is prohibited and reported as a compile-time error.
+
 Annotation classes are not allowed to have any member functions, constructors or mutable properties.
 They are also not allowed to have declared supertypes and are considered to be implicitly derived from `kotlin.Annotation`.
 

docs/src/md/kotlin.core/declarations.md

@@ -403,8 +403,8 @@ As such, data classes allow Kotlin to reduce the boilerplate and generate a numb
     - `equals(that)` returns true iff:
         - `that` has the same runtime type as `this`;
         - `this.prop == that.prop` returns `true` for every data property `prop`;
-    - `hashCode()` returns the same numbers for objects `A` and `B` if they are equal w.r.t. the generated `equals`;
-    - `toString` returns a string representations which is guaranteed to include the class name along with all the data properties' string representations.
+    - `hashCode()` returns the same numbers for values `A` and `B` if they are equal w.r.t. the generated `equals`;
+    - `toString()` returns a string representations which is guaranteed to include the class name along with all the data properties' string representations.
 * A `copy()` function for shallow object copying with the following properties:
     - It has the same number of parameters as the primary constructor with the same names and types;
     - It calls the primary constructor with the corresponding parameters at the corresponding positions;
@@ -499,6 +499,35 @@ Data classes have the following restrictions:
 >
 > Disclaimer: the implementations of these methods given in this examples are not guaranteed to exactly match the ones generated by kotlin compiler, please refer to the descriptions of these methods above for guarantees
 
+##### Data object declaration
+
+> Note: as of Kotlin $\currentKotlinMajorVersion{}$, this feature is experimental.
+
+A data object $\dataObject$ is a special kind of [object][Object declaration], which extends the [data class][Data class declaration] abstraction (product type of one or more data properties) to a case of unit type: product type of zero data properties.
+
+> Note: unit type has only one possible value, thus it is also known as singleton type.
+
+Similarly to data classes, there are a number of functions with predefined behaviour generated for data objects.
+
+* `equals() / hashCode() / toString()` functions compliant with [their contracts][`kotlin.Any`-builtins]:
+    - `equals(that)` returns true iff `that` has the same runtime type as `this`;
+    - `hashCode()` returns the same numbers for values `A` and `B` if they are equal w.r.t. the generated `equals`;
+    - `toString()` returns a string representations which is guaranteed to include the object name.
+
+> Note: `copy()` and `componentN()` functions are not generated, as they are not relevant for a unit type.
+> 
+> * `copy()` function is not needed as unit type has a single possible value;
+> * `componentN()` functions are not needed as unit type has no data properties.
+
+Unlike data classes, however, for data objects the only generated function which can be exemplified or inherited is `toString()`; `equals()` and `hashCode()` for a data object always work as specified above.
+This is to ensure data objects do not violate the unit type invariant of "being inhabited by only one value", which would be possible if one were to provide a custom `equals()` implementation.
+
+If either `equals()` or `hashCode()` function would be exemplified or inherited by a data object, it is a compile-time error.
+
+Data objects have the same restrictions are regular [objects][Object declaration].
+
+> Note: [companion objects][Class declaration] and [object literals][Object literals] cannot be data objects.
+
 #### Enum class declaration
 
 Enum class $E$ is a special kind of class with the following properties:
@@ -510,6 +539,8 @@ Enum class $E$ is a special kind of class with the following properties:
 - It cannot have type parameters of any kind;
 - It has special syntax to accommodate for the properties described above.
 
+> Note: for the purposes of overload resolution, enum entries are considered to be [static member callables][Call with an explicit type receiver] of the enum class type
+
 Enum class body uses special kind of syntax (see grammar) to declare enum entries in addition to all other declarations inside the class body.
 Enum entries have their own bodies that may contain their own declarations, similar to [object declarations][Classifier declaration].
 
@@ -542,27 +573,41 @@ Every enum entry of class `E` implicitly overrides members of `kotlin.Enum<E>` i
 
   (a member of `kotlin.Any`) defined by default to return the entry name, but may be overridden  to have different behaviour both in the enum class declaration and in entry declarations.
 
-In addition to these, every enum class type `E` has the following **static** member functions declared implicitly:
+In addition to these, every enum class type `E` has the following **static** members declared implicitly:
+
+- ```kotlin
+  public final static val entries: EnumEntries<E>
+  ```
+
+  This property returns an instance of a special immutable `EnumEntries<E>` list of all possible enum values in the order they are declared;
 
 - ```kotlin
   public final static fun valueOf(value: String): E
   ```
 
-   returning an object corresponding to the entry with the name equal to `value` parameter of the call or throws an exception otherwise;
+  This function returns an object corresponding to the entry with the name equal to `value` parameter of the call or throws an exception otherwise.
+
+> Important: `static` is not a valid Kotlin keyword and is only used here for clarity.
+> The static members are handled differently by the [overload resolution][Call with an explicit type receiver].
+
+Kotlin standard library also introduces a function to access all enum values for a specific enum class called `kotlin.enumEntries<T>`.
+Please refer to the standard library documentation for details.
+
+> Note: the `entries` property is available since Kotlin 1.9.
+
+For backwards compatibility, in addition to the `entries` property, every enum class type `E` has the following **static** member function declared implicitly.
 
 - ```kotlin
   public final static fun values(): kotlin.Array<E>
   ```
-  
-  returning an [array][Array types] of all possible enum values in the order they are declared.
-  Every invocation of this function returns a new array to disallow changing its contents.
 
-> Important: `static` is not a valid Kotlin keyword and is only used here for clarity
+  This function returns an [array][Array types] of all possible enum values in the order they are declared.
+  Every invocation of this function returns a new array to disallow changing its contents.
 
-> Note: these static member functions are handled differently by the [overload resolution][Overload resolution].
+> Important: `values` function is effectively deprecated and `entries` property should be used instead.
 
-> Note: Kotlin standard library introduces another function to access all enum values for a specific enum class called `kotlin.enumValues<T>`.
-> Please refer to the standard library documentation for details.
+Kotlin standard library also introduces another function to access all enum values for a specific enum class called `kotlin.enumValues<T>` (which is deprecated for subsequent removal).
+Please refer to the standard library documentation for details.
 
 > Example:
 >
@@ -622,6 +667,9 @@ Annotation classes have the following properties:
     - Other annotation types;
     - Arrays of any other allowed type.
 
+> Important: when we say "other annotation types", we mean an annotation type cannot reference itself, either directly or indirectly.
+> For example, if annotation type `A` references annotation type `B` which references an array of `A`, it is prohibited and reported as a compile-time error.
+
 > Note: annotation classes can have type parameters, but cannot use them as types for their primary constructor parameters.
 > Their main use is for various annotation processing tools, which can access the type arguments from the source code.
 
@@ -796,6 +844,8 @@ Similarly to interfaces, we shall specify object declarations by highlighting th
 > Note: this section is about declaration of _named_ objects. 
 > Kotlin also has a concept of _anonymous_ objects, or object literals, which are similar to their named counterparts, but are expressions rather than declarations and, as such, are described in the [corresponding section][Object literals].
 
+> Note: besides regular object declarations, Kotlin supports [data object declarations][Data object declaration].
+
 #### Local class declaration
 
 A class (but not an interface or an object) may be declared *locally* inside a [statement scope][Scopes and identifiers] (namely, inside a function).
@@ -1130,6 +1180,8 @@ They may also be passed to other functions as `noinline` or `crossinline` argume
 
 Particular platforms may introduce additional restrictions or guarantees for the inlining mechanism.
 
+> Important: for extension functions, the extension receiver is considered to be effectively `noinline`.
+
 > Examples:
 > 
 > ```kotlin
@@ -1385,7 +1437,9 @@ Properties without backing fields are not allowed to have initializer expression
 
 Read/write access to the property is replaced with getter/setter invocation respectively. 
 Getters and setters allow for some modifiers available for function declarations (for example, they may be declared `inline`, see grammar for details).
+
 Properties themselves may also be declared `inline`, meaning that both getter and setter of said property are `inline`.
+Additionally, `inline` properties are not allowed to have backing fields, i.e., they must have custom accessors which do not use the `field` property.
 
 #### Delegated property declaration
 
@@ -1706,7 +1760,6 @@ The following declarations are not allowed to have type parameters:
 - Constructor declarations;
 - Getters and setters of property declarations;
 - Enum class declarations;
-- Annotation class declarations;
 - Classifier declarations inheriting from `kotlin.Throwable`.
 
 Type parameters are allowed to specify *subtyping restrictions* on them in the form `T : U`, meaning $T <: U$ where $T$ is a type parameter and $U$ is some other type available in the scope the declaration is declared in.
@@ -1791,9 +1844,9 @@ By supplying this annotation the author of the code explicitly declares that saf
 
 #### Reified type parameters
 
-Type parameters of inline function declarations (and only those) can be declared `reified` using the corresponding keyword.
-A reified type parameter is a [runtime-available][Runtime-available types] type inside the function scope, see the corresponding section for details.
-Reified type parameters can only be substituted by other [runtime-available types][Runtime-available types] when using such functions.
+Type parameters of inline function or property declarations (and only those) can be declared `reified` using the corresponding keyword.
+A reified type parameter is a [runtime-available][Runtime-available types] type inside their declaration's scope, see the corresponding section for details.
+Reified type parameters can only be substituted by other [runtime-available types][Runtime-available types] when using such declarations.
 
 > Example:
 >

docs/src/md/kotlin.core/expressions.md

@@ -418,7 +418,7 @@ If when expression is not [exhaustive][Exhaustive when expressions], it has type
 > }
 > ```
 
-When with bound value also allows for an inline property declaration of the form `when (val V = E) { ... }` inside the parentheses.
+When with bound value also allows for an in-place property declaration of the form `when (val V = E) { ... }` inside the parentheses.
 This declares a new property (see [declaration sections][Property declaration] for details) alongside the usual mechanics of the *when-expression*.
 The scope of this property is limited to the `when` expression, including both conditions and control structure bodies of the expression.
 As its form is limited to a simple "assignment-like" declaration with an initializer, this property does not allow getters, setters, delegation or destructuring.
@@ -711,15 +711,16 @@ The type of elvis operator expression is the [least upper bound][Least upper bou
 :::{.paste target=grammar-rule-rangeExpression}
 :::
 
-A *range expression* is a binary expression which uses a range operator `..`.
-It is an [overloadable][Operator overloading] operator with the following expansion:
+A *range expression* is a binary expression which uses a range operator `..` or a range-until operator `..<`.
+These are [overloadable][Operator overloading] operators with the following expansions:
 
 - `A..B` is exactly the same as `A.rangeTo(B)`
+- `A..<B` is exactly the same as `A.rangeUntil(B)`
 
-where `rangeTo` is a valid operator function available in the current scope.
+where `rangeTo` or `rangeUntil` is a valid operator function available in the current scope.
 
-The return type of this function is not restricted.
-A range expression has the same type as the return type of the corresponding `rangeTo` overload variant.
+The return type of these functions is not restricted.
+A range expression has the same type as the return type of the corresponding operator function overload variant.
 
 ### Additive expressions
 

docs/src/md/kotlin.core/overload-resolution.md

@@ -230,7 +230,8 @@ They mostly follow the same rules as [calls with an explicit value receiver][Cal
 However, for a callable `f` with an explicit type receiver `T` the following sets are analyzed (**in the given order**):
 
 1. Static member callables named `f` of type `T`;
-2. The overload candidate sets for call `T.f()`, where `T` is a companion object of type `T`.
+2. Static member callables named `f` of type `T` declared implicitly;
+3. The overload candidate sets for call `T.f()`, where `T` is a companion object of type `T`.
 
 ##### Call with an explicit super-form receiver
 
@@ -730,6 +731,14 @@ TODO: more examples
 
 > Note: this is different from the overload resolution for regular calls in that no most specific candidate selection process is performed inside the sets
 
+> Important: when the callable reference resolution for `T::f` requires building overload candidate sets for both [type][Call with an explicit type receiver] and [value][Call with an explicit receiver] receiver candidates, they are considered in the following order.
+>
+> 1. Static member callables named `f` of type `T`;
+> 2. The overload candidate sets for call `t::f`, where `t` is a value of type `T`;
+> 3. The overload candidate sets for call `T::f`, where `T` is a companion object of type `T`.
+>
+> Callable references to members of companion objects are deprioritized, as you could always use the `T.Companion::f` syntax to reference them.
+
 > Important: when building the OCS for a callable reference, `invoke` operator convention does not apply, and all property references are treated equally as function references, being placed in the same sets.
 > For example, consider the following code:
 > 

grammar/scripts/compareActuals.sh

@@ -3,7 +3,7 @@
 TEST_DATA="$1"
 
 for fo in `find ${TEST_DATA} -name "*.antlrtree.txt"`; do
-    fa="$i.actual";
+    fa="$fo.actual";
     if [[ -e $fa ]]; then
         meld $fa $fo;
     fi

grammar/scripts/processModified.sh

@@ -2,7 +2,7 @@
 
 REF="$1"
 
-for i in `git status -s | grep "^M.*\.antlrtree.txt$" | cut -d ' ' -f 3`; do
+for i in `git status -s | grep "^ M.*\.antlrtree.txt$" | cut -d ' ' -f 3`; do
     git diff --numstat HEAD $i | grep -q "$REF";
     if [[ $? == 0 ]]; then
         echo $i;

grammar/src/main/antlr/KotlinLexer.g4

@@ -68,6 +68,7 @@ MOD_ASSIGNMENT: '%=';
 ARROW: '->';
 DOUBLE_ARROW: '=>';
 RANGE: '..';
+RANGE_UNTIL: '..<';
 COLONCOLON: '::';
 DOUBLE_SEMICOLON: ';;';
 HASH: '#';
@@ -417,6 +418,7 @@ Inside_MOD_ASSIGNMENT: MOD_ASSIGNMENT  -> type(MOD_ASSIGNMENT);
 Inside_ARROW: ARROW  -> type(ARROW);
 Inside_DOUBLE_ARROW: DOUBLE_ARROW  -> type(DOUBLE_ARROW);
 Inside_RANGE: RANGE  -> type(RANGE);
+Inside_RANGE_UNTIL: RANGE_UNTIL  -> type(RANGE_UNTIL);
 Inside_RESERVED: RESERVED -> type(RESERVED);
 Inside_COLONCOLON: COLONCOLON  -> type(COLONCOLON);
 Inside_DOUBLE_SEMICOLON: DOUBLE_SEMICOLON  -> type(DOUBLE_SEMICOLON);