KotlinPoet

https://github.com/square/kotlinpoet
Admin
KotlinPoet is a Kotlin and Java API for generating .kt source files programmatically.
Tokens:22,277
Snippets:194
Trust Score:9.4
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example KSProperty source class

Source: https://github.com/square/kotlinpoet/blob/main/docs/interop-ksp.md

Example class used throughout the documentation to demonstrate KSP conversions.

```kotlin
class Taco {
  internal inline val seasoning: String get() = "spicy"
}
```

--------------------------------

### Class and function with type parameters

Source: https://github.com/square/kotlinpoet/blob/main/docs/interop-ksp.md

Example class and function with nested type parameters used to demonstrate composing resolvers.

```kotlin
class Taco<T> {
  fun <E> getShellOfType(param1: E, param2: T) {

  }
}
```

--------------------------------

### HelloWorld target Kotlin source

Source: https://github.com/square/kotlinpoet/blob/main/docs/index.md

The Kotlin source file that the KotlinPoet example generates. It defines a Greeter class with a name property and a greet() function, plus a main function that greets the first command-line argument.

```kotlin
class Greeter(val name: String) {
  fun greet() {
    println("""Hello, $name""")
  }
}

fun main(vararg args: String) {
  Greeter(args[0]).greet()
}
```

--------------------------------

### Create mutable property with mutable()

Source: https://github.com/square/kotlinpoet/blob/main/docs/properties.md

Shows how to create a var property by calling mutable() on PropertySpec.Builder. The example includes a private modifier and an initializer.

```kotlin
val android = PropertySpec.builder("android", String::class)
  .mutable()
  .addModifiers(KModifier.PRIVATE)
  .initializer("%S + %L", "Oreo v.", 8.1)
  .build()
```

--------------------------------

### Class with type parameter

Source: https://github.com/square/kotlinpoet/blob/main/docs/interop-ksp.md

Example class with a type parameter T used to demonstrate TypeParameterResolver.

```kotlin
abstract class Taco<T> {
  abstract val seasoning: T
}
```

--------------------------------

### Generated Function with Single Context Parameter

Source: https://github.com/square/kotlinpoet/blob/main/docs/context-parameters.md

This is the Kotlin code generated by the previous example. The context parameter appears as context(user: kotlin.String) before the public function, and the function body produces the appropriate output.

```kotlin
context(user: kotlin.String)
public fun greet() {
  println("Hello, $user!")
}
```

--------------------------------

### Annotate a type with annotated()

Source: https://github.com/square/kotlinpoet/blob/main/docs/t-for-types.md

Shows how to add an annotation to a type using the annotated() API. The example uses String::class.asTypeName() and builds an AnnotationSpec for MyAnnotation.

```kotlin
val annotatedType = String::class.asTypeName()
  .annotated(AnnotationSpec.builder(MyAnnotation::class).build())
```

--------------------------------

### Generate single-expression function with return body

Source: https://github.com/square/kotlinpoet/blob/main/docs/functions.md

Creates a single-expression function by using a body that starts with return. KotlinPoet recognizes this pattern and prints the function as a single-expression function.

```kotlin
val abs = FunSpec.builder("abs")
  .addParameter("x", Int::class)
  .returns(Int::class)
  .addStatement("return if (x < 0) -x else x")
  .build()
```

```kotlin
fun abs(x: Int): Int = if (x < 0) -x else x
```

--------------------------------

### Named Arguments: CodeBlock.addNamed() with map

Source: https://github.com/square/kotlinpoet/blob/main/docs/code-block-format-strings.md

Uses named arguments with the syntax %argumentName:X and calls CodeBlock.addNamed() with a map containing all argument keys. Argument names use characters in a-z, A-Z, 0-9, and _, and must start with a lowercase character.

```kotlin
val map = LinkedHashMap<String, Any>()
map += "food" to "tacos"
map += "count" to 3
CodeBlock.builder().addNamed("I ate %count:L %food:L", map)
```

--------------------------------

### Add a Single Context Parameter with contextParameter()

Source: https://github.com/square/kotlinpoet/blob/main/docs/context-parameters.md

When you need to add one context parameter to a generated function, use the contextParameter() method on a FunSpec builder, passing the parameter name and type. This example generates a function with a context parameter called 'user' of type kotlin.String. The generated code shows the context applied with the public fun declaration.

```kotlin
val greet = FunSpec.builder("greet")
  .contextParameter("user", String::class)
  .addStatement("println(\"Hello, ${'$'}user!\")")
  .build()
```

--------------------------------

### Build anonymous Comparator with TypeSpec.anonymousClassBuilder()

Source: https://github.com/square/kotlinpoet/blob/main/docs/anonymous-inner-classes.md

Constructs an anonymous inner class implementing Comparator<String> and uses it in a method via %L. The comparator overrides compare() to return the difference in string lengths. This snippet is the setup for generating a HelloWorld class with a sortByLength method.

```kotlin
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()
```

