Name	Name	Last commit message	Last commit date
Latest commit History 3 Commits
gradle/wrapper	gradle/wrapper
src	src
.gitignore	.gitignore
LICENSE	LICENSE
NOTICE	NOTICE
README.md	README.md
build.gradle.kts	build.gradle.kts
gradle.properties	gradle.properties
gradlew	gradlew
gradlew.bat	gradlew.bat
settings.gradle.kts	settings.gradle.kts

DocTree

A modern, type-safe Kotlin library for building and manipulating structured document trees.

DocTree provides a clean, fluent API for creating rich document structures programmatically. Whether you're generating reports, building documentation tools, or creating content management systems, DocTree gives you the power to represent complex documents as typed object trees.

✨ Features

🎯 Type-Safe DSL - Build documents using an intuitive Kotlin DSL
🏗️ Clean Architecture - Separation of concerns between API, core, and implementation
🔄 Visitor Pattern - Traverse and transform document trees efficiently
🎨 Rich Styling - Comprehensive styling system for text and blocks
📊 Complex Structures - Support for tables, lists, code blocks, quotes, and more
🔍 Text Extraction - Extract plain text from any document structure
📈 Statistics - Analyze document structure with built-in visitors
🧵 Thread-Safe - ID generation and core operations are thread-safe
🔌 Extensible - Easy to extend with custom node types and visitors

🚀 Quick Start

Installation

Add to your build.gradle.kts:

dependencies {
 implementation("org.codirex.doctree:doc-tree:1.0.0")
}

Basic Usage

import org.codirex.doctree.api.document
import org.codirex.doctree.api.visitor.toPlainText
import org.codirex.doctree.style.*
// Create a document using the fluent DSL
val doc = document {
 metadata {
 title = "Getting Started with DocTree"
 author = "John Doe"
 keywords = listOf("documentation", "kotlin", "tutorial")
 }
 heading(1) {
 text("Welcome to DocTree")
 }
 paragraph {
 text("DocTree is a ")
 bold("powerful")
 text(" and ")
 italic("flexible")
 text(" library for building structured documents.")
 }
 list(ordered = true) {
 item {
 paragraph { text("Easy to use") }
 }
 item {
 paragraph { text("Type-safe") }
 }
 item {
 paragraph { text("Extensible") }
 }
 }
 codeBlock(
 language = "kotlin",
 code = """
 val doc = document {
 paragraph { text("Hello, World!") }
 }
 """.trimIndent()
 )
}
// Extract plain text
val plainText = doc.toPlainText()
println(plainText)

📚 Core Concepts

Document Tree Structure

DocTree represents documents as hierarchical trees of nodes:

Document (root)
├─ Paragraph
│ ├─ TextRun (plain)
│ └─ TextRun (bold)
├─ Heading
│ └─ TextRun
├─ List
│ ├─ ListItem
│ │ └─ Paragraph
│ └─ ListItem
│ └─ Paragraph
└─ Table
 ├─ TableRow
 │ ├─ TableCell
 │ └─ TableCell
 └─ TableRow
 ├─ TableCell
 └─ TableCell

Node Types

Block Elements

Document - Root container for all content
Paragraph - Basic text block with styled runs
Heading - Section headings (levels 1-6)
ListBlock - Ordered or unordered lists
ListItem - Individual list items
CodeBlock - Syntax-highlighted code blocks
BlockQuote - Quoted content
Table - Tabular data with rows and cells
Image - Embedded images
HorizontalRule - Thematic breaks

Text Elements

TextRun - Styled text content with formatting

🎨 Styling System

DocTree provides comprehensive styling capabilities:

Text Styling

paragraph {
 // Basic styling
 text("Normal text")
 bold("Bold text")
 italic("Italic text")
 underline("Underlined")
 strikethrough("Strikethrough")
 // Custom styling
 text("Custom", TextStyle(
 font = Font.ROBOTO,
 size = 14f,
 weight = 600,
 color = Color.BLUE,
 backgroundColor = Color.YELLOW,
 decoration = setOf(TextDecoration.BOLD, TextDecoration.UNDERLINE)
 ))
 // Code styling
 code("inline code")
}

Block Styling

val paragraph = Paragraph(
 id = "para-1",
 style = BlockStyle(
 margin = Spacing.all(16),
 padding = Spacing.symmetric(vertical = 8, horizontal = 12),
 border = Border.all(width = 1, color = Color.BLACK),
 background = Background(color = Color(240, 240, 240)),
 width = Dimension.percent(100f),
 textStyle = TextStyle(size = 14f)
 )
)

Colors

// Predefined colors
val red = Color.RED
val blue = Color.BLUE
// Custom RGB colors
val purple = Color(128, 0, 128)
// Colors with transparency
val semiTransparent = Color(255, 0, 0, 0.5f)
// Hex colors
val orange = Color.fromHex("#FF6600")

🔄 Visitor Pattern

DocTree uses the Visitor pattern for tree traversal and transformation:

Built-in Visitors

Text Extraction

val plainText = document.toPlainText()

Statistics

val stats = document.getStatistics()
println("Paragraphs: ${stats.paragraphCount}")
println("Headings: ${stats.headingCount}")
println("Total words: ${stats.totalWords}")
println("Total characters: ${stats.totalCharacters}")

