Package com.squareup.kotlinpoet

Types

AnnotationSpec
Link copied to clipboard

A generated annotation on a declaration.

class AnnotationSpec : Taggable
ClassName
Link copied to clipboard

A fully-qualified class name for top-level and member classes.

class ClassName : TypeName, Comparable<ClassName>
CodeBlock
Link copied to clipboard

A fragment of a .kt file, potentially containing declarations, statements, and documentation. Code blocks are not necessarily well-formed Kotlin code, and are not validated. This class assumes kotlinc will check correctness later!

Code blocks support placeholders like java.text.Format. This class primarily uses a percent sign % but has its own set of permitted placeholders:

  • %L emits a literal value with no escaping. Arguments for literals may be strings, primitives, type declarations, annotations and even other code blocks.

  • %N emits a name, using name collision avoidance where necessary. Arguments for names may be strings (actually any character sequence), parameters, properties, functions, and types.

  • %S escapes the value as a string, wraps it with double quotes, and emits that. For example, 6" sandwich is emitted "6\" sandwich". %S will also escape all dollar signs ($), use %P for string templates.

  • %P - Similar to %S, but doesn't escape dollar signs ($) to allow creation of string templates. If the string contains dollar signs that should be escaped - use %S.

  • %T emits a type reference. Types will be imported if possible. Arguments for types may be classes.

  • %M emits a member reference. A member is either a function or a property. If the member is importable, e.g. it's a top-level function or a property declared inside an object, the import will be resolved if possible. Arguments for members must be of type MemberName.

  • %% emits a percent sign.

  • · emits a space that never wraps. KotlinPoet prefers to wrap lines longer than 100 columns. It does this by replacing normal spaces with a newline and indent. Note that spaces in strings are never wrapped.

  • increases the indentation level.

  • decreases the indentation level.

  • « begins a statement. For multiline statements, every line after the first line is double-indented.

  • » ends a statement.

class CodeBlock
Dynamic
Link copied to clipboard
object Dynamic : TypeName
FileSpec
Link copied to clipboard

A Kotlin file containing top level objects like classes, objects, functions, properties, and type aliases.

Items are output in the following order:

  • Comment

  • Annotations

  • Package

  • Imports

  • Members

class FileSpec : Taggable
FunSpec
Link copied to clipboard

A generated function declaration.

class FunSpec : Taggable, OriginatingElementsHolder
Import
Link copied to clipboard
data class Import : Comparable<Import>
KModifier
Link copied to clipboard
enum KModifier : Enum<KModifier>
KOperator
Link copied to clipboard
enum KOperator : Enum<KOperator>
LambdaTypeName
Link copied to clipboard
class LambdaTypeName : TypeName
MemberName
Link copied to clipboard

Represents the name of a member (such as a function or a property).

data class MemberName
NameAllocator
Link copied to clipboard

Assigns Kotlin identifier names to avoid collisions, keywords, and invalid characters. To use, first create an instance and allocate all of the names that you need. Typically this is a mix of user-supplied names and constants:

val nameAllocator = NameAllocator()
for (property in properties) {
nameAllocator.newName(property.name, property)
}
nameAllocator.newName("sb", "string builder")

Pass a unique tag object to each allocation. The tag scopes the name, and can be used to look up the allocated name later. Typically the tag is the object that is being named. In the above example we use property for the user-supplied property names, and "string builder" for our constant string builder.

Once we've allocated names we can use them when generating code:

val builder = FunSpec.builder("toString")
.addModifiers(KModifier.OVERRIDE)
.returns(String::class)

builder.addStatement("val %N = %T()",
nameAllocator.get("string builder"), StringBuilder::class)

for (property in properties) {
builder.addStatement("%N.append(%N)",
nameAllocator.get("string builder"), nameAllocator.get(property))
}
builder.addStatement("return %N.toString()", nameAllocator.get("string builder"))
return builder.build()

The above code generates unique names if presented with conflicts. Given user-supplied properties with names ab and sb this generates the following:

override fun toString(): kotlin.String {
val sb_ = java.lang.StringBuilder()
sb_.append(ab)
sb_.append(sb)
return sb_.toString()
}

The underscore is appended to sb to avoid conflicting with the user-supplied sb property. Underscores are also prefixed for names that start with a digit, and used to replace name-unsafe characters like space or dash.

When dealing with multiple independent inner scopes, use a copy of the NameAllocator used for the outer scope to further refine name allocation for a specific inner scope.

