tpl: add custom functions and new built-in transforms

New built-in transforms:
- |html  — HTML-escape <, >, &, "
- |url   — URL query-encode (net/url.QueryEscape)
- |trim  — strip leading/trailing whitespace
- |json  — JSON-serialize the raw typed value

Custom function registry:
- RegisterFunc(name, func(any) string) — registers a named function
- $var|funcName — applies function to the variable's typed value
- $funcName     — calls function with nil when name is not in params
- Built-in transforms take precedence over registered functions
- Params take precedence over standalone function lookup
- Missing variable + built-in transform keeps the $var|transform placeholder
- Missing variable + registered function calls the function with nil

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: getevo

lib/tpl/tpl.go

@@ -1,8 +1,11 @@
 package tpl
 
 import (
+	"encoding/json"
 	"fmt"
+	htmlpkg "html"
 	"io"
+	neturlpkg "net/url"
 	"strconv"
 	"strings"
 	"sync"
@@ -33,12 +36,43 @@ func SetCacheSize(n int) {
 	}
 }
 
+// Func is the signature for custom template functions.
+// It receives the resolved variable value (or nil for standalone / modifier-on-empty calls)
+// and must return the string to insert into the output.
+type Func func(v any) string
+
+var (
+	funcsMu sync.RWMutex
+	funcs   = map[string]Func{}
+)
+
+// RegisterFunc registers a named function for use in templates.
+// A registered function can be used in two ways:
+//
+//   - modifier:   $var|name  — receives the variable's typed value
+//   - standalone: $name      — receives nil when "name" is not found in params
+//
+// Built-in transform names (upper, lower, title, html, url, trim, json) are
+// reserved and always take precedence over registered functions.
+func RegisterFunc(name string, fn Func) {
+	funcsMu.Lock()
+	funcs[name] = fn
+	funcsMu.Unlock()
+}
+
+func lookupFunc(name string) (Func, bool) {
+	funcsMu.RLock()
+	fn, ok := funcs[name]
+	funcsMu.RUnlock()
+	return fn, ok
+}
+
 // segment is one piece of a compiled template: either a literal string or a
 // variable reference (with optional modifier).
 type segment struct {
 	literal  string
 	path     string
-	modifier string // transform name ("upper","lower","title") or default value
+	modifier string // built-in transform, registered function name, or default value
 	isVar    bool
 }
 
@@ -167,30 +201,54 @@ func (t *Template) writeTo(w io.Writer, params []any) {
 			_, _ = io.WriteString(w, seg.literal)
 			continue
 		}
+
 		val, found := resolve(seg.path, params)
 		out := ""
 		if found {
 			out = stringify(val)
 		}
+
 		switch {
 		case out != "":
-			if seg.modifier != "" && isTransform(seg.modifier) {
-				out = applyTransform(out, seg.modifier)
+			// We have a string value — apply modifier if it is a known transform or function.
+			if seg.modifier != "" {
+				if result, ok := applyModifier(out, val, seg.modifier); ok {
+					out = result
+				}
+				// else: modifier is a default value string — ignore since we already have a value.
 			}
 			_, _ = io.WriteString(w, out)
-		case seg.modifier != "" && !isTransform(seg.modifier):
-			// value missing or empty and modifier is a default — use it
-			_, _ = io.WriteString(w, seg.modifier)
-		case !found:
-			// variable not found, no usable default — keep original placeholder
-			_, _ = io.WriteString(w, "$")
-			_, _ = io.WriteString(w, seg.path)
-			if seg.modifier != "" {
+
+		case seg.modifier != "":
+			// No string value, but there is a modifier.
+			if fn, ok := lookupFunc(seg.modifier); ok {
+				// Registered function — call with nil (no value available).
+				_, _ = io.WriteString(w, fn(nil))
+			} else if isBuiltinTransform(seg.modifier) {
+				// Built-in transform on a missing variable — keep the placeholder.
+				_, _ = io.WriteString(w, "$")
+				_, _ = io.WriteString(w, seg.path)
 				_, _ = io.WriteString(w, "|")
 				_, _ = io.WriteString(w, seg.modifier)
+			} else {
+				// Unknown modifier — treat as a default value.
+				_, _ = io.WriteString(w, seg.modifier)
+			}
+
+		case !found:
+			// Variable not found and no modifier — try the path as a standalone function.
+			if fn, ok := lookupFunc(seg.path); ok {
+				_, _ = io.WriteString(w, fn(nil))
+			} else {
+				// Keep the original placeholder unchanged.
+				_, _ = io.WriteString(w, "$")
+				_, _ = io.WriteString(w, seg.path)
+				if seg.modifier != "" {
+					_, _ = io.WriteString(w, "|")
+					_, _ = io.WriteString(w, seg.modifier)
+				}
 			}
 		}
-		// found but stringifies to "" with a transform → output nothing
 	}
 }
 
