Companion blocks and extensions

[serras]

This is an issue to discuss companion blocks and extensions. The current full text of the proposal can be found here.

TL;DR (from the text of the proposal)

data class Vector(val x: Double, val y: Double) {
    companion { // companion block
        val Zero: Vector get() = Vector(0.0, 0.0)
    }
}

// companion extension
companion val Vector.UnitX get() = Vector(1.0, 0.0)

• Companion extensions may be defined even if the type doesn't have a companion object or companion block (including types coming from Java).
• Members in companion blocks become static members in supported platforms.
• Companion blocks and extensions take precedence over companion objects in the general case.

[kyay10]

Extension members are not allowed in a companion block

There are some use cases where the companion is used as a namespace for imports like import foo.bar.Baz.someExtension. It is rather niche, so I understand why this wasn't considered. Just highlighting this!

[kyay10]

Only the invoke and of operators may be defined in a companion block.

I feel like this list should be extended. get and set already come to mind. Maybe getValue and setValue, although that's stretching it.

[serras]

Do you have particular use cases in mind?

On get and set, I think that X[1] crosses the boundary on what should be an "object".

On the issue of delegates, I actually think that provideDelegate would be the only reasonable one, since it allows you to create a different instance on each call. However, getValue and setValue are supposed to work on the particular delegate instance -- which is backed by a field -- so I don't think it fits very well on the whole "class member" idea.

[serras]

One small thing: we can always add some of those operators later on. The current list is chosen because we definitely have use cases ("fake" constructors, and collection constructors). If we allow too much, we cannot take it out without a (potentially painful) migration.

[CLOVIS-AI]

I think other operators are used so rarely on companion objects that it's not a very impactful restriction for the first version. At least in the codebases I've worked with, the presence of get and set perfectly correlates with ‘the companion object inherits from an interface’, so this wouldn't be migrated to a companion block anyway.

[kyay10]

That's very fair. My instinct is to look for DSL opportunities, so I dislike restrictions if it seems they can be lifted easily. However, this ultimately doesn't end up mattering much, since this only restricts the incredibly tiny use case of wanting get/set on an externally-defined type.

[tKe]

§1.2.2 (companion blocks, object): companion blocks may not be defined if the enclosing classifier is an object.

Was there a specific rationale not to support companion blocks inside objects? I don't have a use-case specifically in mind but an object would still have a classifier on which you could desire companion functions/properties without wanting to resort to platform-specific annotations such as @JvmStatic.

Would companion extensions still be applicable on an object classifier?

[serras]

Would companion extensions still be applicable on an object classifier?

No. Rule §1.3.2 explicitly forbids this.

Was there a specific rationale not to support companion blocks inside objects?

The main problem is that resolution becomes very complex, since an object T is both an expression and a type at the same time. This also aligns with the current behavior: companion objects cannot be defined inside objects.

[tKe]

I can understand objects not having companion objects as there's no clear distinction between the two. However with the companion blocks and companion members having a well defined higher priority resolution (⌘2.1) should favour the companion member over object member.

You can/could disambiguate between the type T and the object T by by using T as an expression, either wrapping in parenthesis as (T).member or explicitly casting (T as T).member.

object Example {
    fun test() // (1)
    companion {
        @JvmName("staticTest") // assumedly still needed to avoid jvm name clash
        fun test() { } // (2)
    }
}

companion fun Example.test() { }  // (3) shadowed by (2) if defined - possibly shadows (1)?

fun example() {
    Example.test()               // resolves to (2) or (3) if (2) not defined
    (Example as Example).test()  // resolves to (1)
    (Example).test()             // also resolves to (1)
}

obviously having named clashes between

[serras]

It's not only about being able to disambiguate (which you could do with objects and its companion objects), it's also about ensuring that the code remains readable. I think this doesn't cut it, it will end up being a "Kotlin brain teaser" if we're not careful with the design.

[gpopides]

I like the KEEP, i have a question regarding:

