kotlin / keep

Kotlin Evolution and Enhancement Process

KEEP - Kotlin Evolution and Enhancement Process

This repository contains proposals for the Kotlin Programming Language, including draft design notes and discussions for in-progress proposals as well as the design documentation on the changes that were already implemented.

The proposals themselves are colloquially referred to as KEEPs. They cover both the language itself and its standard library.

The implementation of the corresponding design enhancements usually lives in the Kotlin Source Code Repository.

Current KEEPs

• Current in-progress KEEPs are listed in issues.
• New KEEPs and additions to current KEEPs are submitted as pull requests.
• When KEEPs are implemented, the corresponding design documents are merged into this repository and stored in a proposals directory.

Design notes

Some feature ideas that are being discussed for Kotlin represent important directions of potential enhancement but are not complete to call them design proposals. They still need to be discussed with the Kotlin community to gather use-cases for these features, their potential syntax, impact on existing Kotlin code, etc. They are called "design notes" and are stored in a separate notes directory.

How to contribute to the design process

Language enhancements/features usually go through the following informal stages:

1. Discussion of an idea.
2. Collection of use-cases.
3. Design proposal and prototype implementation.
4. Experimental support in the language.
5. Further refinement and stable release.

All stages involve the gathering of feedback on the corresponding feature. It does not stop even when the feature becomes stable. The community feedback on all stages is crucial to the open philosophy of the Kotlin language enhancement process.

Contributing ideas

If you have a vague idea about the potential enhancement but you are not sure whether it is worthwhile and/or fits the Kotlin language, or just want to get community feedback, you can use either of the two channels you feel most comfortable with:

• #language-proposals channel in Kotlin public Slack (get an invite here);
• Kotlin Forum in the Language design category.

Contributing use-cases and specific enhancement proposals

If you have a use case that is not covered by the language or have a specific language enhancement in mind, then, please, file a YouTrack issue in the Language Design subsystem. While many popular enhancements and language design problems are already filed in Kotlin YouTrack, your contribution to them is still very important:

• 👍 Vote for the issues you encounter in your work.
• 📝 Comment with the description of your specific use-cases.

Our practice of language design shows that contributing real-life use-cases is the most valuable piece of feedback from the Kotlin community.

Contributing design proposals (KEEPs)

Design proposals in this repository are expected to be well thought-through and usually come with a prototype implementation that demonstrates their feasibility. All design proposals in this repository shall be backed by maintainers of the corresponding subsystems in the Kotlin compiler or its standard library.

If you are in doubt about whether the proposal meets those criteria, please start with the discussion of your idea, use case, or a specific enhancement in the appropriate channels and secure support for your general idea/proposal from maintainers before submitting a KEEP.

We will be gradually moving KEEPs that are not backed by Kotlin maintainers into YouTrack issues for further discussions.

Contributing to existing KEEPs

• For in-progress KEEPs, please keep discussions in the corresponding issue.
• If you find problems with the text or have text correction for merged KEEPs, feel free to create a separate issue or a pull request with the proposed correction.

keep's Issues

Swift-style enums

Swift has the most powerful enum system I've ever seen. This stems from the ability to provide an enumerated value with a tuple, not at declaration, but at usage sites.

For instance, in the form of an SSCnCE:

// In Swift:

enum Intersection {
    case none
    case touching(point: CGPoint, touchesStart: Bool)
    case crossing(point: CGPoint)
}

class Line {
    // Some other vars and funcs like _rawIntersection declared here

    func intersection(with other: Line) -> Intersection {
        if let intersectionPoint = _rawIntersection(with: other) {
            if intersectionPoint == self.startingPoint
                || intersectionPoint == self.endPoint {
                return .touching(point: intersectionPoint, touchesStart: intersectionPoint == self.startingPoint)
            } else {
                return .crossing(point: intersectionPoint)
            }
        } else {
            return .none
        }
    }
}


let intersection = someLine.intersection(with: someOtherLine)
switch intersection {
    case .none: // the .none case has no associated value
        print("So far away...")

    case .touching(_): // Underscore ignores the value
        print("I'm touching you!")

    case .crossing(let point): // let saves the value
        print("Cross my", point, "and hope to die")
}