class NameAllocator
OriginatingElementsHolder
Link copied to clipboard

A type that can have originating elements.

interface OriginatingElementsHolder
ParameterizedTypeName
Link copied to clipboard
class ParameterizedTypeName : TypeName
ParameterSpec
Link copied to clipboard

A generated parameter declaration.

class ParameterSpec : Taggable
PropertySpec
Link copied to clipboard

A generated property declaration.

class PropertySpec : Taggable, OriginatingElementsHolder
Taggable
Link copied to clipboard

A type that can be tagged with extra metadata of the user's choice.

interface Taggable
TypeAliasSpec
Link copied to clipboard

A generated typealias declaration

class TypeAliasSpec : Taggable
TypeName
Link copied to clipboard

Any type in Kotlin's type system. This class identifies simple types like Int and String, nullable types like Int?, composite types like Array<String> and Set<String>, and unassignable types like Unit.

Type names are dumb identifiers only and do not model the values they name. For example, the type name for kotlin.List doesn't know about the size() function, the fact that lists are collections, or even that it accepts a single type parameter.

Instances of this class are immutable value objects that implement equals() and hashCode() properly.

Referencing existing types

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

In an annotation processor you can get a type name instance for a type mirror by calling asTypeName. In reflection code, you can use asTypeName.

Defining new types

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

Create new reference types like com.example.HelloWorld with ClassName.bestGuess. To build composite types like Set<Long>, use the factory methods on ParameterizedTypeName, TypeVariableName, and WildcardTypeName.

sealed class TypeName : Taggable
TypeSpec
Link copied to clipboard

A generated class, interface, or enum declaration.

class TypeSpec : Taggable, OriginatingElementsHolder
TypeVariableName
Link copied to clipboard
class TypeVariableName : TypeName
WildcardTypeName
Link copied to clipboard
class WildcardTypeName : TypeName

Functions

asClassName
Link copied to clipboard
@JvmName(name = "get")
fun Class<*>.asClassName(): ClassName
@JvmName(name = "get")
fun KClass<*>.asClassName(): ClassName
asParameterizedTypeName
Link copied to clipboard

Returns a parameterized type equivalent to type.

@JvmName(name = "get")
fun ParameterizedType.asParameterizedTypeName(): ParameterizedTypeName
asTypeName
Link copied to clipboard

Returns a TypeName equivalent to this Type.

@JvmName(name = "get")
fun Type.asTypeName(): TypeName

Returns a TypeName equivalent to this KClass.

@JvmName(name = "get")
fun KClass<*>.asTypeName(): ClassName

Returns a class name equivalent to given Kotlin KType.

fun KType.asTypeName(): TypeName
asTypeVariableName
Link copied to clipboard

Returns type variable equivalent to element.

@JvmName(name = "get")
fun TypeParameterElement.asTypeVariableName(): TypeVariableName

Returns type variable equivalent to mirror.

@JvmName(name = "get")
fun TypeVariable.asTypeVariableName(): TypeVariableName
fun KTypeParameter.asTypeVariableName(): TypeVariableName
asWildcardTypeName
Link copied to clipboard
@JvmName(name = "get")
fun WildcardType.asWildcardTypeName(): TypeName
buildCodeBlock
Link copied to clipboard

Builds new CodeBlock by populating newly created CodeBlock.Builder using provided builderAction and then converting it to CodeBlock.

inline fun buildCodeBlock(builderAction: CodeBlock.Builder.() -> Unit): CodeBlock
joinToCode
Link copied to clipboard
fun Collection<CodeBlock>.joinToCode(separator: CharSequence, prefix: CharSequence, suffix: CharSequence): CodeBlock
tag
Link copied to clipboard

Returns the tag attached with T as a key, or null if no tag is attached with that key.

inline fun <T : Any> Taggable.tag(): T?

Attaches tag to the request using T as a key. Tags can be read from a request using Taggable.tag. Use null to remove any existing tag assigned for T.

Use this API to attach debugging or other application data to a spec so that you may read it in other APIs or callbacks.

inline fun <T : Any> AnnotationSpec.Builder.tag(tag: T?): AnnotationSpec.Builder
inline fun <T : Any> FileSpec.Builder.tag(tag: T?): FileSpec.Builder
inline fun <T : Any> FunSpec.Builder.tag(tag: T?): FunSpec.Builder
inline fun <T : Any> ParameterSpec.Builder.tag(tag: T?): ParameterSpec.Builder
inline fun <T : Any> PropertySpec.Builder.tag(tag: T?): PropertySpec.Builder
inline fun <T : Any> TypeAliasSpec.Builder.tag(tag: T?): TypeAliasSpec.Builder
inline fun <T : Any> TypeSpec.Builder.tag(tag: T?): TypeSpec.Builder
typeNameOf
Link copied to clipboard
inline fun <T> typeNameOf(): TypeName

