tessl/maven-com-squareup--kotlinpoet
Kotlin and Java API for generating Kotlin source files (.kt) with type-safe, fluent builder patterns
—
Pending
file-and-type-generation.mddocs/
File and Type Generation
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 in KotlinPoet.
Capabilities
File Specification
Creates and manages Kotlin source files with package declarations, imports, and top-level declarations.
/**
* Specification for generating .kt source files
*/
class FileSpec private constructor() {
companion object {
/** Creates a builder for a new file with the given package and file name */
fun builder(packageName: String, fileName: String): Builder
/** Creates a builder from a ClassName */
fun builder(className: ClassName): Builder
/** Creates a builder from a MemberName */
fun builder(memberName: MemberName): Builder
/** Creates a file spec from a package name and type spec */
fun get(packageName: String, typeSpec: TypeSpec): FileSpec
/** Creates a builder for a Kotlin script file (.kts) */
fun scriptBuilder(fileName: String, packageName: String = ""): Builder
}
/** Writes the file content to the provided Appendable */
fun writeTo(out: Appendable)
/** Writes the file to the specified directory path */
fun writeTo(directory: Path)
/** Writes the file to the specified directory as a File */
fun writeTo(directory: File)
/** Returns the generated file content as a string */
override fun toString(): String
/** Builder for constructing FileSpec instances */
class Builder {
/** Adds a top-level type declaration to the file */
fun addType(typeSpec: TypeSpec): Builder
/** Adds a top-level function to the file */
fun addFunction(funSpec: FunSpec): Builder
/** Adds a top-level property to the file */
fun addProperty(propertySpec: PropertySpec): Builder
/** Adds a type alias to the file */
fun addTypeAlias(typeAliasSpec: TypeAliasSpec): Builder
/** Adds an import statement */
fun addImport(packageName: String, names: String): Builder
fun addImport(className: ClassName): Builder
fun addImport(memberName: MemberName): Builder
/** Adds an aliased import statement */
fun addAliasedImport(className: ClassName, alias: String): Builder
fun addAliasedImport(memberName: MemberName, alias: String): Builder
/** Adds KDoc documentation to the file */
fun addFileComment(format: String, vararg args: Any): Builder
/** Adds an annotation to the file */
fun addAnnotation(annotationSpec: AnnotationSpec): Builder
/** Sets the default imports for the file */
fun defaultImports(vararg defaultImports: String): Builder
/** Builds the FileSpec */
fun build(): FileSpec
}
}Usage Examples:
import com.squareup.kotlinpoet.*
// Basic file creation
val file = FileSpec.builder("com.example", "Generated")
.addFileComment("Auto-generated file - do not edit")
.addType(
TypeSpec.classBuilder("Example")
.addProperty(PropertySpec.builder("value", Int::class).initializer("42").build())
.build()
)
.build()
// File with multiple top-level declarations
val multiFile = FileSpec.builder("com.example.utils", "Helpers")
.addFunction(
FunSpec.builder("printMessage")
.addParameter("message", String::class)
.addStatement("println(message)")
.build()
)
.addProperty(
PropertySpec.builder("DEFAULT_MESSAGE", String::class)
.addModifiers(KModifier.CONST)
.initializer("%S", "Hello World")
.build()
)
.addTypeAlias(
TypeAliasSpec.builder("StringMap", Map::class.asClassName().parameterizedBy(String::class.asTypeName(), String::class.asTypeName()))
.build()
)
.build()Class Specification
Generates class declarations with support for all Kotlin class types and modifiers.
/**
* Specification for generating class, interface, object, and other type declarations
*/
class TypeSpec private constructor() {
companion object {
/** Creates a builder for a regular class */
fun classBuilder(name: String): Builder
fun classBuilder(className: ClassName): Builder
/** Creates a builder for an interface */
fun interfaceBuilder(name: String): Builder
fun interfaceBuilder(className: ClassName): Builder
/** Creates a builder for an object declaration */
fun objectBuilder(name: String): Builder
fun objectBuilder(className: ClassName): Builder
/** Creates a builder for an annotation class */
fun annotationBuilder(name: String): Builder
fun annotationBuilder(className: ClassName): Builder
/** Creates a builder for an enum class */
fun enumBuilder(name: String): Builder
fun enumBuilder(className: ClassName): Builder
/** Creates a builder for a companion object */
fun companionObjectBuilder(name: String? = null): Builder
/** Creates a builder for an anonymous class */
fun anonymousClassBuilder(): Builder
/** Creates a builder for an expect class (multiplatform) */
@Deprecated("Use classBuilder with KModifier.EXPECT instead")
fun expectClassBuilder(name: String): Builder
fun expectClassBuilder(className: ClassName): Builder
/** Creates a builder for a fun interface */
fun funInterfaceBuilder(name: String): Builder
fun funInterfaceBuilder(className: ClassName): Builder
/** Creates a builder for a value class */
@Deprecated("Use classBuilder with KModifier.VALUE instead")
fun valueClassBuilder(name: String): Builder
fun valueClassBuilder(className: ClassName): Builder
}
/** Builder for constructing TypeSpec instances */
class Builder {
/** Adds modifiers to the type */
fun addModifiers(vararg modifiers: KModifier): Builder
fun addModifiers(modifiers: Iterable<KModifier>): Builder
/** Adds type parameters (generics) */
fun addTypeVariable(typeVariable: TypeVariableName): Builder
fun addTypeVariables(typeVariables: Iterable<TypeVariableName>): Builder
/** Sets the superclass */
fun superclass(superclass: TypeName): Builder
fun superclass(superclass: KClass<*>): Builder
/** Adds superinterfaces */
fun addSuperinterface(superinterface: TypeName): Builder
fun addSuperinterface(superinterface: KClass<*>): Builder
fun addSuperinterface(superinterface: TypeName, delegate: CodeBlock): Builder
/** Adds enum constants (for enum classes) */
fun addEnumConstant(name: String): Builder
fun addEnumConstant(name: String, typeSpec: TypeSpec): Builder
/** Adds properties to the type */
fun addProperty(propertySpec: PropertySpec): Builder
fun addProperties(propertySpecs: Iterable<PropertySpec>): Builder
/** Adds functions to the type */
fun addFunction(funSpec: FunSpec): Builder
fun addFunctions(funSpecs: Iterable<FunSpec>): Builder
/** Adds nested types */
fun addType(typeSpec: TypeSpec): Builder
fun addTypes(typeSpecs: Iterable<TypeSpec>): Builder
/** Adds init blocks */
fun addInitializerBlock(block: CodeBlock): Builder
/** Adds annotations */
fun addAnnotation(annotationSpec: AnnotationSpec): Builder
fun addAnnotation(annotation: ClassName): Builder
fun addAnnotation(annotation: Class<*>): Builder
fun addAnnotation(annotation: KClass<*>): Builder
/** Adds KDoc documentation */
fun addKdoc(format: String, vararg args: Any): Builder
fun addKdoc(block: CodeBlock): Builder
/** Adds context receivers */
fun contextReceivers(receiverTypes: Iterable<TypeName>): Builder
fun contextReceivers(vararg receiverTypes: TypeName): Builder
/** Sets primary constructor */
fun primaryConstructor(primaryConstructor: FunSpec?): Builder
/** Builds the TypeSpec */
fun build(): TypeSpec
}
}Usage Examples:
// Basic class with properties and methods
val personClass = TypeSpec.classBuilder("Person")
.addModifiers(KModifier.DATA)
.primaryConstructor(
FunSpec.constructorBuilder()
.addParameter("name", String::class)
.addParameter("age", Int::class)
.build()
)
.addProperty(PropertySpec.builder("name", String::class).initializer("name").build())
.addProperty(PropertySpec.builder("age", Int::class).initializer("age").build())
.addFunction(
FunSpec.builder("greet")
.returns(String::class)
.addStatement("return %S + name", "Hello, my name is ")
.build()
)
.build()
// Generic interface
val repositoryInterface = TypeSpec.interfaceBuilder("Repository")
.addTypeVariable(TypeVariableName("T"))
.addFunction(
FunSpec.builder("save")
.addModifiers(KModifier.ABSTRACT)
.addParameter("entity", TypeVariableName("T"))
.build()
)
.addFunction(
FunSpec.builder("findById")
.addModifiers(KModifier.ABSTRACT)
.addParameter("id", Long::class)
.returns(TypeVariableName("T").copy(nullable = true))
.build()
)
.build()
// Enum class
val statusEnum = TypeSpec.enumBuilder("Status")
.addEnumConstant("PENDING")
.addEnumConstant("APPROVED")
.addEnumConstant("REJECTED")
.addProperty(
PropertySpec.builder("displayName", String::class)
.initializer("displayName")
.build()
)
.primaryConstructor(
FunSpec.constructorBuilder()
.addParameter("displayName", String::class)
.build()
)
.build()
// Sealed class hierarchy
val resultSealed = TypeSpec.classBuilder("Result")
.addModifiers(KModifier.SEALED)
.addTypeVariable(TypeVariableName("T"))
.addType(
TypeSpec.classBuilder("Success")
.addModifiers(KModifier.DATA)
.addTypeVariable(TypeVariableName("T"))
.superclass(ClassName("", "Result").parameterizedBy(TypeVariableName("T")))
.primaryConstructor(
FunSpec.constructorBuilder()
.addParameter("value", TypeVariableName("T"))
.build()
)
.addProperty(
PropertySpec.builder("value", TypeVariableName("T"))
.initializer("value")
.build()
)
.build()
)
.addType(
TypeSpec.classBuilder("Error")
.addModifiers(KModifier.DATA)
.addTypeVariable(TypeVariableName("T"))
.superclass(ClassName("", "Result").parameterizedBy(TypeVariableName("T")))
.primaryConstructor(
FunSpec.constructorBuilder()
.addParameter("message", String::class)
.build()
)
.addProperty(
PropertySpec.builder("message", String::class)
.initializer("message")
.build()
)
.build()
)
.build()Object and Companion Object Specification
Creates object declarations and companion objects with full support for properties, functions, and initialization.
// Object declaration examples using TypeSpec.objectBuilder()
// Companion object examples using TypeSpec.companionObjectBuilder()Usage Examples:
// Singleton object
val configObject = TypeSpec.objectBuilder("AppConfig")
.addProperty(
PropertySpec.builder("API_URL", String::class)
.addModifiers(KModifier.CONST)
.initializer("%S", "https://api.example.com")
.build()
)
.addFunction(
FunSpec.builder("initialize")
.addStatement("println(%S)", "Initializing app configuration")
.build()
)
.build()
// Class with companion object
val utilityClass = TypeSpec.classBuilder("MathUtils")
.addType(
TypeSpec.companionObjectBuilder()
.addFunction(
FunSpec.builder("max")
.addParameter("a", Int::class)
.addParameter("b", Int::class)
.returns(Int::class)
.addStatement("return if (a > b) a else b")
.build()
)
.build()
)
.build()Install with Tessl CLI
npx tessl i tessl/maven-com-squareup--kotlinpoet