Companion extensions may be defined even if the type doesn't have a companion object or companion block (including types coming from Java).

does that mean that we will not be able to have companion extensions for classes that have static fields? e.g BigDecimal?

[CLOVIS-AI]

No, it's the opposite. Companion extensions are designed specifically to allow extensions of companion-less types, like Java classes.

[serras]

Indeed, you can use a companion extension on any class or interface, except for the cases listed in §1.3.2 (no objects, no generics).

[gpopides]

Thanks for the clarification, I misread the sentence so now it's clear

[CLOVIS-AI]

In particular, there is no init block for companion blocks; only initializers in properties therein.

Although the full init block is not available, almost all of its usages can be emulated with

class Foo {
    companion {
        val foo = run {
            // ...
        }
    }
}

On the codebases I work on, this covers all the cases where a Java static init block or Kotlin companion object init block are used.

Still, I'm curious what is the reason for not allowing an init block there, I don't see a technical blocker?

[eav-eav-eav]

Same question here. It's a reasonable use case that you use a temporary variable to initialize multiple static fields:

class Foo {
    companion {
        val a: Int
        val b: Int

        init {
            val p: Pair<Int, Int> = stub()
            a = p.first
            b = p.second
        }
    }
}

[serras]

The main reason to avoid init blocks is because of multiplatform. Not every target platform has the same initialization sequence as the JVM, and we wanted to have a model that felt "natural" each of our targets. The way we try to achieve this is by limiting what you can do for initialization. In particular, it helps me think of platforms in which initialization is done lazily per-property, instead of what the KEEP calls "bulk initialization". In that case run is still OK (and supported), whereas full init block really would require emulation in those "lazily per-property initialization" platforms.

[serras]

Another small gain we get from not having init block is that we can more easily allow moving companion blocks (remember, you can have more than one) around the file, without having to worry that much about initialization order (except ensuring there are no cycles).

[CLOVIS-AI]

To expand on the migration section, would this be a safe migration path?

Initial:

class A {
    companion object {
        @JvmStatic
        fun foo() = 7
    }
}

First step, move static declaration to companion block:

class A {
    companion {
        fun foo() = 7
    }