I don't even know how you'd do this in Kotlin. Maybe with optionals or subclasses or something. But that'd much more cumbersome and much less elegant.

Being able to have all the information you need right there when you need it, with only declaring the enum type and no helper classes or anything, is a very powerful thing. I've designed a datetime formatter, an automatic integer memory management system, a categorized searchable collection, and many other things with a Swift enum as the backend. This would be awesome to have in Kotlin!

Denotable nullability flexible types

https://github.com/Kotlin/KEEP/blob/ccd3548d92c8f827cf5e75c1f87e612a08f683a0/proposals/denotable-nullability-flexible-types.md

Automatic invocation of operator invoke

Kotlin has a great feature to overload invoke operator.
It would be nice to have a compiler automatically deduce when it can be called in an unambiguous way.

Most generic example:

class IsBlank(private val origin: String) {
    fun invoke(): Boolean = origin.isBlank()
}

currently, there a two ways to get boolean value from this:

if (IsBlank("").invoke()) { }
if (IsBlank("")())) { }

it would be nice for a compiler to deduce that invoke operator and use it implicitly, so this would work

if (IsBlank("")) { }

Is this feaure worth a proposal, or this idea is not worth the time?

Parcelize toghother with inheritance.

Hey, I'm unable to create generic structure togother with @parcelize annotation.
I want constructor to be used as construcor for Jason, Room, and Parcelable.

Lets assume we have class

@Parcelize
class Food(var taste: String = "")

Now two solution that come to my mind at first
1.complains that taste have to be var or val, to have usable Parceable constructor

@Parcelize
class FastFood(var callory:String = "", taste: String): Food(taste) // error

2.complains that I have to explicitly ovveride taste - so what are benefits from polymorphism?

@Parcelize
class FastFood(var callory: String = "", var taste: String): Food(taste) // error

How can I use efficiently inheritance together with your library?

Java annotations for Kotlin sugar

Discussion of the proposal in #111

Summary

This proposal adds annotations which enable the use of more Kotlin language
features like extension functions, extension properties, default values, and
property names for Java code.

• @ExtensionFunction / @ExtensionProperty - Turn a static method with at
  least one argument into an extension function or an extension property.
• @ParameterName - An explicit name for parameters.
• @DefaultValue - Default parameter values.

Bound callable references

Discussions about the Bound callable references proposal will be held here.

@udalov is the shepherd for this proposal.

Short description

Bound callable references are expression like foo::bar where foo is itself an expression, not a class. A type of foo::toString would be () -> String for any foo.

See full proposal for more details

Const reference-type function/lambda parameters.

A Function/lambda should be able to take a const parameter which is read-only. This will enable certain optimizations and will remove the need to copy references.

This feature will also enable a lot of gains when value-types are actually implemented in Kotlin but, they're not dependent on the availability of value-types in the language. But it's arguable if this feature depends on the availability of const val reference types (heap object that cannot be changed).

Keyword: Kotlin's const keyword can be used so there's no need to add a new one.

The strawman syntax should make it look like the following:

fun foo(const bar: Bar)...

Extensions to copy maps

Discussions about the Extensions to copy maps will be held here.

Collection Literals

Issue for tracking the pull request for collection literals, #112. Please discuss there.

Kotlin.system should use consistent naming for time measurement methods

within kotlin.system there are the following methods:
fun measureNanoTime(block: () -> Unit): Long
fun measureTimeMillis(block: () -> Unit): Long

in measureNanoTime, the unit of time, nanoseconds is mentioned before Time, while
in measureTimeMillis, the unit of time, milliseconds is mentioned after Time.

Make the naming consistent here, by favoring either one or the other scheme. Suggest:
measureTimeNanos
measureTimeMillis

Sealed class inheritors in the same file

Design proposal

Meta-annotations for Java types enhancement

Discussion for the proposal:
https://github.com/Kotlin/KEEP/blob/jvm-meta-annotations-artifact/proposals/jvm-meta-annotations-artifact.md