Custom Visitors

Create custom visitors by extending AbstractNodeVisitor:

class MarkdownExportVisitor : AbstractNodeVisitor<String>() {
 override fun defaultResult() = ""
 override fun visitHeading(heading: Heading): String {
 val hashes = "#".repeat(heading.level)
 return "$hashes ${heading.getPlainText()}\n\n"
 }
 override fun visitParagraph(paragraph: Paragraph): String {
 return "${paragraph.getPlainText()}\n\n"
 }
 override fun visitCodeBlock(codeBlock: CodeBlock): String {
 val lang = codeBlock.language ?: ""
 return "```$lang\n${codeBlock.code}\n```\n\n"
 }
 // Implement other visit methods...
}
// Use the visitor
val markdown = document.accept(MarkdownExportVisitor())

📊 Advanced Examples

Creating a Complex Table

document {
 table(columnCount = 3, hasHeaderRow = true) {
 // Header row
 row {
 cell { paragraph { bold("Name") } }
 cell { paragraph { bold("Age") } }
 cell { paragraph { bold("Role") } }
 }
 // Data rows
 row {
 cell { paragraph { text("Alice") } }
 cell { paragraph { text("30") } }
 cell { paragraph { text("Developer") } }
 }
 row {
 cell { paragraph { text("Bob") } }
 cell { paragraph { text("25") } }
 cell { paragraph { text("Designer") } }
 }
 }
}

Nested Lists

document {
 list(ordered = true) {
 item {
 paragraph { text("First level item 1") }
 }
 item {
 paragraph { text("First level item 2") }
 // Nested list would be added as a separate ListBlock within the item
 }
 }
}

Rich Text with Multiple Styles

paragraph {
 text("This paragraph contains ")
 bold("bold")
 text(", ")
 italic("italic")
 text(", ")
 underline("underlined")
 text(", and ")
 colored("colored", Color.RED)
 text(" text, as well as ")
 highlighted("highlighted", Color.YELLOW)
 text(" content.")
}

🏛️ Architecture

DocTree follows clean architecture principles:

org.codirex.doctree
├── api/ # Public API layer
│ ├── DocumentBuilder # Fluent DSL builder
│ └── visitor/ # Visitor implementations
│ ├── AbstractNodeVisitor
│ ├── TextExtractorVisitor
│ └── NodeCounterVisitor
│
├── core/ # Core domain model
│ ├── Node # Base node interface
│ ├── NodeVisitor # Visitor interface
│ ├── block/ # Block-level elements
│ │ ├── BlockElement # Base block class
│ │ ├── Document
│ │ ├── Paragraph
│ │ ├── Heading
│ │ ├── ListBlock
│ │ ├── CodeBlock
│ │ ├── Table
│ │ └── ...
│ └── text/ # Text-level elements
│ └── TextRun
│
├── style/ # Styling system
│ ├── BlockStyle
│ ├── TextStyle
│ ├── Color
│ ├── Font
│ ├── Border
│ ├── Spacing
│ └── ...
│
└── utils/ # Utilities
 └── IdGenerator # Unique ID generation

Design Principles

Separation of Concerns - Clear boundaries between API, domain, and utilities
Immutability - Style objects are immutable; use copy() for modifications
Type Safety - Strong typing throughout the API
Extensibility - Easy to add new node types and visitors
Testability - Pure functions and dependency injection where needed

🔌 Extensibility

Adding Custom Node Types

Extend BlockElement or implement Node
Add visit method to NodeVisitor interface
Implement in all visitor implementations
Add builder methods if needed

Adding Custom Visitors

Extend AbstractNodeVisitor<R> and override methods for nodes you care about:

class MyCustomVisitor : AbstractNodeVisitor<MyResult>() {
 override fun defaultResult() = MyResult()
 override fun visitParagraph(paragraph: Paragraph): MyResult {
 // Your custom logic
 }
}

⚡ Performance Considerations

Memory Efficiency - Nodes are lightweight; styling is done via immutable data classes
Thread Safety - ID generation is thread-safe; document trees themselves are not inherently thread-safe (use external synchronization if needed)
Lazy Evaluation - Use visitors for on-demand processing
Immutable Styles - Enables safe sharing and caching

🧪 Testing

DocTree is designed for testability:

@Test
fun `should create document with proper structure`() {
 val doc = document {
 heading(1) { text("Title") }
 paragraph { text("Content") }
 }
 val stats = doc.getStatistics()
 assertEquals(1, stats.headingCount)
 assertEquals(1, stats.paragraphCount)
}

📦 Version History

Version 1.0.0

Initial release
Complete document tree model
Fluent DSL API
Visitor pattern support
Comprehensive styling system
Built-in text extraction and statistics visitors

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

Development Setup

Clone the repository
Open in IntelliJ IDEA
Build: ./gradlew build
Test: ./gradlew test

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for the full text. Third-party attributions (if any) are listed in NOTICE.

🙏 Acknowledgments

Built with ❤️ using Kotlin and modern software engineering principles.

📞 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions

Made with 🚀 by Codirex

License

codirex/doc-tree

Folders and files

Latest commit

History

Repository files navigation