Template Engine

The jhelm template engine (jhelm-gotemplate) is a Java implementation of Go’s text/template package. It provides the core lexer, parser, AST, and executor pipeline.

1. Architecture

Template String → Lexer → Tokens → Parser → AST → Executor → Output

1.1. Modules

Module Purpose

jhelm-gotemplate

Core engine: lexer, parser, executor, AST nodes, Function interface, FunctionProvider SPI, Go built-in functions

jhelm-gotemplate-sprig

Sprig function library (strings, collections, math, crypto, etc.)

jhelm-gotemplate-helm

Helm function library (toYaml, include, lookup, etc.)

1.2. Key Classes

  • GoTemplate — Entry point for parsing and executing templates

  • Functions.GO_BUILTINS — Immutable map of Go built-in template functions

  • FunctionProvider — SPI interface for extending the function library

  • GoTemplate.Builder — Builder for fine-grained control over function loading

2. Go Built-in Functions

These 19 functions are always available, matching Go’s text/template built-in set. They live in Functions.GO_BUILTINS within jhelm-gotemplate.

2.1. Output

Function Signature Description

print

print arg1 arg2 …​

Concatenates arguments (like Go fmt.Sprint)

printf

printf format arg1 …​

Formats string (like Go fmt.Sprintf). Translates %v → %s, %T → %s

println

println arg1 arg2 …​

Joins arguments with spaces and appends newline

2.2. Logic

Function Signature Description

and

and x y …​

Returns first falsy argument, or last argument if all truthy

or

or x y …​

Returns first truthy argument, or last argument if all falsy

not

not x

Returns boolean negation of argument

2.3. Comparison

Function Signature Description

eq

eq x y …​

Returns true if all arguments equal the first. Handles mixed numeric types (Integer vs Long vs Double)

ne

ne x y

Returns true if arguments are not equal

lt

lt x y

Returns true if x < y (numeric or Comparable)

le

le x y

Returns true if x <= y

gt

gt x y

Returns true if x > y

ge

ge x y

Returns true if x >= y

2.4. Collection

Function Signature Description

index

index collection key

Retrieves element from Map, List, or array by key/index

slice

slice collection [from] [to]

Returns a sub-list/sub-array. from defaults to 0, to defaults to length

len

len collection

Returns length of Collection, Map, String, or array

2.5. Escaping

Function Signature Description

html

html string

HTML-escapes <, >, &, ", '

js

js string

JavaScript-escapes special characters including <, >, &, =

urlquery

urlquery string

URL-encodes using application/x-www-form-urlencoded

2.6. Other

Function Signature Description

call

call function arg1 …​

Invokes a function value with the given arguments

3. Truthiness

Go templates use "truthiness" to evaluate values in conditionals (if, with, and, or). jhelm implements the same rules:

  • null → false

  • Boolean → its value

  • String → false if empty

  • Number → false if zero

  • Collection → false if empty

  • Map → false if empty

  • Array → false if length is zero

  • Everything else → true

4. Usage

// Auto-discovery: finds Sprig + Helm providers on classpath
GoTemplate template = new GoTemplate();
template.parse("greeting", "Hello {{ .name }}!");

StringWriter writer = new StringWriter();
template.execute("greeting", Map.of("name", "World"), writer);
// writer.toString() == "Hello World!"

See Extending Functions for custom function providers.

5. Reference