square/kotlinpoet

A Kotlin API for generating .kt source files.

KotlinPoet

KotlinPoet is a Kotlin and Java API for generating .kt source files.

square.github.io/kotlinpoet

License

Copyright 2017 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

kotlinpoet's Issues

Replace java.util.regex with kotlin.text

Switch from j.l.m.Modifier to KVisiblity and friends?

https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.reflect/-k-visibility/index.html

Modifier has things like static which aren't in Kotlin, it lacks internal, and there's things like const and override to contend with. We might want to do KVisibility + our own KModifier.

Missing ability to generate internal constructor

Should be able to emit the following

class Foo @Inject internal constructor() { }

object support

Basically the same as class except no constructors allowed

Using @Throws annotation instead of Java throws syntax

I was checking out sources and stumbled upon usage of the invalid in Kotlin throws syntax. Before fixing it I decided to open the issue since it probably will require api changes.
So there are several options:

• Completely remove addException apis from FunSpec since this syntax is not a part of the language and delegate it to AnnotationSpec

• Leave current api unchanged and convert supplied exceptions to AnnotationSpec internally

• Create a new api

What do you think? I would be happy to fix it.

Split platform-specific helper into their own artifacts.

Thinking kotlinpoet and kotlinpoet-jvm, the latter of which has all the java.* things like Class things, TypeElement things, TypeMirror things, and #105.

DSL for Kotlin generation

In addition to the APIs, it would be great to have a fluent DSL for defining Kotlin files.

Class not calling through to superclass constructor when superclass has a no-arg constructor

val typeBuilder = TypeSpec.classBuilder("Foo").superclass(Bar::class)

This generates class Foo : Bar, which does not compile in Kotlin 1.1.2. I read through the documentation and the TypeSpecTests to try to get some insight, but I found nothing that indicates that I'm omitting a function call that adds the superclass constructor call.

Incorrect array generation for AnnotationSpec params

Example:

@Test fun defaultAnnotation() {
  val name = AnnotationSpecTest.IsAnnotated::class.java.canonicalName
  val element = compilation.elements.getTypeElement(name)
  val annotation = AnnotationSpec.get(element.annotationMirrors[0])

  val taco = TypeSpec.classBuilder("Taco")
      .addAnnotation(annotation)
      .build()
  assertThat(toString(taco)).isEqualTo("""
        |package com.squareup.tacos
        |
        |import com.squareup.kotlinpoet.AnnotationSpecTest
        |import java.lang.Override
        |import kotlin.Double
        |import kotlin.Float
        |
        |@AnnotationSpecTest.HasDefaultsAnnotation(
        |    o = AnnotationSpecTest.Breakfast.PANCAKES,
        |    p = 1701,
        |    f = 11.1,
        |    m = {
        |        9,
        |        8,
        |        1
        |    },
        |    l = Override::class,
        |    j = @AnnotationSpecTest.AnnotationA,
        |    q = @AnnotationSpecTest.AnnotationC("bar"),
        |    r = {
        |        Float::class,
        |        Double::class
        |    }
        |)
        |class Taco
        |""".trimMargin())
}

{} won't work in Kotlin. It has to be arrayOf(), intArrayOf() or something different, hence AnnotationSpec should be aware of the type of the parameter. Would it make sense to capture this info through addMember()?

fun addMember(name: String, type: ClassName, format: String, vararg args: Any)

fun addMember(name: String, type: ClassName, codeBlock: CodeBlock)

Based on the type, and in case there are multiple values for the same name, the builder will be able to generate correct CodeBlock for the array and place it as the first element in the members list.

Please share your thoughts. I might be able to work out a PR this week.

TypeName needs isNullable

superclass generates "extends" instead of ":"

When specifying a superclass on a class builder, the generated class contains the "extends" keyword instead of ":"

val classBuilder = TypeSpec.Companion.classBuilder("Child")
classBuilder.superclass(TypeName.Companion.get(Parent::class))

Produces :
Child extends Parent

Instead of :
Child: Parent

Update KDoc

Rename clazz parameter to `class`?

It's a tiny thing, but autocomplete will show the right name without the ticks and keyword workarounds.

Would you consider a PR?

Flip API signatures to be (name, type) instead of (type, name) ?

For consistency with the language. Plus we could potentially make the type part elided.

Support for local functions

https://kotlinlang.org/docs/reference/functions.html#local-functions

FunSpec.Builder should have something like:

fun addLocalFunction(localFunctionSpec: FunSpec)

Consider adding Filer convenience methods back

kapt compiles kt files generated from processors per comments on #93

Emitting redundant modifiers

TypeSpecTest#annotation emits public for the top-level type but this is the default and shouldn't be emitted.

Annotation use site target support

@field:Foo

Re-tool vararg support

Kotlin lets you have multiple in a single function parameter list.

typealias support

KClass use is converted into java.* in code.

See tests for a lot of examples of this

KClass to TypeName broken ?

In 0.2.0, you could get a TypeName from a KClass with this :

TypeName.Companion.get(String::class)

Which enabled one to get a nullable version of it to define a property with type String? for instance :

TypeName.Companion.get(String::class).asNullable()

This doesn't work anymore, and I can't seem to be able to find a replacement for it in the new version (0.3.0) of TypeName.

Maybe I'm doing something wrong or not looking in the right place ?

Cannot add property to companion object

Attempting to add a property to a companion object causes this error:

Exception in thread "main" java.lang.IllegalStateException: cannot add property val ID: kotlin.String = "id" to COMPANION

The exception is being thrown on line 408 of TypeSpec.kt:
check(kind == Kind.CLASS || kind == Kind.ENUM || kind == Kind.ANNOTATION) { "cannot add property $propertySpec to $kind" }

Is this intentional? If it is, I'm not sure how one is meant to add properties to a companion object.