--------------------------------

### Add non-inline setter to property with inline getter

Source: https://github.com/square/kotlinpoet/blob/main/docs/properties.md

Extends the previous example by adding a non-inline setter. The setter uses FunSpec.setterBuilder() with a parameter named 'value'. The generated property has an inline getter and an empty setter.

```kotlin
val android = PropertySpec.builder("android", String::class)
  .mutable()
  .getter(
    FunSpec.getterBuilder()
      .addModifiers(KModifier.INLINE)
      .addStatement("return %S", "foo")
      .build()
  )
  .setter(
    FunSpec.setterBuilder()
      .addParameter("value", String::class)
      .build()
  )
  .build()
```

```kotlin
var android: kotlin.String
  inline get() = "foo"
  set(`value`) {
  }
```

--------------------------------

### KotlinPoet code to generate HelloWorld

Source: https://github.com/square/kotlinpoet/blob/main/docs/index.md

Uses KotlinPoet's FileSpec, TypeSpec, FunSpec, and PropertySpec to generate the HelloWorld.kt file. The greet() function uses the %P format specifier to emit a string template, and the main function uses %T to reference the Greeter class. The generated file is written to System.out.

```kotlin
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(%P)", "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)
```

--------------------------------

### Create a companion object and add it to a class

Source: https://github.com/square/kotlinpoet/blob/main/docs/objects.md

Builds a companion object with a property and function, then adds it to a class using addType().

```kotlin
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()
```

--------------------------------

### Using addStatement and control flow APIs

Source: https://github.com/square/kotlinpoet/blob/main/docs/code-control-flow.md

Use addStatement, beginControlFlow, and endControlFlow to build a method body with proper indentation and braces.

```kotlin
val main = FunSpec.builder("main")
  .addStatement("var total = 0")
  .beginControlFlow("for (i in 0..<10)")
  .addStatement("total += i")
  .endControlFlow()
  .build()
```

--------------------------------

### Annotation with properties

Source: https://github.com/square/kotlinpoet/blob/main/docs/annotations.md

Creates an annotation with `accept` and `userAgent` properties using `AnnotationSpec.builder()`.

```kotlin
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()
```

```kotlin
@Headers(
  accept = "application/json; charset=utf-8",
  userAgent = "Square Cash"
)
abstract fun recordEvent(logRecord: LogRecord): LogReceipt
```

--------------------------------

### Generate a function returning Date with %T

Source: https://github.com/square/kotlinpoet/blob/main/docs/t-for-types.md

Shows how to use %T to reference a class that exists at code-generation time (Date::class). The generated .kt file includes the necessary import and the function body.

```kotlin
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)
```

```kotlin
package com.example.helloworld

import java.util.Date

class HelloWorld {
  fun today(): Date = Date()
}
```

--------------------------------

### Create properties with builder and helper method

Source: https://github.com/square/kotlinpoet/blob/main/docs/properties.md

Shows two ways to create properties: using PropertySpec.builder with modifiers, and using the addProperty helper method on TypeSpec.Builder. Generates a class with two private val properties.

```kotlin
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()
```

```kotlin
class HelloWorld {
  private val android: String

  private val robot: String
}
```

--------------------------------

### Reference members with %M

Source: https://github.com/square/kotlinpoet/blob/main/docs/m-for-members.md

Use MemberName to reference members and the %M placeholder to automatically handle imports in generated code.

```kotlin
val createTaco = MemberName("com.squareup.tacos", "createTaco")
val isVegan = MemberName("com.squareup.tacos", "isVegan")
val file = FileSpec.builder("com.squareup.example", "TacoTest")
  .addFunction(
    FunSpec.builder("main")
      .addStatement("val taco = %M()", createTaco)
      .addStatement("println(taco.%M)", isVegan)
      .build()
  )
  .build()
println(file)
```

```kotlin
package com.squareup.example

import com.squareup.tacos.createTaco
import com.squareup.tacos.isVegan

fun main() {
  val taco = createTaco()
  println(taco.isVegan)
}
```

--------------------------------

### Property with initializer using String.format-like syntax

Source: https://github.com/square/kotlinpoet/blob/main/docs/properties.md

Shows the extended Builder form for a property with a field initializer. The initializer uses String.format-like syntax with %S and %L placeholders. Generates a private val with an initializer expression.

```kotlin
val android = PropertySpec.builder("android", String::class)
  .addModifiers(KModifier.PRIVATE)
  .initializer("%S + %L", "Oreo v.", 8.1)
  .build()
```

```kotlin
private val android: String = "Oreo v." + 8.1
```

--------------------------------

### Create an object with TypeSpec.objectBuilder

Source: https://github.com/square/kotlinpoet/blob/main/docs/objects.md

Builds an object named 'HelloWorld' with a property 'buzz' and a function 'beep'.

```kotlin
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()
```

--------------------------------

### Build parameterized types and STAR with KotlinPoet

Source: https://github.com/square/kotlinpoet/blob/main/docs/t-for-types.md

