1Change Log 2========== 3 4## Unreleased 5 6## Version 1.18.1 7 8Thanks to [@mitasov-ra][mitasov-ra] for contributing to this release. 9 10_2024-07-15_ 11 12 * Fix: Workaround for [KT-18706][kt-18706]: KotlinPoet now generates import aliases without backticks (#1920). 13 14 ```kotlin 15 // before, doesn't compile due to KT-18706 16 import com.example.one.`$Foo` as `One$Foo` 17 import com.example.two.`$Foo` as `Two$Foo` 18 19 // now, compiles 20 import com.example.one.`$Foo` as One__Foo 21 import com.example.two.`$Foo` as Two__Foo 22 ``` 23 24## Version 1.18.0 25 26Thanks to [@DanielGronau][DanielGronau] for contributing to this release. 27 28_2024-07-05_ 29 30 * New: Kotlin 2.0.0. 31 * New: KSP 2.0.0-1.0.22. 32 * New: Promote `kotlinpoet-metadata` out of preview to stable. 33 * New: Migrate `kotlinpoet-metadata` to stable `org.jetbrains.kotlin:kotlin-metadata-jvm` artifact for Metadata parsing. 34 * New: Make enum entry references in `KSAnnotation.toAnnotationSpec()` and `KSClassDeclaration.toClassName()` more robust. 35 * Fix: Don't expand typealiases of function types to `LambdaTypeName`s in `KSTypeReference.toTypeName()`. 36 * Fix: Avoid rounding small double and float values in `%L` translation (#1927). 37 * Fix: Fix typealias type argument resolution in KSP2 (#1929). 38 39## Version 1.17.0 40 41Thanks to [@jisungbin][jisungbin], [@hfhbd][hfhbd], [@evant][evant], [@sgjesse][sgjesse], [@sebek64][sebek64] for 42contributing to this release. 43 44_2024-05-24_ 45 46* Change: kotlinx-metadata 0.9.0. Note that the `KotlinClassMetadata.read` is deprecated in 0.9.0 and replaced with 47 `readStrict` (#1830). 48 * Note: we now also provide `lenient` parameters to map to the underlying `readStrict()` and `readLenient()` calls 49 (#1766). 50 * We have also removed various `Class`/`TypeElement`/`Metadata`-to-`KmClass` APIs from the public API, as these are 51 trivial to write now with kotlinx-metadata's newer APIs and allows us to focus the API surface area of this artifact 52 better (#1891). 53* New: Supertype list wraps to one-per-line if the primary constructor spans multiple lines (#1866). 54* New: Extract `MemberSpecHolder` interface for constructs that can hold `PropertySpec`s and `FunSpec`s and their 55 builders (#1877). 56* New: `joinToCode` variant which operates on any type, but requires a transform lambda to convert each element into a 57 `CodeBlock` (#1874). 58* New: Support annotation type arguments in `KSAnnotation.toAnnotationSpec()` (#1889). 59* Fix: Prevent name clashes between a function in class and a function call in current scope (#1850). 60* Fix: Fix extension function imports (#1814). 61* Fix: Omit implicit modifiers on `FileSpec.scriptBuilder` (#1813). 62* Fix: Fix trailing newline in `PropertySpec` (#1827). 63* Fix: `KSAnnotation.toAnnotationSpec` writes varargs in place instead of making them an array to work around a Kotlin 64 issue with `OptIn` annotations (#1833). 65* Fix: `MemberName`s without a package are now correctly imported (#1841) 66* Fix: Throw if primary constructor delegates to other constructors (#1859). 67* Fix: Aliased imports with nested class (#1876). 68* Fix: Check for error types in `KSType.toClassName()` (#1890). 69* Fix: Support generating a single import for overloaded `MemberName`s (#1909). 70 71## Version 1.16.0 72 73Thanks to [@drawers][drawers], [@rickclephas][rickclephas] for contributing to this release. 74 75_2024-01-18_ 76 77 * New: Kotlin 1.9.22. 78 * New: KSP 1.9.22-1.0.16. 79 * New: Add `NameAllocator` API to control keyword pre-allocation (#1803). 80 * Fix: Fix issue with missing `suspend` modifier in `KSTypeReference.toTypeName` (#1793). 81 * Fix: Honour same-package import aliases (#1794). 82 * Fix: Always include parameter docs in the type header (#1800). 83 84## Version 1.15.3 85 86Thanks to [@gabrielittner][gabrielittner] for contributing to this release. 87 88_2023-12-04_ 89 90 * Fix: Fix nullability of lambdas in `KSTypeReference.toTypeName` (#1756). 91 92## Version 1.15.2 93 94Thanks to [@evant][evant] for contributing to this release. 95 96_2023-11-30_ 97 98 * New: Kotlin 1.9.21. 99 * New: KSP 1.9.21-1.0.15. 100 * New: KSP: more accurately represent function types (#1742). 101 102## Version 1.15.1 103 104_2023-11-19_ 105 106 * Fix: Fix a regression introduced by #1637, where a superfluous newline is added to a type's KDoc 107 if it has a primary constructor with no docs (#1727). 108 109## Version 1.15.0 110 111_2023-11-18_ 112 113Thanks to [@drawers][drawers], [@fejesjoco][fejesjoco], [@takahirom][takahirom], 114[@martinbonnin][martinbonnin], [@mcarleio][mcarleio] for contributing to this release. 115 116In this release the `:kotlinpoet` module has been converted to a Kotlin Multiplatform module 117(#1654), though for now it only supports the JVM target. **Important**: unless you're building 118with Gradle, you will now need to depend on the `kotlinpoet-jvm` artifact, instead of `kotlinpoet` - 119see [Downloads](index.md#download) for instructions. 120 121 * New: Kotlin 1.9.20. 122 * New: KSP 1.9.20-1.0.14. 123 * New: Extract `TypeSpecHolder` interface for constructs that can hold a TypeSpec and their builders (#1723). 124 * New: Expose relative path from `FileSpec` (#1720). 125 * New: Return the generated path from `FileSpec.writeTo()`. (#1514). 126 * New: Remove default compatibility from unstable types (#1662). 127 * New: Deprecate `TypeSpec.expectClassBuilder()` and `TypeSpec.valueClassBuilder()` (#1589). 128 * New: Add option to convert `KSAnnotation` to `AnnotationSpec` while omitting default values (#1538). 129 * New: Add `FileSpec.builder` convenience for `MemberName` (#1585). 130 * Fix: Set `DecimalFormatSymbols.minusSign` for consistency across locales (#1658). 131 * Fix: Fix link to incremental KSP in KDoc (#1638). 132 * Fix: Emit primary constructor KDoc (#1637). 133 * Change: kotlinx-metadata 0.7.0. This is a breaking change for users of the `:kotlinpoet-metadata` 134 module, as most `Flags`-API extensions have been removed in favor of the now-available first-party versions. 135 136## Version 1.14.2 137 138_2023-05-30_ 139 140 * Fix: Fix one more missing API in binary compatibility override in `Annotatable.Builder` (#1581). 141 142## Version 1.14.1 143 144_2023-05-29_ 145 146 * Fix: Restore ABI stability for annotatable and documentable builders (#1580). 147 148## Version 1.14.0 149 150_2023-05-29_ 151 152Thanks to [@Omico][Omico], [@drawers][drawers], [@RBusarow][RBusarow] for contributing to this release. 153 154 * New: Kotlin 1.8.21. 155 * New: KSP 1.8.21-1.0.11. 156 * New: Enable default methods in Java bytecode (#1561). 157 * New: Group Kotlin and Renovate updates together in Renovate (#1562). 158 * New: Extract trait interface for annotatable constructs and their builders (#1564). 159 * New: Extract trait interface for documentable constructs and their builders (#1571). 160 * New: Document the usage of `STAR` (#1572). 161 * New: Add builder for `FunSpec` which accepts a `MemberName` (#1574). 162 * Fix: Omit public modifier on override function or constructor parameters (#1550). 163 * Fix: Correct handling of members in various types (#1558). 164 * Fix: Function return types now default to `Unit` unless explicitly set (#1559). 165 166 Previously, when `FunSpec` didn't have a return type specified and an expression body was produced, no return 167 type would be emitted. However, starting from `1.14.0`, KotlinPoet will not add `Unit` as a return type in such 168 cases. In order to correct the generated output, you are to specify the actual return type of the `FunSpec`. 169 170 Before `1.14.0`, if omitted, no return type is produced: 171 ```kotlin 172 val funSpec = FunSpec.builder("foo") 173 .addStatement("return 1") 174 .build() 175 ``` 176 ```kotlin 177 public fun foo() = 1 178 ``` 179 180 From `1.14.0`, the return type defaults to `Unit` if not otherwise set: 181 ```kotlin 182 val funSpec = FunSpec.builder("foo") 183 .addStatement("return 1") 184 .build() 185 ``` 186 ```kotlin 187 public fun foo(): Unit = 1 // ❌ 188 ``` 189 190 To fix it, explicitly define the return type: 191 ```diff 192 val funSpec = FunSpec.builder("foo") 193 + .returns(INT) 194 .addStatement("return 1") 195 .build() 196 ``` 197 ```kotlin 198 public fun foo(): Int = 1 // ✅ 199 ``` 200 201 Additionally, as part of this change, `FunSpec.returnType` has changed to be non-nullable. This is a source- and 202 binary-compatible change, although if you were performing null-checks then new warnings may appear after upgrade. 203 204 * Fix: Append nested class names to alias during name lookup (#1568). 205 * Fix: Allow PropertySpec with context receivers and without getter or setter (#1575). 206 207## Version 1.13.2 208 209_2023-05-05_ 210 211Thanks to [@Squiry][Squiry] for contributing to this release. 212 213* Fix: `KSType.toTypeName` fixed to work with aliased types (#1534). 214 215## Version 1.13.1 216 217_2023-04-28_ 218 219Thanks to [@rickclephas][rickclephas] for contributing to this release. 220 221 * Fix: Look at canonical names instead of just package names when generating import aliases (#1519). 222 * Fix: Ignore KSP annotation arguments without a value (#1523). 223 * Fix: Fix arguments handling in `KSType.toTypeName()` (#1529). 224 225## Version 1.13.0 226 227_2023-04-06_ 228 229Thanks to [@popematt][popematt], [@bitPogo][bitPogo], [@mars885][mars885], [@sjudd][sjudd], [@Sironheart][Sironheart], 230[@polarene][polarene], [@DeoTimeTheGithubUser][DeoTimeTheGithubUser], [@drawers][drawers] for contributing to this release. 231 232 * New: Kotlin 1.8.0. 233 * New: KSP 1.8.0-1.0.9. 234 * New: Support context receivers on TypeSpecs + extract ContextReceivable API (#1269). 235 * New: Optimize `OriginatingElements` and `TagMap` implementations (#1270). 236 * New: Auto-generate import aliases for types and members (#1355). 237 * New: Insert underscores into large decimal literals (#1384). 238 * New: New factory function `FileSpec.builder(ClassName)` (#1397). 239 * Fix: Fix StackOverflowError when calling `KSTypeArgument.toTypeName()` for a wildcard in a recursive type bound (#1272). 240 * Fix: Fix transitive aliases (#1306). 241 * Fix: Fix Aliases as TypeArgument (#1321). 242 * Fix: Don't escape special characters inside raw strings (#1331). 243 * Fix: Fix KSP interop's output of the annotation parameter value of type Char (#1338). 244 * Fix: Fix KSP interop's output for primitive arrays (#1340). 245 * Fix: Avoid emitting public if `shouldEmitPublicModifier` returns false (#1342). 246 * Fix: Fix context receivers being rendered in an incorrect position when on a nullable/suspending `LambdaTypeName` (#1454). 247 * Fix: Do not use `bestGuess` for `KClass.asClassName` (#1469). 248 * Fix: Handle fake nested types with platform mapped parents (#1472). 249 * Fix: Fix `TypeName` equals (#1477). 250 * Fix: Make equals consistent with compareTo for `ClassName` (#1506). 251 252## Version 1.12.0 253 254_2022-06-13_ 255 256Thanks to [@WhosNickDoglio][WhosNickDoglio], [@sullis][sullis], [@DRSchlaubi][DRSchlaubi], 257[@martinbonnin][martinbonnin], [@seriouslyhypersonic][seriouslyhypersonic], [@ephemient][ephemient], 258[@dkilmer][dkilmer], [@aksh1618][aksh1618], [@zsqw123][zsqw123], [@roihershberg][roihershberg] for 259contributing to this release. 260 261 * New: Kotlin 1.7.0. 262 * New: Add support for context receivers. 263 * New: Add support for external property getter. 264 * New: `interop-ksp` API promoted to stable. 265 * Fix: Resolve enum constants when emitting types. 266 * Fix: Fix type argument mapping when processing typealiases with KSP. 267 * Fix: Properly unwrap `KSTypeAlias` with an unused type parameter. 268 * Fix: Unwrap nested `KSTypeAlias`-es recursively. 269 * Fix: Add support for context receivers `@PropertySpec` and fix issues with annotations. 270 * Fix: Treat `header` and `impl` as keywords (workaround for KT-52315). 271 * Fix: Use `%N` instead of `%L` for annotation arg names so keywords are handled. 272 * Fix: Improve handling of long `return` expressions. 273 274## Version 1.11.0 275 276_2022-03-24_ 277 278Thanks to [@liujingxing][liujingxing] and [@BoD][BoD] for contributing to this release. 279 280* New: Kotlin scripting support in `FileSpec`. 281 282```kotlin 283val spec = FileSpec.scriptBuilder("Taco") 284 .addStatement("println(%S)", "hello world!") 285 .addKotlinDefaultImports() 286 .build() 287``` 288 289Generates a `Taco.kts` file with the following contents: 290 291```kotlin 292println("hello world!") 293``` 294 295* New: Emit trailing commas for multi-line parameters and annotations. 296* New: Add `KSAnnotation.toAnnotationSpec()`. 297* New: Add `Unit` and `CharSequence` conversions in `javapoet-interop`. 298* New: Add support for default imports in `FileSpec`. 299 * This is particularly oriented at scripting support, but can also be used in non-script files. 300* New: Update to Kotlin 1.6.10. 301* Fix: Fail compilation if you only pass one string to `ClassName`. 302* Fix: Inline `val` property if its getter is `inline`. 303* Fix: Add `yield` to the list of reserved keywords. 304* Fix: Enforce only allowed parameter modifiers in `ParameterSpec` (i.e. `crossinline`, `vararg`, and `noinline`). 305* Fix: Fix `CodeBlock`s in class delegation getting `toString()`'d instead of participating in code writing. 306* Fix: Error when attempting to convert KSP error types (i.e. if `KSType.isError` is true) to `TypeName`. 307 308## Version 1.10.2 309 310_2021-10-22_ 311 312Thanks to [@glureau][glureau] and [@goooler][goooler] for contributing to this release. 313 314* New: Switch `AnnotationSpec.get()` to use the `arrayOf()` syntax instead of `[]`. 315* Fix: Don't wrap aliasing imports with long package names. 316* Fix: Don't wrap type names inside line comments. 317* Fix: Ignore Java's `@Deprecated` annotations on synthetic methods for annotations. 318 319## Version 1.10.1 320 321_2021-09-21_ 322 323Thanks to [@evant][evant] for contributing to this release. 324 325 * Fix: Correct generation of typealiases with type args in KSP interop. 326 * Fix: Add missing default `TypeParameterResolver.EMPTY` argument to 327 `fun KSTypeArgument.toTypeName` in KSP interop. 328 329## Version 1.10.0 330 331_2021-09-20_ 332 333Thanks to [@martinbonnin][martinbonnin], [@idanakav][idanakav], [@goooler][goooler], and 334[@anandwana001][anandwana001] for contributing to this release. 335 336 * New: Add a new [KSP][ksp] interop artifact. See [docs][ksp-interop-docs] for more details. 337 * New: Add a new [JavaPoet][javapoet] interop artifact. See [docs][javapoet-interop-docs] for more 338 details. 339 * New: Allow copying a `ParameterizedTypeName` with new type arguments via new `copy()` overload. 340 * kotlinx-metadata artifacts have been consolidated to a single `com.squareup:kotlinpoet-metadata` 341 maven artifact. The previous `kotlinpoet-metadata-*` subartifacts are no longer published. 342 * New: `TypeNameAliasTag` has been moved to KotlinPoet's main artifact under `TypeAliasTag`, for 343 reuse with KSP interop. 344 * `ImmutableKm*` classes have been removed. They were deemed to be a needless abstraction over the base `kotlinx-metadata` Km types. All usages of these should be substituted with their non-immutable base types. 345 * Fix: Fix self-referencing type variables in metadata parsing. 346 * Fix: Use delicate APIs rather than noisy logging ones when converting annotation mirrors in 347 `AnnotationSpec.get`. 348 * Fix: Update error message when metadata cannot be read to a more actionable one. 349 * Fix: Avoid escaping already escaped strings. 350 * Add docs about `kotlin-reflect` usage. 351 * Avoid using kotlin-reflect for looking up `Unit` types where possible. 352 * Test all the way up to JDK 17. 353 * Update Kotlin to 1.5.31. 354 355## Version 1.9.0 356 357_2021-06-22_ 358 359 * New: Kotlin 1.5.10. 360 * New: Previously deprecated API to interop with Java reflection and Mirror API have been 361 un-deprecated and marked with `@DelicateKotlinPoetApi` annotation. 362 * New: `CodeBlock.Builder.withIndent` helper function. 363 * New: Allow changing initializers and default values in `ParameterSpec.Builder` and 364 `PropertySpec.Builder` after they were set. 365 * New: `MemberName.isExtension` property that instructs KotlinPoet to always import the member, 366 even if conflicting declarations are present in the same scope. 367 * Fix: Escape member names that only contain underscores. 368 * Fix: Always emit an empty primary constructor if it was set via `TypeSpec.primaryConstructor`. 369 370## Version 1.8.0 371 372_2021-03-29_ 373 374 * New: Kotlin 1.4.31. 375 * New: Add `KModifier.VALUE` to support `value class` declarations. 376 * New: Allow using a custom `ClassLoader` with `ReflectiveClassInspector`. 377 * New: Update to kotlinx-metadata 0.2.0. 378 * Fix: Ensure `ImmutableKmProperty.toMutable()` copies `fieldSignature`. 379 * Fix: Prevent name clashes between an imported `MemberName` and a member in current scope. 380 * Fix: Prevent name clashes between a type and a supertype with the same name. 381 * Fix: Don't generate empty body for `expect` and `external` functions. 382 * Fix: Don't allow `expect` or `external` classes to initialize supertypes. 383 * Fix: Disallow delegate constructor calls in `external` classes. 384 * Fix: Allow non-public primary constructors inside inline/value classes. 385 * Fix: Allow init blocks inside inline/value classes. 386 * Fix: Omit redundant `abstract` modifiers on members inside interfaces 387 388## Version 1.7.2 389 390_2020-10-20_ 391 392 * New: Detect expression bodies with `return·` and `throw·` prefixes. 393 * Fix: Omit visibility modifiers on custom accessors. 394 395## Version 1.7.1 396 397_2020-10-15_ 398 399 * Fix: 1.7.0 was published using JDK 11 which set `"org.gradle.jvm.version"` to `"11"` in Gradle 400 metadata, making it impossible to use the library on earlier Java versions (see 401 [#999][issue-999]). 1.7.1 is published with JDK 8, which fixes the problem. 402 403## Version 1.7.0 404 405_2020-10-14_ 406 407 * New: Kotlin 1.4.10. 408 * New: Generated code is now compatible with the [explicit API mode][explicit-api-mode] by default. 409 * New: Escape soft and modifier keywords, in addition to hard keywords. 410 * New: Improve enum constants generation for cleaner diffs. 411 * New: Disallow setters on immutable properties. 412 * New: Ensure trailing new lines in expression bodies. 413 * New: Ensure trailing new lines after parameterless custom setters. 414 * Fix: Don't auto-convert properties with custom accessors to primary constructor properties. 415 * Fix: Don't allow parameterless setters with body. 416 * Fix: Prevent auto-wrapping spaces inside escaped keywords. 417 418## Version 1.6.0 419 420_2020-05-28_ 421 422 * New: Deprecate Mirror API integrations. 423 424 Mirror API integrations, such as `TypeElement.asClassName()` and 425 `FunSpec.overriding(ExecutableElement)`, are being deprecated in this release. These KotlinPoet 426 APIs are most often used in annotation processors. Since kapt runs annotation processors over 427 stubs, which are Java files, a lot of the Kotlin-specific information gets lost in translation 428 and cannot be accessed by KotlinPoet through the Mirror API integrations. Examples include: 429 430 - Alias types, such as `kotlin.String`, get converted to their JVM representations, such as 431 `java.lang.String`. 432 - Type nullability information is not accessible. 433 - `suspend` functions are seen as simple functions with an additional `Continuation` parameter. 434 435 The correct solution is to switch to [KotlinPoet-metadata][kotlinpoet-metadata] or 436 [KotlinPoet-metadata-specs][kotlinpoet-metadata-specs] API, which fetches Kotlin-specific 437 information from the `@Metadata` annotation and produces correct KotlinPoet Specs. We may explore 438 adding new metadata-based alternatives to the deprecated APIs in the future. 439 440 * New: Kotlin 1.3.72. 441 * New: Improve `MemberName` to support operator overloading. 442 * New: Support generics in `AnnotationSpec`. 443 * New: Add support for functional interfaces. 444 * New: Make more `FunSpec.Builder` members public for easier mutation. 445 * Fix: Properly propagate implicit type and function modifiers in nested declarations. 446 * Fix: Properly escape type names containing `$` character. 447 * Fix: Don't emit `LambdaTypeName` annotations twice. 448 * Fix: Preserve tags in `TypeName.copy()`. 449 450## Version 1.5.0 451 452_2020-01-09_ 453 454 KotlinPoet now targets JDK8, which means that executing a build that includes KotlinPoet as a 455 dependency on a machine with an older version of JDK installed won't work. **This has no effect on 456 the code that KotlinPoet produces**: the code can still be compiled against JDK6, as long as it 457 doesn't use any features that were introduced in newer releases. 458 459 * New: Kotlin 1.3.61. 460 * New: Add support for processing FileFacades in KotlinPoet-metadata. 461 * New: Add support for inner nested and companion objects on annotation classes. 462 * New: Improve error messages for mismatched open/close statement characters. 463 * New: Tag `AnnotationSpec`s with the annotation mirror when available. 464 * New: Include annotations on enum entries when creating `TypeSpec`s from metadata. 465 * Fix: Fix metadata parsing for types. 466 * Fix: Allow file names that are Kotlin keywords. 467 * Fix: Properly escape type alias names with backticks. 468 * Fix: Allow creating `TypeSpec`s with names that can be escaped with backticks. 469 * Fix: Properly escape enum constant names with backticks. 470 * Fix: Maintain proper ordering of properties and initializers when emitting a `TypeSpec`. 471 **Note**: with this change, any properties declared after any initializer blocks will not be 472 added to the primary constructor and will instead be emitted inside the `TypeSpec` body. 473 * Fix: Don't emit a leading new line if type KDoc is empty but parameter KDocs are present. 474 * Fix: Ensure KotlinPoet-metadata resolves package names properly. 475 476 ## Version 1.4.4 477 478_2019-11-16_ 479 480 * Fix: Support reified inline types in KotlinPoet-metadata. 481 482## Version 1.4.3 483 484_2019-10-30_ 485 486 * Fix: Don't emit stubs for abstract functions in KotlinPoet-metadata. 487 488## Version 1.4.2 489 490_2019-10-28_ 491 492 * Fix: Properly handle abstract elements in KotlinPoet-metadata. 493 * Fix: Properly handle typealiases in KotlinPoet-metadata. 494 * Fix: Properly render % symbols at the end of KDocs. 495 496## Version 1.4.1 497 498_2019-10-18_ 499 500 * New: Add annotations support to `TypeAliasSpec`. 501 * New: Read type annotations from Kotlin `Metadata`. 502 * New: Introduce `ImmutableKmDeclarationContainer`. 503 * Fix: Use full package name for shading `auto-common`. 504 * Fix: Support reading self-type variables (e.g. `Asset<A : Asset<A>>`) from Kotlin `Metadata`. 505 506## Version 1.4.0 507 508_2019-09-24_ 509 510 * New: This release introduces the new KotlinPoet-metadata API that makes it easy to introspect 511 Kotlin types and build KotlinPoet Specs based on that data. 512 513 The strategy for type introspection is driven by `ClassInspector`, which is a basic interface for 514 looking up JVM information about a given Class. This optionally is used by the 515 `toTypeSpec()`/`toFileSpec()` APIs in `kotlinpoet-metadata-specs` artifact to inform about 516 Classes with information that isn’t present in metadata (overrides, JVM modifiers, etc). There 517 are two batteries-included implementations available in `ReflectiveClassInspector` 518 (for reflection) and `ElementsClassInspector` (for the javax Elements API in annotation 519 processing). These implementations are available through their respective 520 `kotlinpoet-classinspector-*` artifacts. For more information refer to the 521 [KotlinPoet-metadata-specs README][kotlinpoet-metadata-specs]. 522 523 At the time of this release the API is in experimental mode and has to be opted into via the 524 `KotlinPoetMetadataPreview` annotation. 525 526 * New: Kotlin 1.3.50. 527 * New: A new constructor to simplify creation of `ParameterSpec` instances. 528 * New: New `ClassName` constructors. 529 * New: `TypeName` and subclasses can now store tags. 530 * New: Optional parameters added to `toBuilder()` methods of most Specs. 531 * New: `List` overrides for Spec methods that accept `vararg`s. 532 * New: `CodeBlock.Builder.clear()` helper method. 533 * New: `FunSpec.Builder.clearBody()` helper method. 534 * Fix: Properly escape enum constant names. 535 * Fix: Ensure trailing newlines in KDoc and function bodies. 536 * Fix: `TypeVariableName`s with empty bounds will now default to `Any?`. 537 * Fix: Don't emit parens for primary constructors. 538 * Fix: `ClassName`s with empty simple names are not allowed anymore. 539 * Fix: Throw if names contain illegal characters that can't be escaped with backticks. 540 541## Version 1.3.0 542 543_2019-05-30_ 544 545 * New: Don't inline annotations in the primary constructor. 546 * New: Force new lines when emitting primary constructors. 547 * New: Support using MemberNames as arguments to %N. 548 * New: Add more ClassName constants: ClassName.STRING, ClassName.LIST, etc. 549 * New: Add ClassName.constructorReference() and MemberName.reference(). 550 * New: Make %N accept MemberNames. 551 * New: Escape spaces in import aliases. 552 * New: Escape spaces in ClassNames. 553 * New: Escape spaces in MemberNames. 554 * New: Escape imports containing spaces. 555 * New: Escape package name containing spaces. 556 * New: Use 2-space indents. 557 * New: Only indent one level on annotation values. 558 * Fix: Pass only unique originating elements to Filer. 559 * Fix: Fix bug with MemberNames in same package nested inside a class. 560 561## Version 1.2.0 562 563_2019-03-28_ 564 565 * New: Add writeTo(Filer) and originating element API. 566 * New: Make *Spec types taggable. 567 * New: Make FunSpec.Builder#addCode take vararg Any?. 568 * Fix: Import members from default package. 569 * Fix: Add non-wrapping spaces in control flow creation methods. 570 * Fix: Named "value" argument being omitted in annotation array types. 571 572## Version 1.1.0 573 574_2019-02-28_ 575 576 * New: Kotlin 1.3.21. 577 * New: Support referencing members using `%M` and `MemberName` type. 578 * New: Add extensions for getting a `MemberName` from a `ClassName`, `KClass` and `Class`. 579 * New: Allow passing `CodeBlock`s as arguments to `%P`. 580 * New: Allow interface delegation for objects. 581 * Fix: Don't emit visible whitespace in `toString()`. 582 * Fix: Prevent line wrapping in weird places inside function signature. 583 * Fix: No line wrapping between val and property name. 584 * Fix: Allow passing line prefix into `LineWrapper` to enable proper line wrapping in KDoc. 585 * Fix: Add newline for `TypeSpec` Kdoc with no tags. 586 * Fix: Add newline for remaining Specs. 587 * Fix: Fix kdoc formatting for property getter/setters. 588 * Fix: Don't wrap single line comments inside `FunSpec`. 589 * Fix: Add non-wrapping package name. 590 * Fix: Remove n^2 algorithm in `CodeWriter.resolve()` by precomputing all of the nested simple names of a `TypeSpec`. 591 * Fix: Fix edge case with empty enum classes. 592 * Fix: Fix Nullable Type Parameter handling in `KType.asTypeName()`. 593 * Fix: Fix incorrect long comment wrapping in `FileSpec`. 594 * Fix: Attach primary constructor param/property KDoc to the element vs emitting it inside the type header. 595 596## Version 1.0.1 597 598_2019-01-02_ 599 600 * New: Allow enums without constants. 601 * New: Improved formatting of TypeSpec KDoc. 602 * New: Support @property and @param KDoc tags in TypeSpec. 603 * Fix: Use pre-formatted strings for arguments to %P. 604 605## Version 1.0.0 606 607_2018-12-10_ 608 609 * New: Kotlin 1.3.11. 610 * Fix: Prevent wrapping in import statements. 611 612## Version 1.0.0-RC3 613 614_2018-11-28_ 615 616 * New: Kotlin 1.3.10. 617 * New: Add `%P` placeholder for string templates. 618 * New: Add support for receiver kdoc. 619 * New: Avoid emitting `Unit` as return type. 620 * New: Add support for empty setters. 621 * New: Add checks for inline classes. 622 * New: Escape property and variable names if keywords. 623 * New: Replace `%>`, `%<`, `%[`, `%]` placeholders with `⇥`, `⇤`, `«`, `»`. 624 * New: Replace `%W` with space, and add `·` as a non-breaking space. 625 * New: Change `TypeName` to sealed class. 626 * New: Documentation improvements. 627 * New: Replace `TypeName` modifier methods with `copy()`. 628 * New: Rename members of `WildcardTypeName` to match with the producer/consumer generics model. 629 * New: Rename `TypeName.nullable` into `TypeName.isNullable`. 630 * New: Rename `LambdaTypeName.suspending` into `LambdaTypeName.isSuspending`. 631 * New: Rename `TypeVariableName.reified` into `TypeVariableName.isReified`. 632 * Fix: Emit star-projection only for types with `Any?` upper bound. 633 * Fix: Fold property with escaped name. 634 635## Version 1.0.0-RC2 636 637_2018-10-22_ 638 639 * New: Kotlin 1.2.71. 640 * New: README improvements. 641 * New: Allow opening braces and params in `beginControlFlow()`. 642 * New: Add KDoc to `ParameterSpec`, collapse into parent KDoc. 643 * New: Support `TypeVariable`s in `PropertySpec`. 644 * New: Add parens for annotated types in `LambdaTypeName`. 645 * New: Improve error messaging and documentation for inline properties. 646 * New: Allow sealed classes to declare abstract properties. 647 * New: Added `buildCodeBlock()` helper function. 648 * New: Allow using `CodeBlock`s with statements as property initializers and default parameter values. 649 * New: Rename `NameAllocator.clone()` into `NameAllocator.copy(). 650 * New: Rename `TypeName.asNonNullable()` to `TypeName.asNonNull()`. 651 * New: Remove `PropertySpec.varBuilder()` (use `mutable()` instead). 652 * New: Allow importing top-level members in default package. 653 * New: Add overloads to add KDoc to return type. 654 * Fix: Distinguishing `IntArray` and `Array<Int>` when creating `TypeName`. 655 * Fix: Use `TypeName` instead of `ClassName` as parameter type of `plusParameter()`. 656 * Fix: Keep type-parameter variance when constructing `TypeName` from `KType`. 657 * Fix: Don't validate modifiers when merging properties with primary constructor parameters. 658 * Fix: Escape $ characters in formatted strings. 659 * Fix: `FileSpec.Builder` blank package and subfolder fix. 660 * Fix: Append new line at end of parameter KDoc. 661 * Fix: Add parameter KDoc in `toBuilder()`. 662 663## Version 1.0.0-RC1 664 665_2018-07-16_ 666 667 * New: Escape keywords in imports and canonical class names. 668 * New: Improve `external` support. 669 * New: Extensions for `KType` and `KTypeParameter`. 670 * New: Add builder methods to simplify adding common kotlin.jvm annotations. 671 * New: Enums are able to have companion objects. 672 * New: Add missing primaryConstructor & companionObject to `TypeSpec#toBuilder()`. 673 * New: Make subtype checking vals inside Kind public. 674 * New: Escape (class/property/function/variable) names automatically if they contain space, hyphen, or other symbols. 675 * New: Improve `ParameterizedTypeName` API. 676 * New: Add `WildcardTypeName.STAR` constant. 677 * New: Expose mutable builder properties and move their validations to build-time. 678 * Fix: Use regular indents for parameter lists. 679 * Fix: Inline annotations on properties defined in primary constructor. 680 * Fix: Use `Any?` as the default type variable bounds. 681 * Fix: Fix importing annotated `TypeName`. 682 * Fix: If any primary constructor property has KDoc, put properties on new lines. 683 * Fix: Properly emit where block in type signature. 684 * Fix: Avoid type name collisions in primary constructor. 685 * Fix: Remove implicit `TypeVariable` bound when more bounds are added. 686 * Fix: Combine annotations and modifiers from constructor params and properties. 687 * Fix: Replace delegate constructor args along with the constructor. 688 689## Version 0.7.0 690 691_2018-02-16_ 692 693 * New: Increase indent to 4 spaces. 694 * New: Delegate super interfaces as constructor parameters. 695 * New: Support `PropertySpec`s as `CodeBlock` literals. 696 * New: Support KDoc for `TypeAliasSpec`. 697 * New: Allow for adding an initializer block inside a companion object. 698 * New: Escape name in `ParameterSpec` which is also a keyword. 699 * New: Escape names in statements. 700 * New: Set com.squareup.kotlinpoet as automatic module name. 701 * New: Support suspending lambda types. 702 * New: Support named `LambdaTypeName` parameters. 703 * New: Support dynamic type. 704 * New: Disallow wildcard imports. 705 * New: Depend on Kotlin 1.2.21. 706 * Fix: Correct handling of super-classes/interfaces on anonymous classes. 707 * Fix: Fix boundary filtering to `Any?`. 708 * Fix: Wrap long property initializers. 709 * Fix: Fix formatting and indentation of parameter lists. 710 711## Version 0.6.0 712 713_2017-11-03_ 714 715 * New: Support lambda extensions. 716 * New: Support renames in imports like `import bar.Bar as bBar`. 717 * New: Support extension and inline properties. 718 * New: Support reified types. 719 * New: Expose enclosed types inside `LambdaTypeName`. 720 * New: Depend on Kotlin Kotlin 1.1.51. 721 * New: Improved API and formatting of annotations. 722 * New: Improved multiplatform support. 723 * Fix: Escape function and package names if they are a Kotlin keyword. 724 * Fix: Properly format WildcardTypeName's class declaration. 725 726 727## Version 0.5.0 728 729_2017-09-13_ 730 731 * New: Rename `addFun()` to `addFunction()`. 732 * New: Rename `KotlinFile` to `FileSpec`. 733 * New: Rename `KotlinFile.addFileAnnotation()` to `addAnnotation()`. 734 * New: Rename `KotlinFile.addFileComment()` to `addComment()`. 735 * New: Support cross-platform code, including `HEADER` and `IMPL` modifiers. 736 * New: Support type variables for type aliases. 737 * New: Support constructor delegation. 738 * New: Support named companion objects. 739 * New: Depend on Kotlin 1.1.4-3. 740 * Fix: Format one parameter per line when there are more than two parameters. 741 * Fix: Don't emit braces when the constructor body is empty. 742 * Fix: Do not invoke superclass constructor when no primary constructor. 743 * Fix: Enforce the right modifiers on functions. 744 745 746## Version 0.4.0 747 748_2017-08-08_ 749 750 * New: Change KotlinPoet's extensions like `asClassName()` to be top-level functions. 751 * New: Add declaration-site variance support. 752 * New: Improve handling of single expression bodies. 753 * New: Support file annotations. 754 * New: Support imports from the top-level file. 755 * New: Accept superclass constructor parameters. 756 * New: Support primary constructors using the `constructor` keyword. 757 * Fix: Don't emit setter parameter types. 758 * Fix: Support Kotlin keywords in `NameAllocator`. 759 * Fix: Emit the right default parameters for primary constructors. 760 * Fix: Format annotations properly when used as parameters. 761 * Fix: Recognize imports when emitting nullable types. 762 * Fix: Call through to the superclass constructor when superclass has a no-args constructor. 763 * Fix: Omit class braces if all properties are declared in primary constructor. 764 * Fix: Don't emit empty class bodies. 765 * Fix: Emit the right syntax for declaring multiple generic type constraints. 766 * Fix: Support properties on objects, companions and interfaces. 767 * Fix: Use `AnnotationSpec` for throws. 768 769 770## Version 0.3.0 771 772_2017-06-11_ 773 774 * New: Objects and companion objects. 775 * New: `TypeAliasSpec` to create type aliases. 776 * New: `LambdaTypeName` to create lambda types. 777 * New: Collapse property declarations into constructor params. 778 * New: Extension and invoke functions for creating type names: `Runnable::class.asClassName()`. 779 * New: Basic support for expression bodies. 780 * New: Basic support for custom accessors. 781 * New: Remove `Filer` writing and originating elements concept. These stem from `javac` annotation 782 processors. 783 * Fix: Generate valid annotation classes. 784 * Fix: Use `KModifier` for varargs. 785 * Fix: Use `ParameterizedTypeName` for array types. 786 * Fix: Extract Kotlin name from `KClass` instead of Java name. 787 * Fix: Emit valid class literals: `Double::class` instead of `Double.class`. 788 * Fix: Emit modifiers in the expected order. 789 * Fix: Emit the correct syntax for enum classes and overridden members. 790 791 792## Version 0.2.0 793 794_2017-05-21_ 795 796 * New: Flip API signatures to be (name, type) instead of (type, name). 797 * New: Support for nullable types. 798 * New: Support delegated properties. 799 * New: Extension functions. 800 * New: Support top-level properties. 801 * Fix: Inheritance should use `:` instead of `extends` and `implements`. 802 * Fix: Make initializerBlock emit `init {}`. 803 804 805## Version 0.1.0 806 807_2017-05-16_ 808 809 * Initial public release. 810 811 [kotlinpoet-metadata]: ../kotlinpoet_metadata 812 [kotlinpoet-metadata-specs]: ../kotlinpoet_metadata_specs 813 [explicit-api-mode]: https://kotlinlang.org/docs/reference/whatsnew14.html#explicit-api-mode-for-library-authors 814 [issue-999]: https://github.com/square/kotlinpoet/issues/999 815 [ksp]: https://github.com/google/ksp 816 [ksp-interop-docs]: https://square.github.io/kotlinpoet/interop-ksp/ 817 [javapoet]: https://github.com/square/javapoet 818 [javapoet-interop-docs]: https://square.github.io/kotlinpoet/interop-javapoet/ 819 [kt-18706]: https://youtrack.jetbrains.com/issue/KT-18706 820 821 [martinbonnin]: https://github.com/martinbonnin 822 [idanakav]: https://github.com/idanakav 823 [goooler]: https://github.com/goooler 824 [anandwana001]: https://github.com/anandwana001 825 [evant]: https://github.com/evant 826 [glureau]: https://github.com/glureau 827 [liujingxing]: https://github.com/liujingxing 828 [BoD]: https://github.com/BoD 829 [WhosNickDoglio]: https://github.com/WhosNickDoglio 830 [sullis]: https://github.com/sullis 831 [DRSchlaubi]: https://github.com/DRSchlaubi 832 [seriouslyhypersonic]: https://github.com/seriouslyhypersonic 833 [ephemient]: https://github.com/ephemient 834 [dkilmer]: https://github.com/dkilmer 835 [aksh1618]: https://github.com/aksh1618 836 [zsqw123]: https://github.com/zsqw123 837 [roihershberg]: https://github.com/roihershberg 838 [popematt]: https://github.com/popematt 839 [bitPogo]: https://github.com/bitPogo 840 [mars885]: https://github.com/mars885 841 [sjudd]: https://github.com/sjudd 842 [Sironheart]: https://github.com/Sironheart 843 [polarene]: https://github.com/polarene 844 [DeoTimeTheGithubUser]: https://github.com/DeoTimeTheGithubUser 845 [drawers]: https://github.com/drawers 846 [rickclephas]: https://github.com/rickclephas 847 [Squiry]: https://github.com/Squiry 848 [Omico]: https://github.com/Omico 849 [RBusarow]: https://github.com/RBusarow 850 [fejesjoco]: https://github.com/fejesjoco 851 [takahirom]: https://github.com/takahirom 852 [mcarleio]: https://github.com/mcarleio 853 [gabrielittner]: https://github.com/gabrielittner 854 [jisungbin]: https://github.com/jisungbin 855 [hfhbd]: https://github.com/hfhbd 856 [sgjesse]: https://github.com/sgjesse 857 [sebek64]: https://github.com/sebek64 858 [DanielGronau]: https://github.com/DanielGronau 859 [mitasov-ra]: https://github.com/mitasov-ra 860