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. Control Flow

The engine supports the following Go template control flow keywords:

Keyword Description

if / else / else if

Conditional branching based on truthiness of the pipeline value

range

Iterates over arrays, slices, maps, and collections

with

Sets the dot (.) to the pipeline value if truthy, optionally with an else clause

define / template / block

Named template definition and invocation

break

Exits the innermost range loop early (Go 1.18+)

continue

Skips to the next iteration of the innermost range loop (Go 1.18+)

end

Closes if, range, with, define, and block constructs

4. 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

5. 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.

6. Reference