Shows how to build parameterized types (List, ArrayList, Array with wildcard producer) and use STAR for KClass<*>. The generated file demonstrates how KotlinPoet decomposes types and imports their components.

```kotlin
import com.squareup.kotlinpoet.ParameterizedTypeName.Companion.parameterizedBy
import com.squareup.kotlinpoet.STAR

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 thing = ClassName("com.misc", "Thing")
val array = ClassName("kotlin", "Array")
val producerArrayOfThings = array.parameterizedBy(WildcardTypeName.producerOf(thing))

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()

val printThings = FunSpec.builder("printThings")
  .addParameter("things", producerArrayOfThings)
  .addStatement("println(things)")
  .build()

val printKClass = FunSpec.builder("printKClass")
  .addParameter("kClass", KClass::class.asClassName().parameterizedBy(STAR))
  .addStatement("println(kClass)")
  .build()
```

```kotlin
package com.example.helloworld

import com.mattel.Hoverboard
import com.misc.Thing
import kotlin.Array
import kotlin.collections.ArrayList
import kotlin.collections.List
import kotlin.reflect.KClass

class HelloWorld {
  fun beyond(): List<Hoverboard> {
    val result = ArrayList<Hoverboard>()
    result += Hoverboard()
    result += Hoverboard()
    result += Hoverboard()
    return result
  }

  fun printThings(things: Array<out Thing>) {
    println(things)
  }

  fun printKClass(kClass: KClass<*>) {
    println(kClass)
  }
}
```

--------------------------------

### Create nullable types with copy(nullable = true)

Source: https://github.com/square/kotlinpoet/blob/main/docs/t-for-types.md

Shows how to create a nullable type using copy(nullable = true) and how to add mutable and non-mutable properties. The generated class shows the nullable property with ? and the non-null property without initializer.

```kotlin
val java = PropertySpec.builder("java", String::class.asTypeName().copy(nullable = true))
  .mutable()
  .addModifiers(KModifier.PRIVATE)
  .initializer("null")
  .build()

val helloWorld = TypeSpec.classBuilder("HelloWorld")
  .addProperty(java)
  .addProperty("kotlin", String::class, KModifier.PRIVATE)
  .build()
```

```kotlin
class HelloWorld {
  private var java: String? = null

  private val kotlin: String
}
```

--------------------------------

### Relative Arguments: CodeBlock.add() with %L placeholders

Source: https://github.com/square/kotlinpoet/blob/main/docs/code-block-format-strings.md

Passes arguments positionally to CodeBlock.add() for each placeholder in the format string. The first %L is replaced by 3 and the second by "tacos", producing "I ate 3 tacos".

```kotlin
CodeBlock.builder().add("I ate %L %L", 3, "tacos")
```

--------------------------------

### Emit callable references with constructorReference() and reference()

Source: https://github.com/square/kotlinpoet/blob/main/docs/callable-references.md

Shows how to emit callable references for constructors, functions, and properties using ClassName.constructorReference() and MemberName.reference(). The first block builds a FunSpec that generates the second block's output. Top-level classes and members with conflicting names may require aliased imports, as with member names.

```kotlin
val helloClass = ClassName("com.example.hello", "Hello")
val worldFunction: MemberName = helloClass.member("world")
val byeProperty: MemberName = helloClass.nestedClass("World").member("bye")

val factoriesFun = FunSpec.builder("factories")
  .addStatement("val hello = %L", helloClass.constructorReference())
  .addStatement("val world = %L", worldFunction.reference())
  .addStatement("val bye = %L", byeProperty.reference())
  .build()

FileSpec.builder("com.example", "HelloWorld")
  .addFunction(factoriesFun)
  .build()
```

```kotlin
package com.example

import com.example.hello.Hello

fun factories() {
  val hello = ::Hello
  val world = Hello::world
  val bye = Hello.World::bye
}
```

--------------------------------

### Generate byteToHex and hexDigit with %N

Source: https://github.com/square/kotlinpoet/blob/main/docs/n-for-names.md

The first block shows the target Kotlin functions that the generated code will produce. The second block uses KotlinPoet's FunSpec and %N to generate those functions, passing the hexDigit FunSpec as an argument to byteToHex's statements.

```kotlin
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()
}
```

```kotlin
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()
```

--------------------------------

### Simple annotation

Source: https://github.com/square/kotlinpoet/blob/main/docs/annotations.md

Creates a function with a simple `@Test` annotation.

```kotlin
val test = FunSpec.builder("test string equality")
  .addAnnotation(Test::class)
  .addStatement("assertThat(%1S).isEqualTo(%1S)", "foo")
  .build()
```

```kotlin
@Test
fun `test string equality`() {
  assertThat("foo").isEqualTo("foo")
}
```

--------------------------------

### Using ParameterSpec.builder() and FunSpec.addParameter()

Source: https://github.com/square/kotlinpoet/blob/main/docs/parameters.md