PR for comments: #100
YT issue: https://youtrack.jetbrains.com/issue/KT-23812

Feedback is very welcome, especially about the remaing questions section

Constant inlining

I don't see a KEEP for constant inlining so maybe there is a better place to ask this question but will this cause problems for large constant values or are String compile-time constants excluded from inlining? e.g. const val PI_TO_1000_DIGITS = "3.14159..."

Provide JSR-310 / Java8 date-handling for every platform

The Java8 date/time-handling library is probably the best out there.
There exists an exact port for JavaScript: https://js-joda.github.io/js-joda/
If there are no license issues, I think kotlin should include this API out of the box on every platform.

Generic values() and valueOf() for enums

Discussion of https://github.com/Kotlin/KEEP/blob/master/proposals/generic-values-and-valueof-for-enums.md

JDK dependent built-ins classes

Proposal

Verify Error for Android Api 19.

Code below works on Api above 19.
Tested on api 19 kitkat, Samsung GT-l9195, doesnt work either on emulator api 19.

Crash code:

Process: app.pck.name, PID: 2746
java.lang.VerifyError: app.pck.name/model/Damage$Creator
at app.pck.name.model.Damage.(Damage.kt)
at java.lang.Class.getDeclaredConstructors(Native Method)
at java.lang.Class.getDeclaredConstructors(Class.java:574)
at com.fasterxml.jackson.databind.util.ClassUtil.getConstructors(ClassUtil.java:1114)
at com.fasterxml.jackson.databind.introspect.AnnotatedCreatorCollector._findPotentialConstructors(AnnotatedCreatorCollector.java:101)
at com.fasterxml.jackson.databind.introspect.AnnotatedCreatorCollector.collect(AnnotatedCreatorCollector.java:56)

@Parcelize
@JsonIgnoreProperties(ignoreUnknown = true)
class Damage @JsonCreator constructor(
        @JsonProperty("eventDate") var date: Date = Date(),
        @JsonProperty("eventHour") var time: String = "",
        @JsonProperty("eventDescription") var description: String? = "",
        @Nullable @JsonProperty("status") var status: EnumStatus? = EnumStatus.REPORTED,
        @JsonProperty("eventType") var eventType: EnumCircumstances = EnumCircumstances.OTHER,
        @Nullable @JsonProperty("carRepairShop") var service: CarService? = null,
        @JsonProperty("processed") var processed: Boolean = false) : Parcelable

Group by key and fold each group simultaneously

Discussions about the Operation to group by key and fold each group simultaneously will be held here.

Delegated Methods

Hi.
We are using Kotlin for implementing realtime game servers, and we use java dynamic proxies heavily. Delegated properties in Kotlin are awesome. I would love to see a feature for delegated methods, which would allow us to implement something similar to java dynamic proxies in a statically typed way. Consider the use case:

interface RemoteService {

    fun doSomethingSwesome(param: String) : String by RemoteInvocationHandler()
}

class RemoteInvocationHandler {
    fun invoke(obj: Any, method: KCallable, params: Array<Any>) {
        //forward invocation to remote service and return result
    }
}

Would love to hear your thoughts on this

[Feature Request] Extending the Kotlin Data Class for use with JPA

I documented the concept in this SO post.

To summarize the idea is to create the simplest possible implementation for equals() and hashcode() usage in the context of JPA that just works all the time without having to read through a myriad of articles and best practices for designing equals() and hashcode() methods.

auto naming param in cases of function declaration and named argument

code it:
<1>

functionX(ClassReader, int offset, InputStream){
    x = classReader.getItem(offset)
    y = inputStream.read(conversion(x))
}

Rule: just lowercase the first char of the type name, except primitive which maybe too naive

Reason: in most java methods people use redundant duplication style, not convenient to write and to read

<2>

functionx(....){
normalizeCase = readConfig(...)
... //other arguments
//now kotlin codes do:
reformat(str,
    normalizeCase = normalizeCase,  //weird
    upperCaseFirstLetter = true,
    divideByCamelHumps = false,
    wordSeparator = '_'
)
//because local name same as param name, it can be ignore
//after new auto-name-match
reformat(str,
    normalizeCase,
    upperCaseFirstLetter,
    divideByCamelHumps,
    wordSeparator
)
}

