0
# KotlinPoet
1

2
KotlinPoet is a comprehensive Kotlin and Java API for generating Kotlin source files (.kt) programmatically. It provides type-safe, fluent builder patterns for creating well-formatted Kotlin code, supporting all modern Kotlin language constructs including classes, functions, properties, type aliases, and annotations. As a multiplatform library supporting JVM, JavaScript, and WebAssembly targets, KotlinPoet is the go-to solution for code generation in build tools, annotation processors, and development utilities.
3

4
## Package Information
5

6
- **Package Name**: kotlinpoet
7
- **Package Type**: maven
8
- **Language**: Kotlin (Multiplatform: JVM, JS, WebAssembly)
9
- **Installation**: 
10
  - **Gradle**: `implementation("com.squareup:kotlinpoet:2.2.0")`
11
  - **Maven**: 
12
    ```xml
13
    <dependency>
14
      <groupId>com.squareup</groupId>
15
      <artifactId>kotlinpoet</artifactId>
16
      <version>2.2.0</version>
17
    </dependency>
18
    ```
19

20
## Core Imports
21

22
```kotlin
23
import com.squareup.kotlinpoet.*
24
```
25

26
Common specific imports:
27

28
```kotlin
29
import com.squareup.kotlinpoet.FileSpec
30
import com.squareup.kotlinpoet.TypeSpec
31
import com.squareup.kotlinpoet.FunSpec
32
import com.squareup.kotlinpoet.PropertySpec
33
import com.squareup.kotlinpoet.ClassName
34
import com.squareup.kotlinpoet.CodeBlock
35
```
36

37
For JVM-specific annotations:
38

39
```kotlin
40
import com.squareup.kotlinpoet.jvm.JvmAnnotations
41
```
42

43
## Basic Usage
44

45
```kotlin
46
import com.squareup.kotlinpoet.*
47

48
// Create a simple class with a function
49
val greeterClass = TypeSpec.classBuilder("Greeter")
50
    .addProperty(
51
        PropertySpec.builder("name", String::class)
52
            .initializer("%S", "World")
53
            .build()
54
    )
55
    .addFunction(
56
        FunSpec.builder("greet")
57
            .returns(String::class)
58
            .addStatement("return %S + name", "Hello, ")
59
            .build()
60
    )
61
    .build()
62

63
// Create a file containing the class
64
val file = FileSpec.builder("com.example", "Greeter")
65
    .addType(greeterClass)
66
    .build()
67

68
// Output the generated code
69
file.writeTo(System.out)
70

71
/* Generated output:
72
package com.example
73

74
import kotlin.String
75

76
class Greeter {
77
  val name: String = "World"
78

79
  fun greet(): String = "Hello, " + name
80
}
81
*/
82
```
83

84
## Architecture
85

86
KotlinPoet is built around several key architectural components:
87

88
- **Specification Builders**: Core classes (`FileSpec`, `TypeSpec`, `FunSpec`, `PropertySpec`) using the Builder pattern for constructing code elements
89
- **Type System**: Complete representation of Kotlin's type system (`TypeName`, `ClassName`, `ParameterizedTypeName`) with nullability and annotation support
90
- **Code Generation**: `CodeBlock` for template-based code fragment generation with placeholder substitution
91
- **Multiplatform Design**: Common API with platform-specific implementations for JVM, JS, and WebAssembly
92
- **Utility Layer**: `NameAllocator` for identifier management, `KModifier`/`KOperator` enums for language constructs
93

94
## Capabilities
95

96
### File and Type Generation
97

98
Core functionality for creating Kotlin files and type declarations including classes, interfaces, objects, and annotation classes. This forms the foundation of all code generation workflows.
99

100
```kotlin { .api }
101
// File specification
102
class FileSpec private constructor() {
103
    companion object {
104
        fun builder(packageName: String, fileName: String): Builder
105
        fun builder(className: ClassName): Builder
106
        fun builder(memberName: MemberName): Builder
107
        fun get(packageName: String, typeSpec: TypeSpec): FileSpec
108
        fun scriptBuilder(fileName: String, packageName: String = ""): Builder
109
    }
110
    fun writeTo(out: Appendable)
111
    fun writeTo(directory: Path)
112
    fun toJavaFileObject(): JavaFileObject
113
    fun toBuilder(packageName: String = this.packageName, name: String = this.name): Builder
114
}
115

116
// Type specification  
117
class TypeSpec private constructor() {
118
    companion object {
119
        fun classBuilder(name: String): Builder
120
        fun classBuilder(className: ClassName): Builder
121
        fun interfaceBuilder(name: String): Builder
122
        fun interfaceBuilder(className: ClassName): Builder
123
        fun funInterfaceBuilder(name: String): Builder
124
        fun funInterfaceBuilder(className: ClassName): Builder
125
        fun objectBuilder(name: String): Builder
126
        fun objectBuilder(className: ClassName): Builder
127
        fun annotationBuilder(name: String): Builder
128
        fun annotationBuilder(className: ClassName): Builder
129
        fun enumBuilder(name: String): Builder
130
        fun enumBuilder(className: ClassName): Builder
131
        fun anonymousClassBuilder(): Builder
132
        fun companionObjectBuilder(name: String? = null): Builder
133
    }
134
    fun toBuilder(kind: Kind = this.kind, name: String? = this.name): Builder
135
}
136
```
137