@@ -229,24 +287,40 @@ func resolve(path string, params []any) (any, bool) {
 
 var titleCaser = cases.Title(language.English, cases.NoLower)
 
-// applyTransform applies the named string transform to s.
-func applyTransform(s, transform string) string {
-	switch strings.ToLower(transform) {
+// applyModifier applies a modifier to a value.
+// Returns (result, true) when the modifier is a built-in transform or a registered function.
+// Returns ("", false) when the modifier should be treated as a default value string.
+func applyModifier(str string, val any, mod string) (string, bool) {
+	switch strings.ToLower(mod) {
 	case "upper":
-		return strings.ToUpper(s)
+		return strings.ToUpper(str), true
 	case "lower":
-		return strings.ToLower(s)
+		return strings.ToLower(str), true
 	case "title":
-		return titleCaser.String(s)
-	default:
-		return s
+		return titleCaser.String(str), true
+	case "html":
+		return htmlpkg.EscapeString(str), true
+	case "url":
+		return neturlpkg.QueryEscape(str), true
+	case "trim":
+		return strings.TrimSpace(str), true
+	case "json":
+		b, err := json.Marshal(val)
+		if err != nil {
+			return str, true
+		}
+		return string(b), true
+	}
+	if fn, ok := lookupFunc(mod); ok {
+		return fn(val), true
 	}
+	return "", false
 }
 
-// isTransform reports whether m is a known transform name.
-func isTransform(m string) bool {
-	switch strings.ToLower(m) {
-	case "upper", "lower", "title":
+// isBuiltinTransform reports whether mod is a reserved built-in transform name.
+func isBuiltinTransform(mod string) bool {
+	switch strings.ToLower(mod) {
+	case "upper", "lower", "title", "html", "url", "trim", "json":
 		return true
 	}
 	return false

lib/tpl/tpl_test.go

@@ -1,6 +1,7 @@
 package tpl
 
 import (
+	"fmt"
 	"strings"
 	"testing"
 )
@@ -38,14 +39,17 @@ func TestDollarEscape(t *testing.T) {
 	}
 }
 
-func TestTransforms(t *testing.T) {
+func TestBuiltinTransforms(t *testing.T) {
 	cases := []struct {
 		src, want string
 		params    map[string]any
 	}{
 		{"$name|upper", "HELLO WORLD", Pairs("name", "hello world")},
 		{"$name|lower", "hello", Pairs("name", "HELLO")},
 		{"$name|title", "Hello World", Pairs("name", "hello world")},
+		{"$name|trim", "hi", Pairs("name", "  hi  ")},
+		{"$html|html", "&lt;b&gt;bold&lt;/b&gt;", Pairs("html", "<b>bold</b>")},
+		{"$q|url", "hello+world", Pairs("q", "hello world")},
 	}
 	for _, c := range cases {
 		if got := Render(c.src, c.params); got != c.want {
@@ -54,6 +58,21 @@ func TestTransforms(t *testing.T) {
 	}
 }
 
+func TestJsonTransform(t *testing.T) {
+	type Point struct {
+		X, Y int
+	}
+	got := Render("$p|json", Pairs("p", Point{1, 2}))
+	if got != `{"X":1,"Y":2}` {
+		t.Errorf("json transform: got %q", got)
+	}
+	// scalar
+	got = Render("$n|json", Pairs("n", 42))
+	if got != "42" {
+		t.Errorf("json scalar: got %q", got)
+	}
+}
+
 func TestDefault(t *testing.T) {
 	// missing variable uses default
 	if got := Render("$missing|guest", map[string]any{}); got != "guest" {
@@ -125,6 +144,48 @@ func TestMissingVarKept(t *testing.T) {
 	}
 }
 
+func TestRegisterFuncAsModifier(t *testing.T) {
+	RegisterFunc("currency", func(v any) string {
+		if f, ok := v.(float64); ok {
+			return fmt.Sprintf("$%.2f", f)
+		}
+		return fmt.Sprint(v)
+	})
+	got := Render("Total: $amount|currency", Pairs("amount", 99.99))
+	if got != "Total: $99.99" {
+		t.Errorf("currency modifier: got %q", got)
+	}
+}
+
+func TestRegisterFuncStandalone(t *testing.T) {
+	RegisterFunc("greeting", func(_ any) string {
+		return "Hello, World"
+	})
+	// $greeting is not in params — should call the registered function
+	got := Render("$greeting!", map[string]any{})
+	if got != "Hello, World!" {
+		t.Errorf("standalone func: got %q", got)
+	}
+}
+
+func TestRegisterFuncParamShadowsFunc(t *testing.T) {
+	RegisterFunc("shadow", func(_ any) string { return "from-func" })
+	// param value takes precedence over registered function
+	got := Render("$shadow", Pairs("shadow", "from-param"))
+	if got != "from-param" {
+		t.Errorf("param should shadow func: got %q", got)
+	}
+}
+
+func TestRegisterFuncModifierOnMissingVar(t *testing.T) {
+	RegisterFunc("shout", func(_ any) string { return "HEY" })
+	// $x is missing, |shout is a registered function → call with nil
+	got := Render("$x|shout", map[string]any{})
+	if got != "HEY" {
+		t.Errorf("modifier func on missing var: got %q", got)
+	}
+}
+
 func TestCacheSize(t *testing.T) {
 	SetCacheSize(2)
 	Parse("tpl-a-$x")
@@ -157,7 +218,6 @@ func TestCacheHit(t *testing.T) {
 }
 
 func TestMultipleParams(t *testing.T) {
-	// later params fill in gaps from earlier params
 	got := Render("$a $b", Pairs("a", "1"), Pairs("b", "2"))
 	if got != "1 2" {
 		t.Errorf("multi params: got %q", got)