Thanks! Love the library.

Add Iterable<CodeBlock>.joinToCode helper.

This helps build argument lists the like. Should include optional prefix and suffix strings (and maybe blocks?).

Support KotlinJS external classes

In KotlinJS, declaring a class as external makes all members implicitly external.

Currently the implicit modifiers set for members are not dynamic.

Collapse properties into constructor params when present

When a TypeSpec has constructor params that match it's properties, the properties should be collapsed into the constructor parameters.

This

class Foo(val a: String) {
}

Instead of this:

class Foo(a: String) {
  val a: String
}

Support adding imports for top-level properties and functions.

KotlinFile.Builder.addStaticImport needs a way to import top-level properties.

Add Val + Var to ParameterSpec

Allow us to add parameters to primaryConstructor() which add val/var so we don't have to explicitly add each property on the type itself, or a simple method on the PropertySpec.Builder to specify it goes into primary constructor.

Something like:

addParameter(ParameterSpec.valBuilder(name, valueType)
                                                        .defaultValue(defaultValue) // vals

addParameter(ParameterSpec.varBuilder(name, valueType)
                                                        .defaultValue(defaultValue) // vars

Or

.addProperty(PropertySpec.builder("name", String::class)
            .initializer("name")
            .inPrimaryConstructor()
            .build())

So our outputted code is more concise.

Support top-level fields and functions in KotlinFile

Nested annotations require parenthesis even if empty

@Foo(Bar())
// not
@Foo(Bar)

Support LambdaTypeName

Should have a LambdaTypeName in order to support function parameters and the such.

Inheritance uses "extends" or "implements" keyword, should use :

Right now, kotlinpoet emits the following for inheritance

class MyClassImpl implements MyClass

should be

class MyClassImpl: MyClass

Missing ability to call superclass constructor

Should be able to emit the following:

class Foo: Bar("foo") {
}

Don't emit empty class bodies

class Foo {
}

Initializer block should use `init` keyword

TypeSpec.Builder#initializerBlock currently emits

{ 
  ...
}

should be

init {
  ...
}

Nested annotations shouldn't emit @

@Foo(things = [Bar(), Baz()])
// not
@Foo(things = [@Bar(), @Baz()])

Support multiple type declarations in one KotlinFile

This isn't as taboo as in Java

How to use TypeName to generate nullable primitives?

The docs mention it as a possibility but how exactly is it done?

Incorrect generation for boxed primitives when used as generics

If you read the type SomeClass<Integer> and write it you get SomeClass<Integer> rather than SomeClass<Int>. The generated code compiles but complains that Integer should not be used.

Hide static factories which accept MutableMap from public API

e.g., TypeName.get(TypeMirror, MutableMap)

Collection-like operator behaviors

Give all the builders plusAssign so that we can do things like:

typeBuilder += MethodSpec.builder().stuff().build()

Add KotlinFile.Builder.skipKotlinLangImports

import kotlin.String and others are redundant.
Doesn't matter much for generated code but might be nice to have parity with skipJavaLangImports.

Incorrect syntax when declaring multiple constraints for a generic type parameter

TypeVariableName("T", Comparator::class, Serializable::class) declared for a function will produce the following signature:

fun <T : Comparator & Serializable> getComparator(): T

which doesn't compile. Correct Kotlin syntax is:

fun <T> getComparator(): T where T : Comparator, T : Serializable

Kind.OBJECT can't add property?

Hi, why do check() when adding a single property while addProperties() not?

0.3.0 TypeSpec.kt line:403
fun addProperties(propertySpecs: Iterable) = apply {
this.propertySpecs += propertySpecs
}

fun addProperty(propertySpec: PropertySpec) = apply {
check(kind == Kind.CLASS || kind == Kind.ENUM || kind == Kind.ANNOTATION) {
"cannot add property $propertySpec to $kind"
}
propertySpecs += propertySpec
}

How to use ParameterizedTypeName to generate Class<in Activity>, Class<out Activity>, Class<*>?

Add ability to annotate a file

Add support for

@file:JvmName("TacoUtils")

package com.squareup.tacos

Type is written as fully qualified when made nullable

The following code:

val stringType = ClassName.run { String::class.asClassName() }
KotlinFile.builder("somePackage", "SomeFile.kt")
        .addProperty(PropertySpec.builder("prop1", stringType).build())
        .addProperty(PropertySpec.builder("prop2", stringType.asNullable()).build())
        .build()
        .toString()

generates:

package somePackage

import kotlin.String

val prop1: String

val prop2: kotlin.String?

The type for prop2 became kotlin.String? rather than String?

IntelliJ can't automatically import TypeName, ClassName etc extensions

This might be an issue in Intellij but this does not work in AS 3.0 or Intellij 2017.1.4:

String::class.asClassName()

It doesn't help importing import com.squareup.kotlinpoet.*, import com.squareup.kotlinpoet.ClassName.* or import com.squareup.kotlinpoet.ClassName.Companion.*

This works however:

ClassName.run { String::class.asClassName() }

can't emit primary constructor default parameters

class Foo(val id: String? = null)

Functions with receivers instead of chained builders

In Kotlin DSLs it's a common pattern to provide a factory function taking a function with receiver, which setups the instance being built, so that instead of:

FunSpec.builder("main")
        .addParameter(ArrayTypeName.of(String::class), "args")
        .addStatement("%T(args[0]).greet()", greeterClass)
        .build()

one can write

FunSpec("main") {
    parameter(ArrayTypeName.of(String::class), "args")
    statement("%T(args[0]).greet()", greeterClass))
}

FunSpec has the signature like the following:

fun FunSpec(name: String, init: FunSpec.Builder.() -> Unit): FunSpec = 
    FunSpec.builder(name).apply(init).build()