xref: /aosp_15_r20/external/kotlinpoet/docs/index.md (revision 3c321d951dd070fb96f8ba59e952ffc3131379a0) 
1KotlinPoet
2==========
3
4`KotlinPoet` is a Kotlin and Java API for generating `.kt` source files.
5
6Source file generation can be useful when doing things such as annotation processing or interacting
7with metadata files (e.g., database schemas, protocol formats). By generating code, you eliminate
8the need to write boilerplate while also keeping a single source of truth for the metadata.
9
10## Example
11
12Here's a `HelloWorld` file:
13
14```kotlin
15class Greeter(val name: String) {
16  fun greet() {
17    println("""Hello, $name""")
18  }
19}
20
21fun main(vararg args: String) {
22  Greeter(args[0]).greet()
23}
24```
25
26And this is the code to generate it with KotlinPoet:
27
28```kotlin
29val greeterClass = ClassName("", "Greeter")
30val file = FileSpec.builder("", "HelloWorld")
31  .addType(
32    TypeSpec.classBuilder("Greeter")
33      .primaryConstructor(
34        FunSpec.constructorBuilder()
35          .addParameter("name", String::class)
36          .build()
37      )
38      .addProperty(
39        PropertySpec.builder("name", String::class)
40          .initializer("name")
41          .build()
42      )
43      .addFunction(
44        FunSpec.builder("greet")
45          .addStatement("println(%P)", "Hello, \$name")
46          .build()
47      )
48      .build()
49  )
50  .addFunction(
51    FunSpec.builder("main")
52      .addParameter("args", String::class, VARARG)
53      .addStatement("%T(args[0]).greet()", greeterClass)
54      .build()
55  )
56  .build()
57
58file.writeTo(System.out)
59```
60
61The [KDoc][kdoc] catalogs the complete KotlinPoet API, which is inspired by [JavaPoet][javapoet].
62
63**Note:** In order to maximize portability, KotlinPoet generates code with explicit visibility
64modifiers. This ensures compatibility with both standard Kotlin projects as well as projects
65using [explicit API mode][explicit-api]. Examples in the documentation omit those modifiers for
66brevity.
67
68Download
69--------
70
71![Maven Central][version-shield]
72
73Download [the latest .jar][dl] or depend via Maven:
74
75```xml
76<dependency>
77  <groupId>com.squareup</groupId>
78  <artifactId>kotlinpoet-jvm</artifactId>
79  <version>[version]</version>
80</dependency>
81```
82
83or Gradle:
84
85```groovy
86implementation("com.squareup:kotlinpoet:[version]")
87```
88
89Snapshots of the development version are available in [Sonatype's `snapshots` repository][snap].
90
91License
92-------
93
94    Copyright 2017 Square, Inc.
95
96    Licensed under the Apache License, Version 2.0 (the "License");
97    you may not use this file except in compliance with the License.
98    You may obtain a copy of the License at
99
100       https://www.apache.org/licenses/LICENSE-2.0
101
102    Unless required by applicable law or agreed to in writing, software
103    distributed under the License is distributed on an "AS IS" BASIS,
104    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
105    See the License for the specific language governing permissions and
106    limitations under the License.
107
108 [kdoc]: https://square.github.io/kotlinpoet/1.x/kotlinpoet/kotlinpoet/com.squareup.kotlinpoet/
109 [javapoet]: https://github.com/square/javapoet/
110 [explicit-api]: https://kotlinlang.org/docs/whatsnew14.html#explicit-api-mode-for-library-authors
111 [version-shield]: https://img.shields.io/maven-central/v/com.squareup/kotlinpoet
112 [dl]: https://search.maven.org/remote_content?g=com.squareup&a=kotlinpoet-jvm&v=LATEST
113 [snap]: https://s01.oss.sonatype.org/content/repositories/snapshots/com/squareup/kotlinpoet/
114