Rule: auto match and connect local name to argument name
Reason: avoid to be weird and duplication

Both features in my language(C-family-style), it looks good.

Match both position and name in kotlin should not hard.

BTW I doubt auto naming scheme affect reading preference in pascal style(name:type)

Functional types with big arity on JVM

Discussion of the proposal: https://github.com/Kotlin/KEEP/blob/master/proposals/functional-types-with-big-arity-on-jvm.md

Inlining for property accessors

Proposal

Extending Kotlin API for BigInteger and BigDecimal

Discussions about the Extending Kotlin API for BigInteger and BigDecimal proposal will be held here.

Kotlin Scripting Support

https://github.com/Kotlin/KEEP/blob/master/proposals/scripting-support.md

replaces https://github.com/Kotlin/KEEP/blob/master/proposals/script-definition-template.md

Companion values

Discussion of the proposal: #106

Summary
This proposal provides ability to declare companion val or var and expose implicit visibility of all members associated with type specified in the declaration. This case extends companion behavior at instance level rather than at class level in contrast with companion object declaration.

JSR-305 custom nullability qualifiers

Discussion for the proposal

Underscore for unused parameters

See https://github.com/Kotlin/KEEP/blob/master/proposals/underscore-for-unused-parameters.md

Underscores in numeric literals

Discussion of Underscores in numeric literals KEEP.

apply label to control flow

In java we can write the following code:

//avoid more conditional variable
label: {
       main: while(offset<limit){
            if (doSomething()==ERROR) break label;
            while(true){
                   if(some()) continue main;
             }
       }
      Log("EOF");
      return;
}
completeSomething();

but till kotlin 1.1, label only for single loop. so you must write a single loop to wrapper like this

    //wrapper oneshot loop, just for additional control flow structure
    loop@ for (oneshot in 1..1) {
        for (i in 1..10) {
            println(i)
            if (i == 8) break@loop
        }
        println("next line")
    }
    println("loop@")

wait, As you known, label is applied to lambda, label@{}, the following from kotlin reference

fun foo() {
    ints.forEach lit@ {
        if (it == 0) return@lit
        print(it)
    }
}

So label@{} form can be applied loop.

    loop@ {
        for (i in 1..10) {
            println(i)
            if (i == 8) break@loop
        }
        println("next line")
    }
    println("loop@")

And label if and when is OK as well?

Peek operation for sequences and iterables

Discussions about the onEach operation for sequences and iterables will be held here.

Type aliases

Discussions about the Type aliases proposal will be held here.

@dnpetrov is the shepherd for this proposal.

Destructuring in Lambda Parameters

Proposal

I know how to declare a typealias,but how to use

typealias MyList = MutableList<String>
val list = MyList() // was wrong ?

Opt-in requirements (aka Experimental API support)

Discussion of the proposal:
https://github.com/Kotlin/KEEP/blob/master/proposals/experimental.md

JS - class type at runtime

Ability to retrieve the type of a class at runtime

Use cases / motivation

• Some libraries, like React, Aurelia, Angular, sometimes require that you pass a class type as parameter to a function or other configuration place;
• React uses this to define each component type;
• Dependency injection libraries can use the type to instantiate instances;

Proposed solution

A simple function named typeOf or classOf which retrieves the type of a class.

Actual code workaround