    @Deprecated("...")
    companion object {
        @Deprecated("...", ReplaceWith("A.foo()`))
        fun foo() = A.foo()
    }
}

and then the usual warning→error→hidden→removal cycle?

If so, library authors that don't have a permanent binary compatibility guarantee can probably do the migration over time. This is probably too breaking a change for the standard library, but it looks doable for Ktor 4 or other libraries.

[serras]

Yes, that is the idea.

[Amejonah1200]

What were the reasons why static has been scrapped?
I find personally that removing object from companion object makes more sense in terms of "composability" (I love that Kotlin has more or less composable modifiers), but I wanted to know about the state of end of discussion about static.

[serras]

Addressing the flaws of companions/statics/class members in Kotlin has been an ongoing effort. Several concerns were raised in the previous iteration, so we decided to go back to the drawing board, and take all that input to understand the goals that we need to pursue. In other words, the previous proposal is now rejected, and this is the "new version".

Let me also address one point about static, and why companion fits a bit better in Kotlin. static is a very overloaded term, because in Kotlin it can describe both the notion of "class member", but also talk about how the code is ultimately compiled. For example, top-level functions are static, in the sense that they become a static member of a class in the JVM. The term companion doesn't have this double function, and is more tied to the idea of "class member".

[SPC-code]

After so many iterations, I can say that I like the proposal a lot. It is obvious that there was a lot of effort to conduct research, and, more importantly, explain its results. The resulting design is very concise and simple. And it does not block further development of new features.

[sandwwraith]

The new design looks nice and elegantly solves static problems, as well as extending existing types. However, the problem of (companion) object as a 'collection of declarations' that is also affected by lack of statics and redundant object instance was not addressed — by leaving namespaces out of the scope. Now you can write class Vector { companion { val Zero = ... } }, and that's great. But what if you do not need a class, and just need some common top-level prefix for your constants/properties? This leaves us with two options:

// 1
object GitSchemas {
  val HTTPS = "https://"
  val SSH = "ssh://"
}

// 2
class GitSchemas private constructor() {
  companion {
       val HTTPS = "https://"
       val SSH = "ssh://"
   }
}

(1) is more aesthetically pleasing, shorter, and less indented. Yet, (2) is more correct: you get rid of unnecessary object allocation and non-static property calls. Sadly, it gives so much StringUtil.java vibes. As Kotlin aims to provide shorter and elegant syntax for correct things, I believe here we should also strive to provide a shorter syntax for the preferred option.

There's a struggle with picking a proper modifier for this, though. First version of the proposal used static modifier and suggested static object GitSchemas for such case, which looks quite weird and was disliked by many people, including me. Second version reused static modifier, but dropped this problem out of the scope. Now, it is suggested to use companion modifier. I agree that it conveys better meaning and allows us to extend the concept without new modifiers. However, it doesn't look that well on the top-level:

companion GitSchemas { // companion to what? package? file? anything?
  val HTTPS = "https://"
  val SSH = "ssh://"
}

There were many suggestions to have namespace modifier instead. But then we'll lose nice cohesion with class Vector { companion { ... } } — unless we use namespace there as well, losing cohesion with existing companion objects, which the current proposal strongly advocates against.
There's no easy way out of this, but I believe this problem deserves some attention nonetheless.

[serras]

IMO, we should differentiate between the (potential) notion of namespace, and that of "companion". In general, a companion should be a declaration that it's accessed through the name of another type. This is why I think we would still have companion fun -- and we may say that simply companion inside a class is a shorthand for companion namespace.

[Amejonah1200]

@sandwwraith but how would that be different from simply companion?

Are namespaces just named companions? Are companions solely a different modifier because they need a type to ac_compan_y with?

[sandwwraith]

but how would that be different from simply companion

That's the neat part — it's not.

We currently do not have top-level companions, and yes, they have nothing to accompany, so we need something slightly different.

[CLOVIS-AI]

I think this proposal is perfectly compatible with the (potential?) future addition of namespaces.

We can add:

namespace Foo {
    // …
}

which implies the existence of

class Foo {
    companion namespace {
        // …
    }
}

which would essentially be the same as the companion {} block.

If that happens, we can just say the companion {} block is just shorthand for companion namespace {} and everything is still cohesive. For example, namespaces can be compiled to a class with only static members and it makes sense with how companion {} is used already.

[SPC-code]

I agree with @sandwwraith. Current companions are essentially namespaces. It makes sense to build the mental model this way. But I also agree with @CLOVIS-AI, companion namespace == companion makes sense because companion is a specific case of a namespace. So, any companion is a namespace. I am not sure if we will have cases for other namespace extensions. If we don't, then keeping companion extension looks good because we won't have a namespace keyword in extension position. But if we do, then we will indeed have two different keywords meaning the same thing for companions which is not good.

[kyay10]

Very minor suggestion:
it'd be nice to have a way to define static members without nesting. The previous proposal allowed:

class Foo {
  static fun foo()
}

I think it'd be nice to have something similar here. This feels rather natural:

class Foo {
  companion fun foo()
}

companion extensions have to be top-level, anyway, so no ambiguities here.

In other words, I propose companion members that operate just like companion extensions, but with no receiver.
Additionally, a companion member should be equivalent to having that member in a companion block instead.
This can be retroactively justified in the future as a more general modifier blocks feature, where you can nest declarations inside a block that's prefixed by modifiers.

[serras]

This has been mentioned several times during our usability study, too. From this iteration we'd like to keep the syntax closer to companion object, but this doesn't close the door to this (sometimes shorter) syntax in the future.

[Kyant0]

It's very useful to generate serializer code in KSP, and we can call Data.serializer directly.