138
[File and Type Generation](./file-and-type-generation.md)
139

140
### Function and Property Generation
141

142
Comprehensive support for generating functions, constructors, properties, and parameters with full Kotlin language feature support including modifiers, annotations, and documentation.
143

144
```kotlin { .api }
145
// Function specification
146
class FunSpec private constructor() {
147
    companion object {
148
        fun builder(name: String): Builder
149
        fun builder(memberName: MemberName): Builder
150
        fun constructorBuilder(): Builder
151
        fun getterBuilder(): Builder
152
        fun setterBuilder(): Builder
153
    }
154
}
155

156
// Property specification
157
class PropertySpec private constructor() {
158
    companion object {
159
        fun builder(name: String, type: TypeName, vararg modifiers: KModifier): Builder
160
        fun varBuilder(name: String, type: TypeName, vararg modifiers: KModifier): Builder
161
    }
162
}
163

164
// Parameter specification
165
class ParameterSpec private constructor() {
166
    companion object {
167
        fun builder(name: String, type: TypeName, vararg modifiers: KModifier): Builder
168
        fun unnamed(type: TypeName): ParameterSpec
169
    }
170
}
171
```
172

173
[Function and Property Generation](./function-and-property-generation.md)
174

175
### Type System
176

177
Complete representation of Kotlin's type system including classes, generics, wildcards, lambda types, and type variables. Provides type-safe APIs for working with complex type hierarchies and generic type parameters.
178

179
```kotlin { .api }
180
// Base type representation
181
abstract class TypeName {
182
    val isNullable: Boolean
183
    val annotations: List<AnnotationSpec>
184
    fun copy(nullable: Boolean = this.isNullable, annotations: List<AnnotationSpec> = this.annotations): TypeName
185
}
186

187
// Class and interface types
188
class ClassName : TypeName {
189
    companion object {
190
        fun get(packageName: String, simpleName: String, vararg simpleNames: String): ClassName
191
        fun get(clazz: Class<*>): ClassName
192
        fun get(klass: KClass<*>): ClassName
193
        fun bestGuess(classNameString: String): ClassName
194
    }
195
    fun parameterizedBy(vararg typeArguments: TypeName): ParameterizedTypeName
196
}
197

198
// Parameterized (generic) types
199
class ParameterizedTypeName : TypeName {
200
    val rawType: ClassName
201
    val typeArguments: List<TypeName>
202
    companion object {
203
        fun get(rawType: ClassName, vararg typeArguments: TypeName): ParameterizedTypeName
204
    }
205
}
206
```
207

208
[Type System](./type-system.md)
209

210
### Code Generation and Templates
211

212
Template-based code generation with placeholder substitution, supporting complex code structures and maintaining proper formatting and imports.
213

214
```kotlin { .api }
215
// Code block with template support
216
class CodeBlock private constructor() {
217
    companion object {
218
        fun of(format: String, vararg args: Any?): CodeBlock
219
        fun builder(): Builder
220
        fun join(codeBlocks: Iterable<CodeBlock>, separator: String = ", "): CodeBlock
221
    }
222
}
223

224
// Member reference for imports and qualified names
225
class MemberName {
226
    companion object {
227
        fun get(enclosingClassName: ClassName, simpleName: String): MemberName
228
        fun get(packageName: String, simpleName: String): MemberName
229
        fun get(clazz: Class<*>, simpleName: String): MemberName
230
        fun get(klass: KClass<*>, simpleName: String): MemberName
231
    }
232
}
233
```
234

235
[Code Generation and Templates](./code-generation.md)
236

237
### Annotations and Metadata
238

239
Complete support for Kotlin and Java annotations including annotation specifications, JVM-specific annotations, and metadata generation for annotation processors.
240

241
```kotlin { .api }
242
// Annotation specification
243
class AnnotationSpec private constructor() {
244
    companion object {
245
        fun builder(type: ClassName): Builder
246
        fun builder(type: Class<*>): Builder  
247
        fun builder(type: KClass<*>): Builder
248
    }
249
}
250

251
// Type alias specification
252
class TypeAliasSpec private constructor() {
253
    companion object {
254
        fun builder(name: String, type: TypeName): Builder
255
    }
256
}
257
```
258