By following one idea of @bashor, I created this method at (https://github.com/danfma/kotlinjs-runtime-extension/blob/master/src/kotlin/runtime/extension/typeOf.kt) which grabs the type of T and retrieve its class (function declaration).

inline fun <reified T> typeOf(): Type<T> {
    var type: Type<T>? = null

    js("var tmp = Kotlin.isType; Kotlin.isType = function(a, b) { type = b }")

    null is T

    js("Kotlin.isType = tmp;")

    return type!!
}

But the code could be broken in any future update, so we need a more concrete way.

Examples of use.

val carType = typeOf<Car>()

• https://github.com/danfma/kotlinjs-react/blob/master/src/react/core/functions.kt
• https://github.com/danfma/kotlinjs-runtime-extension/blob/master/src/kotlin/runtime/extension/container/Container.kt

Coding Conventions of Extension names

Coding Conventions of Extension names

EXTENSION_SHADOWED_BY_MEMBER

If a class has a member function, and an extension function is defined which has the same receiver type, the same name and is applicable to given arguments, the member always wins. This may cause trouble in the future. The extension code that can run is not not compatible with the new version of library that implements a member function with same name.

Same author's Extension

If we define a extension functions/properties for the library we write, use the name start with a lower case letter and use camel humps and no underscores.

class C {
}

// the same author wrote the foo extension
fun C.fooBar() { println("same author's extension") }

Third-party Extension

If we define a extension functions/properties for the library we can't control, use the name start with a underscore followed by a lower case letter and use camel humps and no underscores.

class C {
    fun fooBar() { println("member") }
}

// third-part extension's name should start with underscore
fun C._fooBar() { println("third-part extension") }

Local and top-level lateinit properties

(placeholder issue for discussion)

Script Definition Template

initial proposal for Script Definition Template

*Open issues *

• Controlling access to host app's APIs

Read-only and mutable abstract collections

Discussions about the Read-only and mutable abstract collections will be held here.

Sliding window functions

Discussions about the Sliding window functions will be held here.

Extensions to find all occurrences of a pattern in a CharSequence

Discussions about the Extensions to find all occurrences of a pattern in a CharSequence will be held here.

@Parcelize: Android Studio complains that annotated class is missing CREATOR field

Android Studio 3.0 Beta 4
Kotlin plugin 1.1.4-release-Studio3.0-3

I'm my build.gradle I have:

apply plugin: "org.jetbrains.kotlin.android.extensions"
androidExtensions {
    experimental = true
}

And in a Kotlin class:

@Parcelize
data class SomeObject(val aParcelableObject: AParcelableObject) : Parcelable

SomeObject has the red squigglies beneath it and error text: "This class implements Parcelable but does not provide a CREATOR field"

I tried adding a custom Parceler, but (1) it didn't help and (2) seemed to run contrary to my goal of reducing boilerplate.

Explicit mode for library authoring

Motivation

There were a couple of hot discussions about the default visibility before release:
https://discuss.kotlinlang.org/t/public-by-default-for-classes/110
https://discuss.kotlinlang.org/t/kotlins-default-visibility-should-be-internal/1400

The main concern against public-by-default visibility was that it becomes too easy for library authors to expose something accidentally, release it, and then have to make breaking changes to hide it back.

The proposal

The proposal is to provide an 'Explicit API' mode in the compiler which helps library authoring. Such mode should prevent delivery of unintended public API/ABI to the clients by requiring explicit visibility modifier and explicit return types for public declarations.

See the full proposal text in https://github.com/Kotlin/KEEP/blob/master/proposals/explicit-api-mode.md

Inline classes

Discussion of the proposal:
https://github.com/Kotlin/KEEP/blob/master/proposals/inline-classes.md

Exceptionless string to number conversions

Discussions about the exceptionless string to number conversions will be held here.

Embedded Types

Motivation

class Product(val title: String, val description: String)
class Electronics(title: String, description: String, val memory: Long) : Product(title, description)
class Clothing(title: String, description: String, val size: Long) : Product(title, description)

Everytime when we inherit from a class, you nee to duplicate this
title: String, description: String in child constructor

The proposal

I propose to introduce Embedded Types
Something like embedding in golang

Implementation

Add @Embed annotation
Syntax 1

class Clothing(val size: Long) : @Embed Product

Syntax 2

class Clothing(@Embed product: Product, val size: Long)

In second case, user can pass a Product instance, or he can pass title and description beside size

Will be transformed to

class Clothing(title: String, description: String, val size: Long) : Product(title, description)

Allow base classes for data classes

Proposal

Local delegated properties

Scope control for implicit receivers

Discussion of https://github.com/Kotlin/KEEP/blob/master/proposals/scope-control-for-implicit-receivers.md
See also PR #38