KotlinPoet is a Kotlin and Java API for generating .kt source files.
Source file generation can be useful when doing things such as annotation processing or interacting with metadata files (e.g., database schemas, protocol formats). By generating code, you eliminate the need to write boilerplate while also keeping a single source of truth for the metadata.
Here's a HelloWorld file:
class Greeter(val name: String) {
fun greet() {
println("Hello, $name")
}
}
fun main(vararg args: String) {
Greeter(args[0]).greet()
}And this is the code to generate it with KotlinPoet:
val greeterClass = ClassName("", "Greeter")
val file = FileSpec.builder("", "HelloWorld")
.addType(TypeSpec.classBuilder("Greeter")
.primaryConstructor(FunSpec.constructorBuilder()
.addParameter("name", String::class)
.build())
.addProperty(PropertySpec.builder("name", String::class)
.initializer("name")
.build())
.addFunction(FunSpec.builder("greet")
.addStatement("println(%S)", "Hello, \$name")
.build())
.build())
.addFunction(FunSpec.builder("main")
.addParameter("args", String::class, VARARG)
.addStatement("%T(args[0]).greet()", greeterClass)
.build())
.build()
file.writeTo(System.out)The KDoc catalogs the complete KotlinPoet API, which is inspired by JavaPoet.
Most of KotlinPoet's API uses immutable Kotlin objects. There's also builders, method chaining
and varargs to make the API friendly. KotlinPoet offers models for Kotlin files (FileSpec),
classes, interfaces & objects (TypeSpec), type aliases (TypeAliasSpec),
properties (PropertySpec), functions & constructors (FunSpec), parameters (ParameterSpec) and
annotations (AnnotationSpec).
But the body of methods and constructors is not modeled. There's no expression class, no statement class or syntax tree nodes. Instead, KotlinPoet uses strings for code blocks, and you can take advantage of Kotlin's multiline strings to make this look nice:
val main = FunSpec.builder("main")
.addCode("""
|var total = 0
|for (i in 0 until 10) {
| total += i
|}
|""".trimMargin())
.build()Which generates this:
fun main() {
var total = 0
for (i in 0 until 10) {
total += i
}
}There are additional APIs to assist with newlines, braces and indentation:
val main = FunSpec.builder("main")
.addStatement("var total = 0")
.beginControlFlow("for (i in 0 until 10)")
.addStatement("total += i")
.endControlFlow()
.build()This example is lame because the generated code is constant! Suppose instead of just adding 0 to 10, we want to make the operation and range configurable. Here's a method that generates a method:
private fun computeRange(name: String, from: Int, to: Int, op: String): FunSpec {
return FunSpec.builder(name)
.returns(Int::class)
.addStatement("var result = 1")
.beginControlFlow("for (i in $from until $to)")
.addStatement("result = result $op i")
.endControlFlow()
.addStatement("return result")
.build()
}And here's what we get when we call computeRange("multiply10to20", 10, 20, "*"):
fun multiply10to20(): kotlin.Int {
var result = 1
for (i in 10 until 20) {
result = result * i
}
return result
}Methods generating methods! And since KotlinPoet generates source instead of bytecode, you can read through it to make sure it's right.
When emitting code that includes string literals, we can use %S to emit a string, complete
with wrapping quotation marks and escaping. Here's a program that emits 3 methods, each of which
returns its own name:
fun main(args: Array<String>) {
val helloWorld = TypeSpec.classBuilder("HelloWorld")
.addFunction(whatsMyNameYo("slimShady"))
.addFunction(whatsMyNameYo("eminem"))
.addFunction(whatsMyNameYo("marshallMathers"))
.build()
val kotlinFile = FileSpec.builder("com.example.helloworld", "HelloWorld")
.addType(helloWorld)
.build()
kotlinFile.writeTo(System.out)
}
private fun whatsMyNameYo(name: String): FunSpec {
return FunSpec.builder(name)
.returns(String::class)
.addStatement("return %S", name)
.build()
}In this case, using %S gives us quotation marks:
class HelloWorld {
fun slimShady(): String = "slimShady"
fun eminem(): String = "eminem"
fun marshallMathers(): String = "marshallMathers"
}KotlinPoet has rich built-in support for types, including automatic generation of import
statements. Just use %T to reference types:
val today = FunSpec.builder("today")
.returns(Date::class)
.addStatement("return %T()", Date::class)
.build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
.addFunction(today)
.build()
val kotlinFile = FileSpec.builder("com.example.helloworld", "HelloWorld")
.addType(helloWorld)
.build()
kotlinFile.writeTo(System.out)That generates the following .kt file, complete with the necessary import:
package com.example.helloworld
import java.util.Date
class HelloWorld {
fun today(): Date = Date()
}We passed Date::class to reference a class that just-so-happens to be available when we're
generating code. This doesn't need to be the case. Here's a similar example, but this one
references a class that doesn't exist (yet):
val hoverboard = ClassName("com.mattel", "Hoverboard")
val tomorrow = FunSpec.builder("tomorrow")
.returns(hoverboard)
.addStatement("return %T()", hoverboard)
.build()And that not-yet-existent class is imported as well:
package com.example.helloworld
import com.mattel.Hoverboard
class HelloWorld {
fun tomorrow(): Hoverboard = Hoverboard()
}The ClassName type is very important, and you'll need it frequently when you're using KotlinPoet.
It can identify any declared class. Declared types are just the beginning of Kotlin's rich type
system: we also have arrays, parameterized types, wildcard types, lambda types and type variables.
KotlinPoet has classes for building each of these:
val hoverboard = ClassName("com.mattel", "Hoverboard")
val list = ClassName("kotlin.collections", "List")
val arrayList = ClassName("kotlin.collections", "ArrayList")
val listOfHoverboards = list.parameterizedBy(hoverboard)
val arrayListOfHoverboards = arrayList.parameterizedBy(hoverboard)
val beyond = FunSpec.builder("beyond")
.returns(listOfHoverboards)
.addStatement("val result = %T()", arrayListOfHoverboards)
.addStatement("result += %T()", hoverboard)
.addStatement("result += %T()", hoverboard)
.addStatement("result += %T()", hoverboard)
.addStatement("return result")
.build()KotlinPoet will decompose each type and import its components where possible.
package com.example.helloworld
import com.mattel.Hoverboard
import kotlin.collections.ArrayList
import kotlin.collections.List
class HelloWorld {
fun beyond(): List<Hoverboard> {
val result = ArrayList<Hoverboard>()
result += Hoverboard()
result += Hoverboard()
result += Hoverboard()
return result
}
}Generated code is often self-referential. Use %N to refer to another generated declaration by
its name. Here's a method that calls another:
fun byteToHex(b: Int): String {
val result = CharArray(2)
result[0] = hexDigit((b ushr 4) and 0xf)
result[1] = hexDigit(b and 0xf)
return String(result)
}
fun hexDigit(i: Int): Char {
return (if (i < 10) i + '0'.toInt() else i - 10 + 'a'.toInt()).toChar()
}When generating the code above, we pass the hexDigit() method as an argument to the byteToHex()
method using %N:
val hexDigit = FunSpec.builder("hexDigit")
.addParameter("i", Int::class)
.returns(Char::class)
.addStatement("return (if (i < 10) i + '0'.toInt() else i - 10 + 'a'.toInt()).toChar()")
.build()
val byteToHex = FunSpec.builder("byteToHex")
.addParameter("b", Int::class)
.returns(String::class)
.addStatement("val result = CharArray(2)")
.addStatement("result[0] = %N((b ushr 4) and 0xf)", hexDigit)
.addStatement("result[1] = %N(b and 0xf)", hexDigit)
.addStatement("return String(result)")
.build()Although Kotlin's string templates usually work well in cases when you want to include literals into
generated code, KotlinPoet offers additional syntax inspired-by but incompatible-with
String.format(). It accepts %L to emit a literal value in the output. This
works just like Formatter's %s:
private fun computeRange(name: String, from: Int, to: Int, op: String): FunSpec {
return FunSpec.builder(name)
.returns(Int::class)
.addStatement("var result = 0")
.beginControlFlow("for (i in %L until %L)", from, to)
.addStatement("result = result %L i", op)
.endControlFlow()
.addStatement("return result")
.build()
}Literals are emitted directly to the output code with no escaping. Arguments for literals may be strings, primitives, and a few KotlinPoet types described below.
Code blocks may specify the values for their placeholders in a few ways. Only one style may be used for each operation on a code block.
Pass an argument value for each placeholder in the format string to CodeBlock.add(). In each
example, we generate code to say "I ate 3 tacos"
CodeBlock.builder().add("I ate %L %L", 3, "tacos")Place an integer index (1-based) before the placeholder in the format string to specify which argument to use.
CodeBlock.builder().add("I ate %2L %1L", "tacos", 3)Use the syntax %argumentName:X where X is the format character and call CodeBlock.addNamed()
with a map containing all argument keys in the format string. Argument names use characters in
a-z, A-Z, 0-9, and _, and must start with a lowercase character.
val map = LinkedHashMap<String, Any>()
map += "food" to "tacos"
map += "count" to 3
CodeBlock.builder().addNamed("I ate %count:L %food:L", map)All of the above functions have a code body. Use KModifier.ABSTRACT to get a function without any
body. This is only legal if it is enclosed by an abstract class or an interface.
val flux = FunSpec.builder("flux")
.addModifiers(KModifier.ABSTRACT, KModifier.PROTECTED)
.build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
.addModifiers(KModifier.ABSTRACT)
.addFunction(flux)
.build()Which generates this:
abstract class HelloWorld {
protected abstract fun flux()
}The other modifiers work where permitted.
Methods also have parameters, varargs, KDoc, annotations, type variables, return type and receiver
type for extension functions. All of these are configured with FunSpec.Builder.
Also, KotlinPoet can recognize single-expression functions and print them out properly. It treats
each function with a body that starts with return as a single-expression function:
val abs = FunSpec.builder("abs")
.receiver(Int::class)
.returns(Int::class)
.addStatement("return if (this < 0) -this else this")
.build()Which outputs:
fun Int.abs(): Int = if (this < 0) -this else thisFunSpec is a slight misnomer; it can also be used for constructors:
val flux = FunSpec.constructorBuilder()
.addParameter("greeting", String::class)
.addStatement("this.%N = %N", "greeting", "greeting")
.build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
.addProperty("greeting", String::class, KModifier.PRIVATE)
.addFunction(flux)
.build()Which generates this:
class HelloWorld {
private val greeting: String
constructor(greeting: String) {
this.greeting = greeting
}
}For the most part, constructors work just like methods. When emitting code, KotlinPoet will place constructors before methods in the output file.
Often times you'll need to generate the primary constructor for a class:
val helloWorld = TypeSpec.classBuilder("HelloWorld")
.primaryConstructor(flux)
.addProperty("greeting", String::class, KModifier.PRIVATE)
.build()This code, however, generates the following:
class HelloWorld(greeting: String) {
private val greeting: String
init {
this.greeting = greeting
}
}By default, KotlinPoet won't merge primary constructor parameters and properties, even if they share the same name. To achieve the effect, you have to tell KotlinPoet that the property is initialized via the constructor parameter:
val flux = FunSpec.constructorBuilder()
.addParameter("greeting", String::class)
.build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
.primaryConstructor(flux)
.addProperty(PropertySpec.builder("greeting", String::class)
.initializer("greeting")
.addModifiers(KModifier.PRIVATE)
.build())
.build()Now we're getting the following output:
class HelloWorld(private val greeting: String)Notice that KotlinPoet omits {} for classes with empty bodies.
Declare parameters on methods and constructors with either ParameterSpec.builder() or
FunSpec's convenient addParameter() API:
val android = ParameterSpec.builder("android", String::class)
.build()
val welcomeOverlords = FunSpec.builder("welcomeOverlords")
.addParameter(android)
.addParameter("robot", String::class)
.build()Though the code above to generate android and robot parameters is different, the output is the
same:
fun welcomeOverlords(android: String, robot: String) {
}The extended Builder form is necessary when the parameter has annotations (such as @Inject).
Like parameters, properties can be created either with builders or by using convenient helper methods:
val android = PropertySpec.builder("android", String::class)
.addModifiers(KModifier.PRIVATE)
.build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
.addProperty(android)
.addProperty("robot", String::class, KModifier.PRIVATE)
.build()Which generates:
class HelloWorld {
private val android: String
private val robot: String
}The extended Builder form is necessary when a field has KDoc, annotations, or a field
initializer. Field initializers use the same String.format()-like syntax as the code
blocks above:
val android = PropertySpec.builder("android", String::class)
.addModifiers(KModifier.PRIVATE)
.initializer("%S + %L", "Oreo v.", 8.1)
.build()Which generates:
private val android: String = "Oreo v." + 8.1By default PropertySpec.Builder produces val properties. Use PropertySpec.varBuilder() if you
need a var:
val android = PropertySpec.varBuilder("android", String::class)
.addModifiers(KModifier.PRIVATE)
.initializer("%S + %L", "Oreo v.", 8.1)
.build()KotlinPoet has no trouble with interfaces. Note that interface methods must always be ABSTRACT.
The modifier is necessary when defining the interface:
val helloWorld = TypeSpec.interfaceBuilder("HelloWorld")
.addProperty("buzz", String::class)
.addFunction(FunSpec.builder("beep")
.addModifiers(KModifier.ABSTRACT)
.build())
.build()But these modifiers are omitted when the code is generated. These are the defaults so we don't need
to include them for kotlinc's benefit!
interface HelloWorld {
val buzz: String
fun beep()
}KotlinPoet supports objects:
val helloWorld = TypeSpec.objectBuilder("HelloWorld")
.addProperty(PropertySpec.builder("buzz", String::class)
.initializer("%S", "buzz")
.build())
.addFunction(FunSpec.builder("beep")
.addStatement("println(%S)", "Beep!")
.build())
.build()Similarly, you can create companion objects and add them to classes using addType():
val companion = TypeSpec.companionObjectBuilder()
.addProperty(PropertySpec.builder("buzz", String::class)
.initializer("%S", "buzz")
.build())
.addFunction(FunSpec.builder("beep")
.addStatement("println(%S)", "Beep!")
.build())
.build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
.addType(companion)
.build()You can provide an optional name for a companion object.
Use enumBuilder to create the enum type, and addEnumConstant() for each value:
val helloWorld = TypeSpec.enumBuilder("Roshambo")
.addEnumConstant("ROCK")
.addEnumConstant("SCISSORS")
.addEnumConstant("PAPER")
.build()To generate this:
enum class Roshambo {
ROCK,
SCISSORS,
PAPER
}Fancy enums are supported, where the enum values override methods or call a superclass constructor. Here's a comprehensive example:
val helloWorld = TypeSpec.enumBuilder("Roshambo")
.primaryConstructor(FunSpec.constructorBuilder()
.addParameter("handsign", String::class)
.build())
.addEnumConstant("ROCK", TypeSpec.anonymousClassBuilder()
.addSuperclassConstructorParameter("%S", "fist")
.addFunction(FunSpec.builder("toString")
.addModifiers(KModifier.OVERRIDE)
.addStatement("return %S", "avalanche!")
.returns(String::class)
.build())
.build())
.addEnumConstant("SCISSORS", TypeSpec.anonymousClassBuilder()
.addSuperclassConstructorParameter("%S", "peace")
.build())
.addEnumConstant("PAPER", TypeSpec.anonymousClassBuilder()
.addSuperclassConstructorParameter("%S", "flat")
.build())
.addProperty(PropertySpec.builder("handsign", String::class, KModifier.PRIVATE)
.initializer("handsign")
.build())
.build()Which generates this:
enum class Roshambo(private val handsign: String) {
ROCK("fist") {
override fun toString(): String = "avalanche!"
},
SCISSORS("peace"),
PAPER("flat");
}In the enum code, we used TypeSpec.anonymousClassBuilder(). Anonymous inner classes can also be
used in code blocks. They are values that can be referenced with %L:
val comparator = TypeSpec.anonymousClassBuilder()
.addSuperinterface(Comparator::class.parameterizedBy(String::class))
.addFunction(FunSpec.builder("compare")
.addModifiers(KModifier.OVERRIDE)
.addParameter("a", String::class)
.addParameter("b", String::class)
.returns(Int::class)
.addStatement("return %N.length - %N.length", "a", "b")
.build())
.build()
val helloWorld = TypeSpec.classBuilder("HelloWorld")
.addFunction(FunSpec.builder("sortByLength")
.addParameter("strings", List::class.parameterizedBy(String::class))
.addStatement("%N.sortedWith(%L)", "strings", comparator)
.build())
.build()This generates a method that contains a class that contains a method:
class HelloWorld {
fun sortByLength(strings: List<String>) {
strings.sortedWith(object : Comparator<String> {
override fun compare(a: String, b: String): Int = a.length - b.length
})
}
}One particularly tricky part of defining anonymous inner classes is the arguments to the superclass
constructor. To pass them use TypeSpec.Builder's addSuperclassConstructorParameter() method.
Simple annotations are easy:
val test = FunSpec.builder("test string equality")
.addAnnotation(Test::class)
.addStatement("assertThat(%1S).isEqualTo(%1S)", "foo")
.build()Which generates this function with an @Test annotation:
@Test
fun `test string equality`() {
assertThat("foo").isEqualTo("foo")
}Use AnnotationSpec.builder() to set properties on annotations:
val logRecord = FunSpec.builder("recordEvent")
.addModifiers(KModifier.ABSTRACT)
.addAnnotation(AnnotationSpec.builder(Headers::class)
.addMember("accept = %S", "application/json; charset=utf-8")
.addMember("userAgent = %S", "Square Cash")
.build())
.addParameter("logRecord", LogRecord::class)
.returns(LogReceipt::class)
.build()Which generates this annotation with accept and userAgent properties:
@Headers(
accept = "application/json; charset=utf-8",
userAgent = "Square Cash"
)
abstract fun recordEvent(logRecord: LogRecord): LogReceiptWhen you get fancy, annotation values can be annotations themselves. Use %L for embedded
annotations:
val headerList = ClassName("", "HeaderList")
val header = ClassName("", "Header")
val logRecord = FunSpec.builder("recordEvent")
.addModifiers(KModifier.ABSTRACT)
.addAnnotation(AnnotationSpec.builder(headerList)
.addMember(
"[\n%>%L,\n%L%<\n]",
AnnotationSpec.builder(header)
.addMember("name = %S", "Accept")
.addMember("value = %S", "application/json; charset=utf-8")
.build(),
AnnotationSpec.builder(header)
.addMember("name = %S", "User-Agent")
.addMember("value = %S", "Square Cash")
.build())
.build())
.addParameter("logRecord", logRecordName)
.returns(logReceipt)
.build()Which generates this:
@HeaderList([
Header(name = "Accept", value = "application/json; charset=utf-8"),
Header(name = "User-Agent", value = "Square Cash")
])
abstract fun recordEvent(logRecord: LogRecord): LogReceiptKotlinPoet supports use-site targets for annotations:
val utils = FileSpec.builder("com.example", "Utils")
.addAnnotation(AnnotationSpec.builder(JvmName::class)
.useSiteTarget(UseSiteTarget.FILE)
.build())
.addFunction(FunSpec.builder("abs")
.receiver(Int::class)
.returns(Int::class)
.addStatement("return if (this < 0) -this else this")
.build())
.build()Will output this:
@file:JvmName
package com.example
import kotlin.Int
import kotlin.jvm.JvmName
fun Int.abs(): Int = if (this < 0) -this else thisKotlinPoet provides API for creating Type Aliases, which supports simple class names, parameterized types and lambdas:
val fileTable = Map::class.asClassName()
.parameterizedBy(TypeVariableName("K"), Set::class.parameterizedBy(File::class))
val predicate = LambdaTypeName.get(parameters = *arrayOf(TypeVariableName("T")),
returnType = Boolean::class.asClassName())
val helloWorld = FileSpec.builder("com.example", "HelloWorld")
.addTypeAlias(TypeAliasSpec.builder("Word", String::class).build())
.addTypeAlias(TypeAliasSpec.builder("FileTable<K>", fileTable).build())
.addTypeAlias(TypeAliasSpec.builder("Predicate<T>", predicate).build())
.build()Which generates the following:
package com.example
import java.io.File
import kotlin.Boolean
import kotlin.String
import kotlin.collections.Map
import kotlin.collections.Set
typealias Word = String
typealias FileTable<K> = Map<K, Set<File>>
typealias Predicate<T> = (T) -> BooleanDownload the latest .jar or depend via Maven:
<dependency>
<groupId>com.squareup</groupId>
<artifactId>kotlinpoet</artifactId>
<version>1.0.0-RC1</version>
</dependency>or Gradle:
compile 'com.squareup:kotlinpoet:1.0.0-RC1'Snapshots of the development version are available in Sonatype's snapshots repository.
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
http://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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent