Golang Template Engine for Java

中文文档

A Go template engine implementation for Java that evaluates Go templates and generates textual output.

✅ Production Ready: Stable core functionality with 90%+ code coverage, comprehensive built-in functions, and complete documentation.

⚠️ Core Purpose: This project is NOT a replacement for Go's native text/template and does NOT aim to surpass it in performance or features. It exists solely to help Java developers who must work with Go templates meet basic operational needs when dealing with Go-based systems or migrating from Go to Java.

🆕 Latest Release (v0.10.0): Java 11 baseline, compatibility polish, and improved diagnostics.

Quick Start

Requirements

• Java Version: >= 11
• No additional dependencies required (pure Java)

⚠️ Java 8 Support: v0.9.x is the final release line supporting Java 8. The v0.10.0 development line requires Java 11 or higher. See Development Plan for details.

Installation

Maven

Add the dependency to your pom.xml:

<dependency>
    <groupId>io.github.verils</groupId>
    <artifactId>gotemplate4j</artifactId>
    <version>0.10.0</version>
</dependency>

Gradle

Add the dependency to your build.gradle:

dependencies {
    implementation 'io.github.verils:gotemplate4j:0.10.0'
}

For Gradle Kotlin DSL (build.gradle.kts):

dependencies {
    implementation("io.github.verils:gotemplate4j:0.10.0")
}

For more installation options, see the Installation Guide.

Basic Usage

// Create a user as the input data
User user = new User();
user.setName("Bob");

// Prepare your template
Template template = new Template("demo");
template.parse("Hello, {{ .Name }}!");

// Execute and print out the result text
StringWriter writer = new StringWriter();
template.execute(writer, user);
System.out.print(writer.toString());  // "Hello Bob!"

Enhanced File Loading (v0.9.0+)

Load templates from classpath, directories, or with specific encoding:

// Load from classpath
Template tmpl = Template.parseFromClasspath("templates/email.tmpl");

// Load from directory (all .tmpl files)
Map<String, Template> templates = Template.parseDirectory(Paths.get("templates"));

// Load with specific encoding
Template tmpl = Template.parseFile(Paths.get("template.tmpl"), StandardCharsets.UTF_8);

// Batch load from classpath with pattern
List<Template> templates = Template.parseClasspathResources("templates/*.tmpl");

For more examples, see Basic Examples.

Documentation

Comprehensive documentation is available in the docs/ directory:

🚀 Getting Started

• Installation Guide - Add gotemplate4j to your project
• Quick Start Tutorial - Create your first template in 5 minutes
• Basic Concepts - Understand core concepts

📖 User Guide

• Template Syntax Reference - Complete syntax guide
• Working with Java Data - JavaBeans, Maps, Lists, Enums
• Built-in and Custom Functions - Function reference
• Control Flow - If, range, with, break/continue
• Template Sets and Inheritance - Define, template, blocks
• Error Handling - Handle errors gracefully

🔧 Advanced Topics

• Go Template Compatibility - Detailed compatibility guide
• Migration from Go Templates - Step-by-step migration
• Performance Tuning - Optimize template execution
• Security Best Practices - Security considerations
• Design Patterns - Best practices and patterns

📚 API Reference

• Template API - Template class reference
• Function API - Function interface guide
• Exception API - Exception hierarchy

💡 Examples

• Basic Examples - Simple use cases
• Web Templates - HTML generation patterns
• Email Templates - Email generation examples
• Complex Scenarios - Advanced real-world scenarios

❓ FAQ

• Frequently Asked Questions - Common questions and answers

Start here: Documentation Hub

References

• Go text/template Documentation
• Go template Source Code
• Java Template Engine (Alternative)
• Changelog
• Development Plan

Roadmap

See PLAN.md for the detailed development roadmap.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for detailed guidelines.