Creates a ParameterSpec with a default value and adds it to a method builder. Also shows adding a simple parameter directly. The generated code demonstrates the resulting function signature with default value.

```kotlin
val android = ParameterSpec.builder("android", String::class)
  .defaultValue("\"pie\"")
  .build()

val welcomeOverlords = FunSpec.builder("welcomeOverlords")
  .addParameter(android)
  .addParameter("robot", String::class)
  .build()
```

```kotlin
fun welcomeOverlords(android: String = "pie", robot: String) {
}
```

--------------------------------

### Generate a function returning a not-yet-existent Hoverboard with ClassName

Source: https://github.com/square/kotlinpoet/blob/main/docs/t-for-types.md

Shows how to reference a class that does not exist yet using ClassName. The generated file imports the not-yet-existent class and uses it in the function.

```kotlin
val hoverboard = ClassName("com.mattel", "Hoverboard")

val tomorrow = FunSpec.builder("tomorrow")
  .returns(hoverboard)
  .addStatement("return %T()", hoverboard)
  .build()
```

```kotlin
package com.example.helloworld

import com.mattel.Hoverboard

class HelloWorld {
  fun tomorrow(): Hoverboard = Hoverboard()
}
```

--------------------------------

### Positional Arguments: CodeBlock.add() with indexed placeholders

Source: https://github.com/square/kotlinpoet/blob/main/docs/code-block-format-strings.md

Uses 1-based integer indices before the placeholder to select which argument to use. Here %2L uses the second argument ("tacos") and %1L uses the first (3), producing "I ate 3 tacos".

```kotlin
CodeBlock.builder().add("I ate %2L %1L", "tacos", 3)
```

--------------------------------

### Secondary constructor with FunSpec.constructorBuilder()

Source: https://github.com/square/kotlinpoet/blob/main/docs/constructors.md

Builds a secondary constructor with FunSpec.constructorBuilder() and attaches it to a class via addFunction(). The generated output shows the constructor placed before the property and method bodies.

```kotlin
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()
```

```kotlin
class HelloWorld {
  private val greeting: String

  constructor(greeting: String) {
    this.greeting = greeting
  }
}
```

--------------------------------

### Generate extension function with receiver()

Source: https://github.com/square/kotlinpoet/blob/main/docs/functions.md

Builds an extension function by specifying a receiver with the receiver() builder method. The generated output shows the resulting extension function on Int.

```kotlin
val square = FunSpec.builder("square")
  .receiver(Int::class)
  .returns(Int::class)
  .addStatement("var s = this * this")
  .addStatement("return s")
  .build()
```

```kotlin
fun Int.square(): Int {
  val s = this * this
  return s
}
```

--------------------------------

### Use-site target annotation

Source: https://github.com/square/kotlinpoet/blob/main/docs/annotations.md

Adds a `@file:JvmName` annotation to a file using `useSiteTarget(UseSiteTarget.FILE)`.

```kotlin
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()
```

```kotlin
@file:JvmName

package com.example

import kotlin.Int
import kotlin.jvm.JvmName

fun Int.abs(): Int = if (this < 0) -this else this
```

--------------------------------

### Generate default function argument with defaultValue()

Source: https://github.com/square/kotlinpoet/blob/main/docs/functions.md

Shows how to declare a default value for a function argument using the defaultValue() builder function. The first block is the target function with a default argument, and the second block is the KotlinPoet code that generates it.

```kotlin
fun add(a: Int, b: Int = 0) {
  print("a + b = ${a + b}")
}
```

```kotlin
FunSpec.builder("add")
  .addParameter("a", Int::class)
  .addParameter(
    ParameterSpec.builder("b", Int::class)
      .defaultValue("%L", 0)
      .build()
  )
  .addStatement("print(\"a + b = ${a + b}\")")
  .build()
```

--------------------------------

### Using addCode with multiline string

Source: https://github.com/square/kotlinpoet/blob/main/docs/code-control-flow.md

Use addCode with a trimmed multiline string to write a method body. The generated code shows the resulting function.

```kotlin
val main = FunSpec.builder("main")
  .addCode("""
    |var total = 0
    |for (i in 0..<10) {
    |    total += i
    |}
    |""".trimMargin())
  .build()
```

```kotlin
fun main() {
  var total = 0
  for (i in 0..<10) {
    total += i
  }
}
```

--------------------------------

### Generated Kotlin code for HelloWorld with anonymous Comparator

Source: https://github.com/square/kotlinpoet/blob/main/docs/anonymous-inner-classes.md

Shows the output of the previous KotlinPoet code: a HelloWorld class with a sortByLength method that uses an anonymous Comparator<String> to sort strings by length. This is the generated code, not the builder code.

```kotlin
class HelloWorld {
  fun sortByLength(strings: List<String>) {
    strings.sortedWith(object : Comparator<String> {
      override fun compare(a: String, b: String): Int = a.length - b.length
    })
  }
}
```

--------------------------------

### Use %L to emit literals in generated code