Properties

ANNOTATION
Link copied to clipboard
val ANNOTATION: ClassName
ANY
Link copied to clipboard
val ANY: ClassName
ARRAY
Link copied to clipboard
val ARRAY: ClassName
BOOLEAN
Link copied to clipboard
val BOOLEAN: ClassName
BOOLEAN_ARRAY
Link copied to clipboard
val BOOLEAN_ARRAY: ClassName
BYTE
Link copied to clipboard
val BYTE: ClassName
BYTE_ARRAY
Link copied to clipboard
val BYTE_ARRAY: ClassName
CHAR
Link copied to clipboard
val CHAR: ClassName
CHAR_ARRAY
Link copied to clipboard
val CHAR_ARRAY: ClassName
CHAR_SEQUENCE
Link copied to clipboard
val CHAR_SEQUENCE: ClassName
COLLECTION
Link copied to clipboard
val COLLECTION: ClassName
COMPARABLE
Link copied to clipboard
val COMPARABLE: ClassName
DOUBLE
Link copied to clipboard
val DOUBLE: ClassName
DOUBLE_ARRAY
Link copied to clipboard
val DOUBLE_ARRAY: ClassName
DYNAMIC
Link copied to clipboard

Dynamic is a singleton object type, so this is a shorthand for it in Java.

val DYNAMIC: Dynamic
ENUM
Link copied to clipboard
val ENUM: ClassName
FLOAT
Link copied to clipboard
val FLOAT: ClassName
FLOAT_ARRAY
Link copied to clipboard
val FLOAT_ARRAY: ClassName
INT
Link copied to clipboard
val INT: ClassName
INT_ARRAY
Link copied to clipboard
val INT_ARRAY: ClassName
ITERABLE
Link copied to clipboard
val ITERABLE: ClassName
LIST
Link copied to clipboard
val LIST: ClassName
LONG
Link copied to clipboard
val LONG: ClassName
LONG_ARRAY
Link copied to clipboard
val LONG_ARRAY: ClassName
MAP
Link copied to clipboard
val MAP: ClassName
MAP_ENTRY
Link copied to clipboard
val MAP_ENTRY: ClassName
MUTABLE_COLLECTION
Link copied to clipboard
val MUTABLE_COLLECTION: ClassName
MUTABLE_ITERABLE
Link copied to clipboard
val MUTABLE_ITERABLE: ClassName
MUTABLE_LIST
Link copied to clipboard
val MUTABLE_LIST: ClassName
MUTABLE_MAP
Link copied to clipboard
val MUTABLE_MAP: ClassName
MUTABLE_MAP_ENTRY
Link copied to clipboard
val MUTABLE_MAP_ENTRY: ClassName
MUTABLE_SET
Link copied to clipboard
val MUTABLE_SET: ClassName
NOTHING
Link copied to clipboard
val NOTHING: ClassName
NUMBER
Link copied to clipboard
val NUMBER: ClassName
SET
Link copied to clipboard
val SET: ClassName
SHORT
Link copied to clipboard
val SHORT: ClassName
SHORT_ARRAY
Link copied to clipboard
val SHORT_ARRAY: ClassName
STAR
Link copied to clipboard

The wildcard type * which is shorthand for out Any?.

val STAR: WildcardTypeName
STRING
Link copied to clipboard
val STRING: ClassName
THROWABLE
Link copied to clipboard
val THROWABLE: ClassName
U_BYTE
Link copied to clipboard
val U_BYTE: ClassName
U_BYTE_ARRAY
Link copied to clipboard
val U_BYTE_ARRAY: ClassName
U_INT
Link copied to clipboard
val U_INT: ClassName
U_INT_ARRAY
Link copied to clipboard
val U_INT_ARRAY: ClassName
U_LONG
Link copied to clipboard
val U_LONG: ClassName
U_LONG_ARRAY
Link copied to clipboard
val U_LONG_ARRAY: ClassName
U_SHORT
Link copied to clipboard
val U_SHORT: ClassName
U_SHORT_ARRAY
Link copied to clipboard
val U_SHORT_ARRAY: ClassName
UNIT
Link copied to clipboard
val UNIT: ClassName