259
[Annotations and Metadata](./annotations-and-metadata.md)
260

261
### Utilities and Language Support
262

263
Essential utilities for name allocation, modifier management, and platform-specific functionality across JVM, JavaScript, and WebAssembly targets.
264

265
```kotlin { .api }
266
// Name collision avoidance
267
class NameAllocator {
268
    fun newName(suggestion: String, tag: Any? = null): String
269
    fun get(tag: Any): String
270
    fun clone(): NameAllocator
271
}
272

273
// Kotlin modifiers
274
enum class KModifier {
275
    PUBLIC, PROTECTED, PRIVATE, INTERNAL,
276
    EXPECT, ACTUAL, FINAL, OPEN, ABSTRACT, SEALED,
277
    CONST, EXTERNAL, OVERRIDE, LATEINIT, TAILREC,
278
    VARARG, SUSPEND, INNER, ENUM, ANNOTATION, FUN,
279
    COMPANION, INLINE, VALUE, INFIX, OPERATOR, DATA,
280
    CROSSINLINE, NOINLINE, REIFIED
281
}
282

283
// Kotlin operators
284
enum class KOperator {
285
    UNARY_PLUS, PLUS, UNARY_MINUS, MINUS, TIMES, DIV, REM,
286
    PLUS_ASSIGN, MINUS_ASSIGN, TIMES_ASSIGN, DIV_ASSIGN, REM_ASSIGN,
287
    INC, DEC, EQUALS, NOT_EQUALS, NOT,
288
    RANGE_TO, CONTAINS, NOT_CONTAINS,
289
    GT, LT, GE, LE, ITERATOR
290
}
291
```
292

293
[Utilities and Language Support](./utilities.md)
294

295
## Type Definitions
296

297
### Common Built-in Types
298

299
```kotlin { .api }
300
// Core types
301
val ANY: ClassName
302
val UNIT: ClassName
303
val NOTHING: ClassName
304
val DYNAMIC: Dynamic
305

306
// Primitive types
307
val BOOLEAN: ClassName
308
val BYTE: ClassName
309
val SHORT: ClassName
310
val INT: ClassName
311
val LONG: ClassName
312
val CHAR: ClassName
313
val FLOAT: ClassName
314
val DOUBLE: ClassName
315
val STRING: ClassName
316
val NUMBER: ClassName
317

318
// Character and comparison types
319
val CHAR_SEQUENCE: ClassName
320
val COMPARABLE: ClassName
321
val THROWABLE: ClassName
322
val ANNOTATION: ClassName
323
val ENUM: ClassName
324

325
// Unsigned types
326
val U_BYTE: ClassName
327
val U_SHORT: ClassName
328
val U_INT: ClassName
329
val U_LONG: ClassName
330

331
// Collection types
332
val ITERABLE: ClassName
333
val COLLECTION: ClassName
334
val LIST: ClassName
335
val SET: ClassName
336
val MAP: ClassName
337
val MAP_ENTRY: ClassName
338
val MUTABLE_ITERABLE: ClassName
339
val MUTABLE_COLLECTION: ClassName
340
val MUTABLE_LIST: ClassName
341
val MUTABLE_SET: ClassName
342
val MUTABLE_MAP: ClassName
343
val MUTABLE_MAP_ENTRY: ClassName
344

345
// Array types
346
val ARRAY: ClassName
347
val BOOLEAN_ARRAY: ClassName
348
val BYTE_ARRAY: ClassName
349
val CHAR_ARRAY: ClassName
350
val SHORT_ARRAY: ClassName
351
val INT_ARRAY: ClassName
352
val LONG_ARRAY: ClassName
353
val FLOAT_ARRAY: ClassName
354
val DOUBLE_ARRAY: ClassName
355

356
// Unsigned array types
357
val U_BYTE_ARRAY: ClassName
358
val U_SHORT_ARRAY: ClassName
359
val U_INT_ARRAY: ClassName
360
val U_LONG_ARRAY: ClassName
361

362
// Wildcard type
363
val STAR: WildcardTypeName
364
```
365

366
### Core Interfaces
367

368
```kotlin { .api }
369
// Tagging support for builders
370
interface Taggable {
371
    val tags: Map<KClass<*>, Any>
372
}
373

374
// Documentation support
375
interface Documentable {
376
    val kdoc: CodeBlock
377
}
378

379
// Annotation processing support
380
interface OriginatingElementsHolder {
381
    val originatingElements: List<Element>
382
}
383
```