Source: https://github.com/square/kotlinpoet/blob/main/docs/l-for-literals.md

Shows how to use %L in addStatement and beginControlFlow to insert literal values (from, to, op) directly into generated code. Literals are emitted without escaping and can be strings, primitives, or certain KotlinPoet types.

```kotlin
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..<%L)", from, to)
    .addStatement("result = result %L i", op)
    .endControlFlow()
    .addStatement("return result")
    .build()
}
```

--------------------------------

### Use CodeBlock with %P for importable members in KotlinPoet

Source: https://github.com/square/kotlinpoet/blob/main/docs/p-for-string-templates.md

Use CodeBlock arguments with %P to reference importable types or members inside a string template. The first block builds a FileSpec with a function that uses %P and a CodeBlock with a MemberName, and the second shows the generated output with proper imports.

```kotlin
val file = FileSpec.builder("com.example", "Digits")
  .addFunction(
    FunSpec.builder("print")
      .addParameter("digits", IntArray::class)
      .addStatement("println(%P)", buildCodeBlock {
        val contentToString = MemberName("kotlin.collections", "contentToString")
        add("These are the digits: \${digits.%M()}", contentToString)
      })
      .build()
  )
  .build()
println(file)
```

```kotlin
package com.example

import kotlin.IntArray
import kotlin.collections.contentToString

fun print(digits: IntArray) {
  println("""These are the digits: ${digits.contentToString()}""")
}
```

--------------------------------

### Generate string templates with %P in KotlinPoet

Source: https://github.com/square/kotlinpoet/blob/main/docs/p-for-string-templates.md

Use %P to generate string templates without escaping dollar signs. The first block builds a FunSpec with addStatement("return %P", ...) and the second shows the resulting function with an unescaped $amount template.

```kotlin
val amount = 50
val stringWithADollar = "Your total is " + "$" + "amount"
val funSpec = FunSpec.builder("printTotal")
  .returns(String::class)
  .addStatement("return %P", stringWithADollar)
  .build()
```

```kotlin
fun printTotal(): String = "Your total is $amount"
```

--------------------------------

### Add Multiple Context Parameters using ContextParameter

Source: https://github.com/square/kotlinpoet/blob/main/docs/context-parameters.md

To add several context parameters to a function, create ContextParameter objects and pass them to the contextParameter method multiple times. Types can be specified via ClassName instances. The generated function includes all context parameters in order.

```kotlin
val loggerType = ClassName("java.util.logging", "Logger")
val configType = ClassName("com.example", "Config")

val logger = ContextParameter("logger", loggerType)
val config = ContextParameter("config", configType)

val processData = FunSpec.builder("processData")
  .contextParameter(logger)
  .contextParameter(config)
  .addStatement("%N.info(\"Processing with config: ${'$'}%N\")", logger, config)
  .build()
```

--------------------------------

### Generating a method with configurable range and operation

Source: https://github.com/square/kotlinpoet/blob/main/docs/code-control-flow.md

A method that generates a FunSpec with configurable name, range, and operation. The generated code shows the result of calling computeRange("multiply10to20", 10, 20, "*").

```kotlin
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..<$to)")
    .addStatement("result = result $op i")
    .endControlFlow()
    .addStatement("return result")
    .build()
}
```

```kotlin
fun multiply10to20(): kotlin.Int {
  var result = 1
  for (i in 10..<20) {
    result = result * i
  }
  return result
}
```

--------------------------------

### Create type aliases with TypeAliasSpec

Source: https://github.com/square/kotlinpoet/blob/main/docs/type-aliases.md

Builds a FileSpec with three type aliases: Word (simple), FileTable (parameterized with type variable K), and Predicate (lambda type). The generated code shows the corresponding typealias declarations.

```kotlin
val k = TypeVariableName("K")
val t = TypeVariableName("T")

val fileTable = Map::class.asClassName()
  .parameterizedBy(k, Set::class.parameterizedBy(File::class))

val predicate = LambdaTypeName.get(
  parameters = arrayOf(t),
  returnType = Boolean::class.asClassName()
)
val helloWorld = FileSpec.builder("com.example", "HelloWorld")
  .addTypeAlias(TypeAliasSpec.builder("Word", String::class).build())
  .addTypeAlias(
    TypeAliasSpec.builder("FileTable", fileTable)
      .addTypeVariable(k)
      .build()
  )
  .addTypeAlias(
    TypeAliasSpec.builder("Predicate", predicate)
      .addTypeVariable(t)
      .build()
  )
  .build()
```

```kotlin
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) -> Boolean
```

--------------------------------

### Convert Visibility to KModifier

Source: https://github.com/square/kotlinpoet/blob/main/docs/interop-ksp.md

Converts a KSP Visibility to a KModifier. The comment shows the expected result: KModifier.INTERNAL.

```kotlin
// returns `KModifier.INTERNAL`
seasoningKsProperty.getVisibility().toKModifier()
```

--------------------------------

