kotlin-excel-dsl

한국어

Kotlin DSL for creating Excel files with type safety and elegant syntax.

Features

• Hybrid API: Annotations for simple cases, DSL for complex ones
• Type Safety: Compile-time verification of configurations
• Declarative Styling: Intuitive style definitions with themes
• Annotation Styling: @HeaderStyle, @BodyStyle, @ConditionalStyle for annotation-based styling
• Conditional Styling: Dynamic styles based on cell values
• Formula Support: Excel formulas with formula("SUM(A1:A10)")
• Header Groups: Multi-row headers with automatic cell merging
• Freeze Panes / Auto Filter / Zebra Stripes: Common Excel features
• Streaming Support: SXSSF for large datasets (1M+ rows)
• Excel Parsing: Type-safe parsing of Excel files into data classes

Requirements

• Kotlin 2.2.0+
• JDK 21+

Installation

dependencies {
    implementation("io.clroot.excel:excel-dsl:$version")
}

Check Releases for the latest version.

Quick Start

DSL Approach

data class User(val name: String, val age: Int, val joinedAt: LocalDate)

val users = listOf(
    User("Alice", 30, LocalDate.of(2024, 1, 15)),
    User("Bob", 25, LocalDate.of(2024, 3, 20))
)

excel {
    sheet<User>("Users") {
        column("Name") { it.name }
        column("Age") { it.age }
        column("Joined") { it.joinedAt }
        rows(users)
    }
}.writeTo(FileOutputStream("users.xlsx"))

Annotation Approach

@Excel
data class User(
    @Column("Name", order = 1) val name: String,
    @Column("Age", order = 2) val age: Int,
    @Column("Joined", order = 3) val joinedAt: LocalDate
)

excelOf(users).writeTo(FileOutputStream("users.xlsx"))

Annotation Styling

@Excel
@HeaderStyle(bold = true, backgroundColor = StyleColor.LIGHT_GRAY)
@BodyStyle(alignment = StyleAlignment.CENTER)
data class StyledUser(
    @Column("Name", order = 1)
    @HeaderStyle(fontColor = StyleColor.BLUE)  // Property-level override
    val name: String,

    @Column("Score", order = 2)
    @ConditionalStyle(ScoreStyler::class)  // Dynamic styling
    val score: Int
)

class ScoreStyler : ConditionalStyler<Int> {
    override fun style(value: Int?): CellStyle? = when {
        value == null -> null
        value >= 90 -> CellStyle(fontColor = Color.GREEN)
        value < 60 -> CellStyle(fontColor = Color.RED)
        else -> null
    }
}

With Theme

excel(theme = Theme.Modern) {
    sheet<User>("Users") {
        column("Name") { it.name }
        column("Age") { it.age }
        rows(users)
    }
}.writeTo(output)

Conditional Styling

excel {
    sheet<Transaction>("Transactions") {
        column("Description") { it.description }
        column("Amount", conditionalStyle = { value: Int? ->
            when {
                value == null -> null
                value < 0 -> fontColor(Color.RED)
                value > 1000000 -> fontColor(Color.GREEN)
                else -> null
            }
        }) { it.amount }
        rows(transactions)
    }
}.writeTo(output)

Formulas

excel {
    sheet<SummaryRow>("Summary") {
        column("Label") { it.label }
        column("Value") { formula("SUM(A1:A10)") }  // Excel formula
        rows(summaryData)
    }
}.writeTo(output)

Parsing Excel Files

@Excel
data class User(
    @Column("Name") val name: String,
    @Column("Email") val email: String,
)

val result = parseExcel<User>(FileInputStream("users.xlsx"))
when (result) {
    is ParseResult.Success -> result.data.forEach { println(it) }
    is ParseResult.Failure -> result.errors.forEach { println(it.message) }
}

Documentation

• Usage Guide - Styling, themes, and advanced features
• Parsing - Excel file parsing configuration
• Error Handling - Exception types and handling
• Performance - Benchmarks and best practices

Module Structure

kotlin-excel-dsl/
├── excel-dsl/   # All-in-one module (recommended)
├── core/        # Core models & DSL
├── annotation/  # @Excel, @Column processing
├── render/      # Apache POI integration
├── theme/       # Predefined themes
└── parser/      # Excel file parsing

License

MIT License