### Generated Function with Multiple Context Parameters

Source: https://github.com/square/kotlinpoet/blob/main/docs/context-parameters.md

KotlinPoet generates this function with two context parameters, context(logger: com.example.Logger, config: com.example.Config), and the function body references both parameters. Notice the context parameters are listed in the order they were added.

```kotlin
context(logger: com.example.Logger, config: com.example.Config)
public fun processData() {
  logger.info("Processing with config: $config")
}
```

--------------------------------

### Add originating KSFile to FunSpec

Source: https://github.com/square/kotlinpoet/blob/main/docs/interop-ksp.md

Adds an originating KSFile to a FunSpec builder for incremental processing support.

```kotlin
val functionBuilder = FunSpec.builder("sayHello")
  .addOriginatingKSFile(sourceKsFile)
  .build()
```

--------------------------------

### Generate abstract function with KModifier.ABSTRACT

Source: https://github.com/square/kotlinpoet/blob/main/docs/functions.md

Creates an abstract function with the ABSTRACT and PROTECTED modifiers and places it in an abstract class. The generated output shows the abstract class with the protected abstract function.

```kotlin
val flux = FunSpec.builder("flux")
  .addModifiers(KModifier.ABSTRACT, KModifier.PROTECTED)
  .build()

val helloWorld = TypeSpec.classBuilder("HelloWorld")
  .addModifiers(KModifier.ABSTRACT)
  .addFunction(flux)
  .build()
```

```kotlin
abstract class HelloWorld {
  protected abstract fun flux()
}
```

--------------------------------

### Annotating types with annotated()

Source: https://github.com/square/kotlinpoet/blob/main/docs/annotations.md

Shows various ways to add annotations to types using the `annotated()` API.

```kotlin
// Add a single annotation.
val annotatedType = String::class.asTypeName()
  .annotated(AnnotationSpec.builder(MyAnnotation::class).build())

// Add multiple annotations.
val multiAnnotatedType = Int::class.asTypeName()
  .annotated(
    AnnotationSpec.builder(Suppress::class).addMember("%S", "unused").build(),
    AnnotationSpec.builder(Deprecated::class).addMember("%S", "Use something else").build()
  )

// Add annotations by class.
val simpleAnnotated = String::class.asTypeName().annotated(Suppress::class, Deprecated::class)

// Chain multiple calls.
val chainedAnnotations = String::class.asTypeName()
  .annotated(Suppress::class)
  .annotated(Deprecated::class)
```

--------------------------------

### Primary constructor with primaryConstructor()

Source: https://github.com/square/kotlinpoet/blob/main/docs/constructors.md

Uses primaryConstructor() to generate a primary constructor. The output shows that KotlinPoet does not merge the constructor parameter with the property by default, resulting in an init block that assigns the parameter.

```kotlin
val helloWorld = TypeSpec.classBuilder("HelloWorld")
  .primaryConstructor(flux)
  .addProperty("greeting", String::class, KModifier.PRIVATE)
  .build()
```

```kotlin
class HelloWorld(greeting: String) {
  private val greeting: String

  init {
    this.greeting = greeting
  }
}
```

--------------------------------

### Maven dependency for kotlinpoet-jvm

Source: https://github.com/square/kotlinpoet/blob/main/docs/index.md

Adds the kotlinpoet-jvm artifact from com.squareup as a Maven dependency. Replace [version] with the desired version.

```xml
<dependency>
  <groupId>com.squareup</groupId>
  <artifactId>kotlinpoet-jvm</artifactId>
  <version>[version]</version>
</dependency>
```

--------------------------------

### Define an interface with KotlinPoet

Source: https://github.com/square/kotlinpoet/blob/main/docs/interfaces.md

Use TypeSpec.interfaceBuilder() to create an interface. Interface methods must be marked with KModifier.ABSTRACT, though these modifiers are omitted in the generated code.

```kotlin
val helloWorld = TypeSpec.interfaceBuilder("HelloWorld")
  .addProperty("buzz", String::class)
  .addFunction(
    FunSpec.builder("beep")
      .addModifiers(KModifier.ABSTRACT)
      .build()
  )
  .build()
```

```kotlin
interface HelloWorld {
  val buzz: String

  fun beep()
}
```

--------------------------------

### Add kotlinpoet-ksp dependency

Source: https://github.com/square/kotlinpoet/blob/main/docs/interop-ksp.md

Add the kotlinpoet-ksp dependency to your Gradle build to use the KSP interop API.

```kotlin
dependencies {
  implementation("com.squareup:kotlinpoet-ksp:<version>")
}
```

--------------------------------

### Write FileSpec to CodeGenerator

Source: https://github.com/square/kotlinpoet/blob/main/docs/interop-ksp.md

Writes a FileSpec to a KSP CodeGenerator using the extension function. This call also collects originating files and requires an aggregating parameter.

```kotlin
fileSpec.writeTo(codeGenerator)
```

--------------------------------

### Convert metadata to TypeSpec and FileSpec

Source: https://github.com/square/kotlinpoet/blob/main/docs/interop-kotlin-metadata.md

Converts a Taco class to KotlinPoet's TypeSpec via toTypeSpec() and FileSpec via toFileSpec(). This generates stub source representations of the underlying API.

```kotlin
data class Taco(val seasoning: String, val soft: Boolean) {
  fun prepare() {
  }
}

val typeSpec = Taco::class.toTypeSpec()

// Or FileSpec
val fileSpec = Taco::class.toFileSpec()
```

--------------------------------

### Use %S to emit quoted string literals in KotlinPoet

Source: https://github.com/square/kotlinpoet/blob/main/docs/s-for-strings.md

When emitting code that includes string literals, %S emits a string with wrapping quotation marks and escaping. The program builds a HelloWorld class with three methods that return their own names using addStatement("return %S", name). The second block shows the generated output with quoted return values.

```kotlin
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()
}
```

```kotlin
class HelloWorld {
  fun slimShady(): String = "slimShady"

  fun eminem(): String = "eminem"

  fun marshallMathers(): String = "marshallMathers"
}
```

--------------------------------

### Gradle dependency for kotlinpoet

Source: https://github.com/square/kotlinpoet/blob/main/docs/index.md

Adds the kotlinpoet artifact from com.squareup as a Gradle dependency. Replace [version] with the desired version.

```groovy
implementation("com.squareup:kotlinpoet:[version]")
```

--------------------------------

### Annotating types by class

Source: https://github.com/square/kotlinpoet/blob/main/docs/annotations.md

Passes annotations directly by class.

```kotlin
val suppressedType = String::class.asTypeName().annotated(Suppress::class)
```

--------------------------------

### Use ♢ symbol for optional line wrapping

Source: https://github.com/square/kotlinpoet/blob/main/docs/functions.md

Uses the ♢ symbol to declare a breaking space where it is safe to wrap the line. The generated output wraps at the marked positions, producing a slightly more readable result.

```kotlin
val funSpec = FunSpec.builder("foo")
  .addStatement("return (100..10000).map { number ->♢number * number♢}.map { number ->♢number.toString()♢}.also { string ->♢println(string)♢}")
  .build()
```

```kotlin
public fun foo(): Unit = (100..10000).map { number -> number * number }.map { number ->
  number.toString() }.also { string -> println(string) }
```

--------------------------------

### Chaining annotations

Source: https://github.com/square/kotlinpoet/blob/main/docs/annotations.md

Chains multiple annotations on a type.

```kotlin
val chainedAnnotations = String::class.asTypeName()
  .annotated(AnnotationSpec.builder(Suppress::class).addMember("%S", "unused").build())
  .annotated(Deprecated::class)
```

--------------------------------

### Create a simple enum with enumBuilder and addEnumConstant

Source: https://github.com/square/kotlinpoet/blob/main/docs/enums.md

Use enumBuilder to create the enum type and addEnumConstant() for each value. The generated code shows the resulting enum class with each constant separated by blank lines.

```kotlin
val helloWorld = TypeSpec.enumBuilder("Roshambo")
  .addEnumConstant("ROCK")
  .addEnumConstant("SCISSORS")
  .addEnumConstant("PAPER")
  .build()
```

```kotlin
enum class Roshambo {
  ROCK,

  SCISSORS,

  PAPER
}
```

--------------------------------

### Merging primary constructor parameter with property

Source: https://github.com/square/kotlinpoet/blob/main/docs/constructors.md

Merges the primary constructor parameter with a property by using PropertySpec.initializer("greeting") and adding the PRIVATE modifier. The output shows the property declared directly in the constructor parameter list, and KotlinPoet omits braces for classes with empty bodies.

```kotlin
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()
```

```kotlin
class HelloWorld(private val greeting: String)
```

--------------------------------

### Escape illegal identifier names with %N

Source: https://github.com/square/kotlinpoet/blob/main/docs/n-for-names.md

The first block creates a FileSpec that uses %N with a MemberName whose simple name is the Kotlin keyword 'package'. The second block shows the generated output where %N escapes the name with backticks, ensuring valid Kotlin.

```kotlin
val taco = ClassName("com.squareup.tacos", "Taco")
val packager = ClassName("com.squareup.tacos", "TacoPackager")
val file = FileSpec.builder("com.example", "Test")
  .addFunction(
    FunSpec.builder("packageTacos")
      .addParameter("tacos", LIST.parameterizedBy(taco))
      .addParameter("packager", packager)
      .addStatement("packager.%N(tacos)", packager.member("package"))
      .build()
  )
  .build()
```

```kotlin
package com.example

import com.squareup.tacos.Taco
import com.squareup.tacos.TacoPackager
import kotlin.collections.List

fun packageTacos(tacos: List<Taco>, packager: TacoPackager) {
  packager.`package`(tacos)
}
```

--------------------------------

### Nested annotations

Source: https://github.com/square/kotlinpoet/blob/main/docs/annotations.md

Creates an annotation that contains a list of annotations using `%L` for embedded annotations.

```kotlin
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()
```

```kotlin
@HeaderList(
  [
    Header(name = "Accept", value = "application/json; charset=utf-8"),
    Header(name = "User-Agent", value = "Square Cash")
  ]
)
abstract fun recordEvent(logRecord: LogRecord): LogReceipt
```

--------------------------------

### Read Kotlin class metadata with toKmClass

Source: https://github.com/square/kotlinpoet/blob/main/docs/interop-kotlin-metadata.md

Converts a Kotlin class's @Metadata into a KmClass instance via Taco::class.toKmClass(). After conversion, you can access the class name, properties, and functions. The Taco class is defined with a prepare() function that has an empty body.

```kotlin
data class Taco(val seasoning: String, val soft: Boolean) {
  fun prepare() {

  }
}

val kmClass = Taco::class.toKmClass()

// Now you can access misc information about Taco from a Kotlin lens
println(kmClass.name)
kmClass.properties.forEach { println(it.name) }
kmClass.functions.forEach { println(it.name) }
```

--------------------------------

### Reference operators with MemberName

Source: https://github.com/square/kotlinpoet/blob/main/docs/m-for-members.md

MemberName supports operators using KOperator to import and reference them in generated code.

```kotlin
val taco = ClassName("com.squareup.tacos", "Taco")
val meat = ClassName("com.squareup.tacos.ingredient", "Meat")
val iterator = MemberName("com.squareup.tacos.internal", KOperator.ITERATOR)
val minusAssign = MemberName("com.squareup.tacos.internal", KOperator.MINUS_ASSIGN)
val file = FileSpec.builder("com.example", "Test")
  .addFunction(
    FunSpec.builder("makeTacoHealthy")
      .addParameter("taco", taco)
      .beginControlFlow("for (ingredient %M taco)", iterator)
      .addStatement("if (ingredient is %T) taco %M ingredient", meat, minusAssign)
      .endControlFlow()
      .addStatement("return taco")
      .build()
  )
  .build()
println(file)
```

```kotlin
package com.example

import com.squareup.tacos.Taco
import com.squareup.tacos.ingredient.Meat
import com.squareup.tacos.internal.iterator
import com.squareup.tacos.internal.minusAssign

fun makeTacoHealthy(taco: Taco) {
  for (ingredient in taco) {
    if (ingredient is Meat) taco -= ingredient
  }
  return taco
}
```

--------------------------------

### Create a fancy enum with constructor, overrides, and anonymous classes

Source: https://github.com/square/kotlinpoet/blob/main/docs/enums.md

Fancy enums are supported where enum values override methods or call a superclass constructor. The builder adds a primary constructor, anonymous class bodies for constants, and a private property; the generated code shows the resulting enum with overridden toString and constructor arguments.

```kotlin
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()
```

```kotlin
enum class Roshambo(private val handsign: String) {
  ROCK("fist") {
    override fun toString(): String = "avalanche!"
  },

  SCISSORS("peace"),

  PAPER("flat");
}
```

--------------------------------

### Handle name collisions with addAliasedImport

Source: https://github.com/square/kotlinpoet/blob/main/docs/m-for-members.md

Use FileSpec.addAliasedImport() to create an alias for a clashing MemberName when simple name collisions occur.

```kotlin
val createTaco = MemberName("com.squareup.tacos", "createTaco")
val createCake = MemberName("com.squareup.cakes", "createCake")
val isTacoVegan = MemberName("com.squareup.tacos", "isVegan")
val isCakeVegan = MemberName("com.squareup.cakes", "isVegan")
val file = FileSpec.builder("com.squareup.example", "Test")
  .addAliasedImport(isTacoVegan, "isTacoVegan")
  .addAliasedImport(isCakeVegan, "isCakeVegan")
  .addFunction(
    FunSpec.builder("main")
      .addStatement("val taco = %M()", createTaco)
      .addStatement("val cake = %M()", createCake)
      .addStatement("println(taco.%M)", isTacoVegan)
      .addStatement("println(cake.%M)", isCakeVegan)
      .build()
  )
  .build()
println(file)
```

```kotlin
package com.squareup.example

import com.squareup.cakes.createCake
import com.squareup.tacos.createTaco
import com.squareup.cakes.isVegan as isCakeVegan
import com.squareup.tacos.isVegan as isTacoVegan

fun main() {
  val taco = createTaco()
  val cake = createCake()
  println(taco.isTacoVegan)
  println(cake.isCakeVegan)
}
```

--------------------------------

### Clearing annotations with copy()

Source: https://github.com/square/kotlinpoet/blob/main/docs/annotations.md

Uses the `copy()` function to clear annotations from a type.

```kotlin
val unannotatedString = String::class.asTypeName()
  .annotated(Suppress::class)
  .copy(annotations = listOf())
```
Tokens:
Raw