plush

package module
v5.0.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 23, 2026 License: MIT Imports: 25 Imported by: 9

README

Plush

Standard Test Go Reference

Plush is the templating system that Go both needs and deserves. Powerful, flexible, and extendable, Plush is there to make writing your templates that much easier.

Introduction Video

Installation

$ go get -u github.com/gobuffalo/plush

Usage

Plush allows for the embedding of dynamic code inside of your templates. Take the following example:

<!-- input -->
<p><%= "plush is great" %></p>

<!-- output -->
<p>plush is great</p>
Controlling Output

By using the <%= %> tags we tell Plush to dynamically render the inner content, in this case the string plush is great, into the template between the <p></p> tags.

If we were to change the example to use <% %> tags instead the inner content will be evaluated and executed, but not injected into the template:

<!-- input -->
<p><% "plush is great" %></p>

<!-- output -->
<p></p>

By using the <% %> tags we can create variables (and functions!) inside of templates to use later:

<!-- does not print output -->
<%
let h = {name: "mark"}
let greet = fn(n) {
  return "hi " + n
}
%>
<!-- prints output -->
<h1><%= greet(h["name"]) %></h1>
Recursion

Template functions can call themselves by name. Define the function with let name = fn(...) { ... }, then call name(...) inside the function body. This works in both the interpreter and the compiled VM renderer.

<%
let countdown = fn(x) {
  if (x == 0) {
    return "done"
  }
  return countdown(x - 1)
}
%>
<%= countdown(3) %>

renders:

done

Recursive functions can also close over values from the surrounding template scope:

<%
let remaining = 3
let tick = fn() {
  if (remaining == 0) {
    return "done"
  } else {
    remaining = remaining - 1
    return tick()
  }
}
%>
<%= tick() %>

The important rule is that recursive functions need a stopping condition. Without a base case, the function will keep calling itself until the render fails or a configured render budget stops it. Use let and fn; Go-style var a = func() { ... } is not Plush syntax.

Whitespace Trim Output

Use <%- %> when you want to render an expression and remove contiguous whitespace immediately around that tag:

<pre>
<%- "Hello" %>
</pre>

renders:

<pre>Hello</pre>

Only spaces, tabs, \r, and \n directly before the opening tag and directly after the closing tag are trimmed. <%- %> renders and escapes values the same way as <%= %>. Existing <%= %> whitespace behavior is unchanged.

Full Example:
html := `<html>
<%= if (names && len(names) > 0) { %>
	<ul>
		<%= for (n) in names { %>
			<li><%= capitalize(n) %></li>
		<% } %>
	</ul>
<% } else { %>
	<h1>Sorry, no names. :(</h1>
<% } %>
</html>`

ctx := plush.NewContext()
ctx.Set("names", []string{"john", "paul", "george", "ringo"})

s, err := plush.Render(html, ctx)
if err != nil {
  log.Fatal(err)
}

fmt.Print(s)
// output: <html>
// <ul>
// 		<li>John</li>
// 		<li>Paul</li>
// 		<li>George</li>
// 		<li>Ringo</li>
// 		</ul>
// </html>

Comments

You can add comments like this:

<%# This is a comment %>

You can also add line comments within a code section

<%
# this is a comment
not_a_comment()
%>

If/Else Statements

The basic syntax of if/else if/else statements is as follows:

<%
if (true) {
  # do something
} else if (false) {
  # do something
} else {
  # do something else
}
%>

Parentheses around if and else if conditions are optional. The older parenthesized form still works:

<%= if name == "mark" { %>
  hello mark
<% } else if admin { %>
  hello admin
<% } %>

When using if/else statements to control output, remember to use the <%= %> tag to output the result of the statement:

<%= if (true) { %>
  <!-- some html here -->
<% } else { %>
  <!-- some other html here -->
<% } %>
Operators

Complex if statements can be built in Plush using "common" operators:

  • == - checks equality of two expressions
  • != - checks that the two expressions are not equal
  • ~= - checks a string against a regular expression (foo ~= "^fo")
  • < - checks the left expression is less than the right expression
  • <= - checks the left expression is less than or equal to the right expression
  • > - checks the left expression is greater than the right expression
  • >= - checks the left expression is greater than or equal to the right expression
  • && - requires both the left and right expression to be true
  • || - requires either the left or right expression to be true

Numeric equality and ordering are safe across common Go numeric types. This lets backend values such as int32, uint32, uint64, float32, and float64 compare against template integer or float literals without type errors:

<%= product.Count == 0 %>
<%= order.Total > 0.0 %>
<%= uintValue == 3.0 %>
<%= floatValue == 3 %>

The same mixed numeric comparison rules apply to struct fields, map values, indexed values, helper returns, and method returns.

Grouped Expressions
<%= if ((1 < 2) && (someFunc() == "hi")) { %>
  <!-- some html here -->
<% } else { %>
  <!-- some other html here -->
<% } %>

Maps

Maps in Plush will get translated to the Go type map[string]interface{} when used. Creating, and using maps in Plush is not too different than in JSON:

<% let h = {key: "value", "a number": 1, bool: true} %>

Would become the following in Go:

map[string]interface{}{
  "key": "value",
  "a number": 1,
  "bool": true,
}

Accessing maps is just like access a JSON object:

<%= h["key"] %>

Go maps passed through the render context use the same bracket syntax, including typed maps from backend code:

ctx.Set("labels", map[string]string{"status": "ready"})
ctx.Set("counts", map[string]uint32{"active": 7})

<%= labels["status"] %>
<%= counts["active"] %>

When using the compiled VM renderer, static string-key map access is optimized automatically for typed maps such as map[string]string, map[string]uint32, and nested chains such as robots["bender"].Name. The VM caches the access plan and typed map key, not the map value itself.

Using maps as options to functions in Plush is incredibly powerful. See the sections on Functions and Helpers to see more examples.

Arrays

Arrays in Plush will get translated to the Go type []interface{} when used.

<% let a = [1, 2, "three", "four", h] %>

[]interface{}{ 1, 2, "three", "four", h }

Arrays in plush can be appended using the following format:

<% let a = [1, 2, "three", "four", h] %> <% a = a + "hello world"%>

If the array passed to plush is not of type []interface{} and an attempt is made to append a value with a data type that does not match the underlying array type, an error will be returned.

For Loops

There are three different types that can be looped over: maps, arrays/slices, and iterators. The format for them all looks the same:

<%= for (key, value) in expression { %>
  <%= key %> <%= value %>
<% } %>

You can also continue to the next iteration of the loop:

for (i,v) in [1, 2, 3,4,5,6,7,8,9,10] {
  if (i > 0) {
    continue
  }
  return v
}

You can terminate the for loop with break:

for (i,v) in [1, 2, 3,4,5,6,7,8,9,10] {
  if (i > 5) {
    break
  }
  return v
}

The values inside the () part of the statement are the names you wish to give to the key (or index) and the value of the expression. The expression can be an array, map, or iterator type.

Arrays
Using Index and Value
<%= for (i, x) in someArray { %>
  <%= i %> <%= x %>
<% } %>
Using Just the Value
<%= for (val) in someArray { %>
  <%= val %>
<% } %>
Maps
Using Index and Value
<%= for (k, v) in someMap { %>
  <%= k %> <%= v %>
<% } %>
Using Just the Value
<%= for (v) in someMap { %>
  <%= v %>
<% } %>
Iterators
type ranger struct {
	pos int
	end int
}

func (r *ranger) Next() interface{} {
	if r.pos < r.end {
		r.pos++
		return r.pos
	}
	return nil
}

func betweenHelper(a, b int) Iterator {
	return &ranger{pos: a, end: b - 1}
}

html := `<%= for (v) in between(3,6) { return v } %>`

ctx := plush.NewContext()
ctx.Set("between", betweenHelper)

s, err := plush.Render(html, ctx)
if err != nil {
  log.Fatal(err)
}
fmt.Print(s)
// output: 45

Default helpers

Plush ships with a comprehensive list of helpers to make your life easier. For more info check the helpers package.

Custom Helpers
html := `<p><%= one() %></p>
<p><%= greet("mark")%></p>
<%= can("update") { %>
<p>i can update</p>
<% } %>
<%= can("destroy") { %>
<p>i can destroy</p>
<% } %>
`

ctx := NewContext()

// one() #=> 1
ctx.Set("one", func() int {
  return 1
})

// greet("mark") #=> "Hi mark"
ctx.Set("greet", func(s string) string {
  return fmt.Sprintf("Hi %s", s)
})

// can("update") #=> returns the block associated with it
// can("adsf") #=> ""
ctx.Set("can", func(s string, help HelperContext) (template.HTML, error) {
  if s == "update" {
    h, err := help.Block()
    return template.HTML(h), err
  }
  return "", nil
})

s, err := Render(html, ctx)
if err != nil {
  log.Fatal(err)
}
fmt.Print(s)
// output: <p>1</p>
// <p>Hi mark</p>
// <p>i can update</p>

Partial Rendering With Data Maps

Partials can receive a data map as their second argument:

<%= partial("row.plush", {name: product.Name, title: "Robot"}) %>

The keys in the map become local values inside the partial. The values are evaluated from the current render context each time the partial runs.

Parent template:

<%= partial("row.plush", {name: product.Name, title: product.Category.Label}) %>
<%= product.Name %>

Partial source for row.plush:

<span><%= title %>: <%= name %></span>

Go setup:

type Product struct {
  Name     string
  Category Category
}

type Category struct {
  Label string
}

ctx := plush.NewContextWith(map[string]interface{}{
  "product": Product{
    Name:     "Bender",
    Category: Category{Label: "Robot"},
  },
  "partialFeeder": func(name string) (string, error) {
    if name == "row.plush" {
      return `<span><%= title %>: <%= name %></span>`, nil
    }
    return "", fmt.Errorf("unknown partial %s", name)
  },
})

input := `<%= partial("row.plush", {name: product.Name, title: product.Category.Label}) %>
<%= product.Name %>`

html, err := plush.Render(input, ctx)

This renders the partial with name and title available as local values:

<span>Robot: Bender</span>
Bender

Partial data is scoped to that partial render. Passing {name: product.Name} does not replace product.Name or name in the parent context after the partial finishes.

You can pass literals, variables, struct fields, indexed values, and nested property chains:

<%= partial("user.plush", {name: user.Name, role: "admin"}) %>
<%= partial("robot.plush", {name: robots[0].Name, echo: robots[0].Name.Echo()}) %>
<%= partial("row.plush", {label: label(product.Name, prefix)}) %>

Layouts still use the existing Plush partial behavior:

<%= partial("card.plush", {name: product.Name, layout: "shell.plush"}) %>

When using the compiled VM renderer, simple static-key partial data maps are optimized automatically. The VM reuses the compiled partial bytecode, prepares a small key/value binding plan, and writes the evaluated data values into a scoped partial context. Data-map values may also be helper calls such as label(product.Name, prefix); the VM compiles those calls into the data binding plan and uses direct no-reflect invokers for common helper signatures. It does not cache request data, struct values, helper results, or rendered partial output.

Performance Recommendations

Plush now has two render engines:

  • The classic interpreter, which remains the default.
  • The compiled VM renderer, available from github.com/gobuffalo/plush/v5/vm/plush.

For one-off template strings, the interpreter is still a good default because the VM has to parse and compile before it can run. For templates rendered repeatedly, use the VM path.

Best Options
Use case Recommended path Why
Hot template string reused many times vmplush.Compile once, then tmpl.Render(ctx) Avoids parse and compile on every render
File-backed app templates plush.SetRenderMode(plush.RenderModeVM) plus PlushCacheSetup Reuses cached VM bytecode by filename
One-off/dynamic template strings Default plush.Render interpreter Avoids compile overhead when reuse is unlikely
App-specific hot helpers Optional vmplush.SetFastHelper Skips generic reflection for helper hot paths
Compiled Template API

Use this when you can hold a compiled template object:

import (
  "log"

  plush "github.com/gobuffalo/plush/v5"
  vmplush "github.com/gobuffalo/plush/v5/vm/plush"
)

tmpl, err := vmplush.Compile(`<p><%= greet(name) %></p>`)
if err != nil {
  log.Fatal(err)
}

ctx := plush.NewContextWith(map[string]interface{}{
  "name": "mark",
  "greet": func(name string) string {
    return "Hi " + name
  },
})

html, err := tmpl.Render(ctx)

This is the fastest path for repeated renders because the template is parsed and compiled only once.

VM Render Mode

Use this when an application already calls the root plush.Render function and you want to switch that render path to the VM. SetRenderMode is global, so most applications call it once during startup:

import (
  plush "github.com/gobuffalo/plush/v5"
  _ "github.com/gobuffalo/plush/v5/vm/plush"
)

plush.SetRenderMode(plush.RenderModeVM)

The blank import registers the VM renderer. Without it, RenderModeVM cannot call the VM path.

Filename Cache

For file-backed templates, enable a template cache. The interpreter stores parsed ASTs in this cache, and the VM stores compiled bytecode on the same cache entry.

import (
  plush "github.com/gobuffalo/plush/v5"
  _ "github.com/gobuffalo/plush/v5/vm/plush"
  "github.com/gobuffalo/plush/v5/helpers/meta"
  "github.com/gobuffalo/plush/v5/templatecache/inmemory"
)

cache := inmemory.NewMemoryCache()
plush.PlushCacheSetup(cache)
plush.SetRenderMode(plush.RenderModeVM)

ctx := plush.NewContext()
ctx.Set(meta.TemplateFileKey, "templates/items/show.plush.html")

html, err := plush.Render(input, ctx)

The filename must be present in the context for filename-backed cache reuse. On the first render, the VM compiles the template. On later renders of the same filename, it can reuse bytecode.

Compiled Render Diagnostics

Plush records lightweight render diagnostics on the render context. Use these when comparing interpreter and VM mode, confirming bytecode-cache hits, or understanding why a template did or did not use the VM fast path. The diagnostics API lives in render_diagnostics.go.

Diagnostics are collected automatically during plush.Render; no global flag is required for the basic fields.

The normal request flow is:

  1. Set meta.TemplateFileKey on the Plush context for file-backed templates.
  2. Render through plush.Render, BuffaloRendererWithContext, or a compiled VM template.
  3. Read diagnostics after the render with RenderDiagnosticsFromContext or RenderDiagnosticsFromData.
  4. Log the values or expose selected values as internal-only response headers.
import (
  "fmt"

  plush "github.com/gobuffalo/plush/v5"
  _ "github.com/gobuffalo/plush/v5/vm/plush"
  "github.com/gobuffalo/plush/v5/helpers/meta"
)

ctx := plush.NewContext()
ctx.Set(meta.TemplateFileKey, "templates/report/show.plush.html")

plush.SetRenderMode(plush.RenderModeVM)
html, err := plush.Render(input, ctx)
if err != nil {
  return err
}

diagnostics, ok := plush.RenderDiagnosticsFromContext(ctx)
if ok {
  fmt.Printf(
    "mode=%s cache=%s fast=%s engine=%.3fms\n",
    diagnostics.Mode,
    diagnostics.VMBytecodeCache,
    diagnostics.FastPath,
    diagnostics.EngineDurationMilliseconds(),
  )
}

_ = html

Useful fields:

Field Meaning
Mode Render engine used for the call: interpreter or vm.
TemplateFilename Clean filename used for filename-backed cache lookup, when one was present in the context.
VMBytecodeCache VM cache state, such as disabled, miss, miss-store, miss-store-source, hit, hit-static, hit-source, or compiled-template.
FastPath VM execution path, such as static, fast, generic, or interpreter-fallback.
FastReject / FastRejectLine Reason and source line when the compiler could not build a fast render plan.
PunchHoleCache Punch-hole cache state, such as disabled, hit, or miss.
EngineDuration Time spent inside Plush rendering. Use EngineDurationMilliseconds() for reporting.
FastPlan Static complexity counters for the compiled fast plan: bindings, segments, static segments, name segments, property reads, value writes, helper calls, conditionals, loops, loop parts, partials, max depth, helper names, and partial names.
VMHotspots Optional helper and partial call counts/timings when VM hotspot diagnostics are enabled.

FastPlan describes the compiled template shape, not elapsed time. It includes bindings, segments, static segments, name segments, property reads, value writes, helper calls, conditionals, loops, loop parts, partials, max depth, helper names, and partial names.

Hotspot diagnostics are optional. They time VM helper and partial calls, so enable them only when profiling or sampling because they add measurement overhead:

ctx := plush.NewContext()
ctx.Set(meta.TemplateFileKey, "templates/report/show.plush.html")
plush.EnableRenderVMHotspotDiagnostics(ctx)

_, err := plush.Render(input, ctx)
if err != nil {
  return err
}

diagnostics, ok := plush.RenderDiagnosticsFromContext(ctx)
if ok {
  fmt.Printf("helper calls: %d\n", diagnostics.VMHotspots.HelperCalls)
  fmt.Printf("helper time: %.3fms\n", diagnostics.VMHelperDurationMilliseconds())
  fmt.Printf("partial calls: %d\n", diagnostics.VMHotspots.PartialCalls)
  fmt.Printf("partial time: %.3fms\n", diagnostics.VMPartialDurationMilliseconds())
  fmt.Println("helper hotspots:", diagnostics.VMHelperHotspotsHeader())
  fmt.Println("partial hotspots:", diagnostics.VMPartialHotspotsHeader())
}

VMHelperHotspotsHeader() and VMPartialHotspotsHeader() return a compact name:calls:time_ms list sorted by total time, for example formatValue:7:34.660;layout.plush:1:26.120. The list is meant for diagnostics and A/B testing; it is not a stable application data format.

If your renderer creates a Plush context internally and then copies local values back into a data map, use RenderDiagnosticsFromData after rendering. BuffaloRendererWithContext is useful when you also need to set meta.TemplateFileKey or enable hotspot diagnostics:

data := map[string]interface{}{
  "title": "Dashboard",
}

html, err := plush.BuffaloRendererWithContext(input, data, helpers, func(ctx *plush.Context) {
  ctx.Set(meta.TemplateFileKey, "templates/report/show.plush.html")
  plush.EnableRenderVMHotspotDiagnostics(ctx)
})
if err != nil {
  return err
}

diagnostics, ok := plush.RenderDiagnosticsFromData(data)
if ok {
  fmt.Printf("mode=%s cache=%s helper_time=%.3fms\n",
    diagnostics.Mode,
    diagnostics.VMBytecodeCache,
    diagnostics.VMHelperDurationMilliseconds(),
  )
}

_ = html

If an HTTP integration wants response headers, read the diagnostics after rendering and before writing the HTTP response, then map the fields explicitly:

diagnostics, ok := plush.RenderDiagnosticsFromContext(ctx)
if ok {
  w.Header().Set("X-Plush-Render-Mode", diagnostics.Mode)
  w.Header().Set("X-Plush-VM-Bytecode-Cache", diagnostics.VMBytecodeCache)
  w.Header().Set("X-Plush-Template-Filename", diagnostics.TemplateFilename)
  w.Header().Set("X-Plush-Fast-Path", diagnostics.FastPath)
  w.Header().Set("X-Plush-Render-Engine-Time-Ms",
    fmt.Sprintf("%.3f", diagnostics.EngineDurationMilliseconds()))
  w.Header().Set("X-Plush-Punch-Hole-Cache", diagnostics.PunchHoleCache)
  w.Header().Set("X-Plush-Fast-Plan-Bindings",
    fmt.Sprintf("%d", diagnostics.FastPlan.Bindings))
  w.Header().Set("X-Plush-Fast-Plan-Segments",
    fmt.Sprintf("%d", diagnostics.FastPlan.Segments))
  w.Header().Set("X-Plush-Fast-Plan-Static-Segments",
    fmt.Sprintf("%d", diagnostics.FastPlan.StaticSegments))
  w.Header().Set("X-Plush-Fast-Plan-Name-Segments",
    fmt.Sprintf("%d", diagnostics.FastPlan.NameSegments))
  w.Header().Set("X-Plush-Fast-Plan-Property-Reads",
    fmt.Sprintf("%d", diagnostics.FastPlan.PropertyReads))
  w.Header().Set("X-Plush-Fast-Plan-Value-Writes",
    fmt.Sprintf("%d", diagnostics.FastPlan.ValueWrites))
  w.Header().Set("X-Plush-Fast-Plan-Helper-Calls",
    fmt.Sprintf("%d", diagnostics.FastPlan.HelperCalls))
  w.Header().Set("X-Plush-Fast-Plan-Conditionals",
    fmt.Sprintf("%d", diagnostics.FastPlan.Conditionals))
  w.Header().Set("X-Plush-Fast-Plan-Loops",
    fmt.Sprintf("%d", diagnostics.FastPlan.Loops))
  w.Header().Set("X-Plush-Fast-Plan-Loop-Parts",
    fmt.Sprintf("%d", diagnostics.FastPlan.LoopParts))
  w.Header().Set("X-Plush-Fast-Plan-Partials",
    fmt.Sprintf("%d", diagnostics.FastPlan.Partials))
  w.Header().Set("X-Plush-Fast-Plan-Max-Depth",
    fmt.Sprintf("%d", diagnostics.FastPlan.MaxDepth))
  w.Header().Set("X-Plush-Fast-Plan-Helper-Names",
    diagnostics.FastPlanHelperNamesHeader())
  w.Header().Set("X-Plush-Fast-Plan-Partial-Names",
    diagnostics.FastPlanPartialNamesHeader())
  w.Header().Set("X-Plush-VM-Helper-Calls",
    fmt.Sprintf("%d", diagnostics.VMHotspots.HelperCalls))
  w.Header().Set("X-Plush-VM-Helper-Time-Ms",
    fmt.Sprintf("%.3f", diagnostics.VMHelperDurationMilliseconds()))
  w.Header().Set("X-Plush-VM-Partial-Calls",
    fmt.Sprintf("%d", diagnostics.VMHotspots.PartialCalls))
  w.Header().Set("X-Plush-VM-Partial-Time-Ms",
    fmt.Sprintf("%.3f", diagnostics.VMPartialDurationMilliseconds()))
  w.Header().Set("X-Plush-VM-Helper-Hotspots",
    diagnostics.VMHelperHotspotsHeader())
  w.Header().Set("X-Plush-VM-Partial-Hotspots",
    diagnostics.VMPartialHotspotsHeader())
  w.Header().Set("Server-Timing",
    fmt.Sprintf(
      "plush;dur=%.3f, plush_helpers;dur=%.3f, plush_partials;dur=%.3f",
      diagnostics.EngineDurationMilliseconds(),
      diagnostics.VMHelperDurationMilliseconds(),
      diagnostics.VMPartialDurationMilliseconds(),
    ))
}

These X-Plush-* and Server-Timing headers are not emitted by Plush automatically. Plush records the diagnostics; the HTTP application decides which values to expose. In production, put these headers behind a debug, benchmark, or internal-only flag because filenames, helper names, and partial names may reveal application structure.

Common header meanings:

Header Meaning
X-Plush-Render-Mode interpreter or vm, showing which renderer handled this request.
X-Plush-VM-Bytecode-Cache VM cache status. Warm file-backed templates should usually move from miss-store on first render to hit, hit-static, or hit-source on later renders.
X-Plush-Template-Filename Filename used as the cache key when meta.TemplateFileKey was set on the context.
X-Plush-Render-Engine-Time-Ms Time spent inside Plush rendering only, in milliseconds. Use this instead of total request time when comparing interpreter vs VM.
X-Plush-Fast-Path VM execution path: static, fast, generic, or interpreter-fallback. The best steady-state VM path is usually fast; interpreter-fallback means the VM intentionally delegated unsupported syntax to the old interpreter.
X-Plush-Punch-Hole-Cache Punch-hole cache status for templates that mix static HTML with embedded Plush code.
X-Plush-Fast-Plan-* Static counters captured from the compiled fast plan. These describe template complexity, not elapsed time.
X-Plush-Fast-Plan-Helper-Names Helper names the fast plan found while compiling. Useful for spotting expensive helper-heavy templates.
X-Plush-Fast-Plan-Partial-Names Partial names the fast plan found while compiling. Useful for spotting partial-heavy templates.
X-Plush-VM-Helper-* Optional helper-call count and timing fields. They are zero unless EnableRenderVMHotspotDiagnostics was enabled for that context.
X-Plush-VM-Partial-* Optional partial-call count and timing fields. They are zero unless EnableRenderVMHotspotDiagnostics was enabled for that context.
Server-Timing Browser/devtools-friendly timing summary. The example maps Plush engine time plus optional VM helper and partial hotspot time into server timing metrics.

For fair VM measurements, warm file-backed templates until VMBytecodeCache reports hit and FastPath reports fast. A first render may report miss-store because the VM is parsing, compiling, storing bytecode, and then rendering. Fast-plan counters describe template shape, not elapsed time; use EngineDurationMilliseconds, VMHelperDurationMilliseconds, and VMPartialDurationMilliseconds for timings.

Measured Gains

Latest local benchmark checkpoint, VM bytecode cache compared with interpreter AST cache:

Benchmark set Time B/op allocs/op
Full render-mode matrix, 26 scenarios 61.2% faster 59.6% less 71.8% fewer
Realistic mixed template 59.6% faster 73.3% less 81.3% fewer
Simple conditional access output 45.0% faster 32.8% less 65.6% fewer
Nested access/simple access output 55.4% faster 56.7% less 61.8% fewer
Partial simple access bodies 52.5% faster 49.6% less 70.6% fewer
Partial rendering with data maps 53.6% faster 55.6% less 68.9% fewer
Partial data maps with helper-call values 63.4% faster 53.5% less 68.0% fewer
Typed map access 35.6% faster 24.8% less 56.8% fewer
Loop helper direct string calls 69.6% faster 50.6% less 74.5% fewer
Loop helper direct int calls 58.9% faster 51.1% less 70.3% fewer
Mixed numeric operator output 46.4% faster 28.3% less 61.5% fewer

The full matrix includes static output, variable interpolation, helpers, loops, struct fields, nested access, conditionals, regex, partials, whitespace trim, and mixed numeric comparisons. These numbers come from the latest local post-profile checkpoint using medians from count=3 / 500ms. The exact percentage will move with hardware and template shape, but repeated cached VM renders should usually be materially faster than interpreter AST-cache renders.

This checkpoint includes the partial no-overlay fast path, stack-backed partial data locals, helper-call partial data value plans, cleaner cache-key/punch-hole lookup, and lower-allocation request context construction. Some percentages moved because those context changes speed up the interpreter too; the VM partial rows still improved sharply in absolute ns/op, B/op, and allocs/op.

Important caveat: one-shot VM rendering is not the headline number because it includes parse and compile work. Use cached VM render or compiled-template reuse for the real compiled-performance path.

Run the benchmark matrix locally:

go test ./vm/vm -run '^$' -bench '^BenchmarkRenderModeMatrix/.*/(interpreter_ast_cache|vm_bytecode_cache)$' -benchmem -count=3 -benchtime=500ms
Automatic VM Fast Paths

Most VM optimizations need no template changes. The VM automatically specializes common Plush shapes:

  • static output and mixed static/name templates
  • simple mixed templates that combine static text, names, property/access chains, and rendered infix booleans
  • repeated name lookups
  • safe mixed numeric comparisons such as uint32 == 0 and float32 == 3
  • struct fields, nested property chains, indexed property chains, and no-arg method tails
  • typed Go map access with static string keys, such as labels["status"] and robots["bender"].Name
  • loops over strings, slices, structs, and pointers to structs
  • simple top-level conditionals whose branches contain static/name/property/access/infix output
  • conditionals and infix conditions inside loops
  • direct helper calls for common helper signatures
  • direct scalar helper calls for common string, int, uint32, bool, and float64 argument shapes
  • regex match expressions
  • partials with no data, including direct linked rendering when the partial body is simple and does not need partial metadata
  • partials with simple static-key data maps, such as partial("row", {name: product.Name}); the VM prepares the keys and value lookup plan, then reads fresh values each render
  • partial data maps with helper-call values, such as partial("row", {label: label(product.Name, prefix)}); the VM compiles the call arguments and uses direct value invokers for common helper signatures
  • linked partial bodies that contain simple property/access/infix output, such as <%= robot.Name %> or <%= labels["status"] %>
  • clean filename cache keys and punch-hole filename checks for file-backed cached renders

The VM caches plans and bytecode, not request values. It does not cache the current product, helper return values, rendered HTML, partial output, or branch decisions.

Helpers whose Go function signature uses an application-defined scalar parameter, such as func(ProductName, string) string, still use the safe reflective call path unless an app registers a custom fast helper. Go does not safely convert func(ProductName, string) string into func(string, string) string even when ProductName is backed by string.

Advanced Fast Helpers

The VM already specializes common helper shapes at runtime. For example, this normal helper needs no extra setup:

ctx.Set("greet", func(name string) string {
  return "Hi " + name
})

<%= greet(name) %>

For app-specific hot helpers that use broad types like interface{} or complex domain values, you can optionally register a custom fast helper. Keep the normal helper in the context for correctness and fallback.

ctx.Set("money", func(value interface{}) string {
  return formatMoney(value)
})

vmplush.SetFastHelper(ctx, "money", func(w vmplush.FastWriter, args vmplush.FastArgs) error {
  amount, ok := args.Float64(0)
  if !ok {
    return vmplush.ErrFastUnsupported // fall back to the normal helper
  }

  w.WriteEscapedString(formatMoneyFloat(amount))
  return nil
})

The template stays normal:

<%= money(amount) %>

Fast helpers should only optimize the hot path. They must not cache request values or rendered output. Use WriteEscapedString for normal text and WriteHTML only for trusted template.HTML. If a fast helper cannot safely handle the current arguments, return vmplush.ErrFastUnsupported so the VM can call the regular helper.

For generated gRPC/protobuf objects, use args.Raw(i) and type assert to the generated message type:

ctx.Set("productName", func(value interface{}) string {
  product, ok := value.(*pb.Product)
  if !ok || product == nil {
    return ""
  }
  return product.GetName()
})

vmplush.SetFastHelper(ctx, "productName", func(w vmplush.FastWriter, args vmplush.FastArgs) error {
  raw, ok := args.Raw(0)
  if !ok {
    return vmplush.ErrFastUnsupported
  }

  product, ok := raw.(*pb.Product)
  if !ok || product == nil {
    return vmplush.ErrFastUnsupported
  }

  w.WriteEscapedString(product.GetName())
  return nil
})

The template does not change:

<%= productName(product) %>

This avoids reflection and generic property access for the hot helper body while still keeping the normal helper as a safe fallback.

For nested Go structs, the pattern is the same. Register a normal helper first:

type Product struct {
  Name     string
  Category Category
}

type Category struct {
  Label string
}

ctx.Set("productLabel", func(value interface{}) string {
  product, ok := value.(Product)
  if !ok {
    return ""
  }
  return product.Category.Label + ":" + product.Name
})

Then add an optional fast helper for the hot path:

vmplush.SetFastHelper(ctx, "productLabel", func(w vmplush.FastWriter, args vmplush.FastArgs) error {
  raw, ok := args.Raw(0)
  if !ok {
    return vmplush.ErrFastUnsupported
  }

  product, ok := raw.(Product)
  if !ok {
    return vmplush.ErrFastUnsupported
  }

  w.WriteEscapedString(product.Category.Label + ":" + product.Name)
  return nil
})

If the context stores pointers, assert the pointer type and nil-check it:

product, ok := raw.(*Product)
if !ok || product == nil {
  return vmplush.ErrFastUnsupported
}

w.WriteEscapedString(product.Category.Label + ":" + product.Name)

Normal templates can still use regular Plush access without a fast helper:

<%= product.Category.Label %>

Partial calls with simple data maps are also optimized automatically by the VM. See Partial Rendering With Data Maps for syntax and behavior.

Render Budget

Plush lets you attach a work-unit budget to any render to protect against runaway templates — deeply nested loops, recursive partials, or unexpectedly expensive helpers.

A nil budget = unlimited, so all existing code is completely unaffected.

Quick start
b := plush.NewBudget(10_000)
ctx := plush.NewContext()
ctx.Set("products", products)
ctx.WithBudget(b)

html, err := plush.Render(tmpl, ctx)
if errors.Is(err, plush.ErrBudgetExceeded) {
    log.Printf("budget exceeded: used=%d remaining=%d", b.Used(), b.Remaining())
    return errorPage()
}

// One-liner convenience wrapper
html, err = plush.RenderWithBudget(tmpl, 10_000, ctx)
Default operation costs
Operation Default cost
Loop iteration 1
Helper / function call 5
Filter call 3
Partial / sub-render 10
Condition check (if) 1
Variable assignment 0
Object traversal (per segment) 1
Custom costs

Pass a BudgetCosts struct to override any cost:

costs := plush.ZeroCosts()          // start from all-zero
costs.LoopIteration = 1
costs.SubRender     = 25

html, err = plush.RenderWithBudgetConfig(tmpl, 5_000, costs, ctx)
Per-function costs

Override the cost for individual functions registered in the context:

costs := plush.DefaultBudgetCosts()
costs.FunctionCosts = map[string]int64{
    "expensiveQuery": 50, // charged 50 per call instead of the default 5
    "cheapHelper":     1,
}

html, err = plush.RenderWithBudgetConfig(tmpl, 10_000, costs, ctx)

Functions not listed in FunctionCosts fall back to the HelperCall cost.

Stats report

After rendering, call b.Stats() to see exactly where the budget was spent:

b := plush.NewBudget(10_000)
ctx.WithBudget(b)
plush.Render(tmpl, ctx)

s := b.Stats()
fmt.Printf("total=%d  loops=%d  calls=%d  conditions=%d\n",
    s.TotalUsed, s.LoopIterations, s.FunctionCalls, s.ConditionChecks)

for name, units := range s.ByFunction {
    fmt.Printf("  %s: %d units\n", name, units)
}

BudgetStats fields:

Field What it measures
TotalUsed Sum of all units spent
LoopIterations Units from loop iterations
FunctionCalls Units from all function/helper calls
FilterCalls Units from filter calls
SubRenders Units from partial renders
ConditionChecks Units from if/unless evaluations
Assignments Units from variable assignments
ObjectTraversals Units from dot-notation traversal
ByFunction Per-function breakdown (map of name → units)
Special Thanks

This package absolutely, 100%, could not have been written without the help of Thorsten Ball’s incredible books, Writing an Interpreter in Go and Writing a Compiler in Go.

Not only did the book make understanding the process of writing lexers, parsers, and asts, compilers, vm but it also provided the basis for the syntax of Plush itself.

If you have yet to read Thorsten's book, I can't recommend it enough. Please go and buy it!

Documentation

Index

Examples

Constants

View Source 
const (
	RenderModeNameInterpreter = "interpreter"
	RenderModeNameVM          = "vm"

	VMBytecodeCacheDisabled        = "disabled"
	VMBytecodeCacheHit             = "hit"
	VMBytecodeCacheHitStatic       = "hit-static"
	VMBytecodeCacheHitSource       = "hit-source"
	VMBytecodeCacheMiss            = "miss"
	VMBytecodeCacheMissStore       = "miss-store"
	VMBytecodeCacheMissStoreSource = "miss-store-source"
	VMBytecodeCacheDirect          = "compiled-template"

	RenderFastPathStatic              = "static"
	RenderFastPathFast                = "fast"
	RenderFastPathGeneric             = "generic"
	RenderFastPathInterpreterFallback = "interpreter-fallback"

	PunchHoleCacheDisabled = "disabled"
	PunchHoleCacheHit      = "hit"
	PunchHoleCacheMiss     = "miss"
)

Variables

View Source 
var DefaultTimeFormat = "January 02, 2006 15:04:05 -0700"

DefaultTimeFormat is the default way of formatting a time.Time type. This a **GLOBAL** variable, so if you change it, it will change for templates rendered through the `plush` package. If you want to set a specific time format for a particular call to `Render` you can set the `TIME_FORMAT` in the context. 

ctx.Set("TIME_FORMAT", "2006-02-Jan")
s, err = Render(input, ctx)
View Source 
var ErrBudgetExceeded = errors.New("render budget exceeded")

ErrBudgetExceeded is returned when a render exhausts its budget.

View Source 
var ErrVMRendererNotRegistered = errors.New("plush VM renderer is not registered")
View Source 
var Helpers = helpers.NewMap(map[string]interface{}{})

Helpers contains all of the default helpers for These will be available to all templates. You should add any custom global helpers to this list.

View Source 
var PunchHoleCacheLifetime = 1 * time.Minute

Functions

func AddRenderDiagnosticVMHelperTiming added in v5.0.12 

func AddRenderDiagnosticVMHelperTiming(ctx hctx.Context, name string, duration time.Duration)

func AddRenderDiagnosticVMPartialTiming added in v5.0.12 

func AddRenderDiagnosticVMPartialTiming(ctx hctx.Context, name string, duration time.Duration)

func BuffaloRenderer 

func BuffaloRenderer(input string, data map[string]interface{}, helpers map[string]interface{}) (string, error)

BuffaloRenderer implements the render.TemplateEngine interface allowing velvet to be used as a template engine for Buffalo

func BuffaloRendererWithContext added in v5.0.12 

func BuffaloRendererWithContext(input string, data map[string]interface{}, helpers map[string]interface{}, configure func(*Context)) (string, error)

BuffaloRendererWithContext is BuffaloRenderer with an optional context configuration hook. The hook runs after data/helpers are loaded and before rendering, so callers can attach per-render options such as VM fast helpers.

func CachePunchHoleSkeleton added in v5.0.12 

func CachePunchHoleSkeleton(filename string, ctx hctx.Context, skeleton string, holes []HoleMarker, force bool)

func CachePunchHoleSkeletonWithSource added in v5.0.12 

func CachePunchHoleSkeletonWithSource(filename string, ctx hctx.Context, skeleton string, holes []HoleMarker, force bool, source string)

func CacheVMBytecode added in v5.0.12 

func CacheVMBytecode(filename string, ctx hctx.Context, program *ast.Program, bytecode interface{})

func CacheVMBytecodeForCleanFilename added in v5.0.12 

func CacheVMBytecodeForCleanFilename(filename string, program *ast.Program, bytecode interface{})

func CacheVMBytecodeForCleanFilenameWithSource added in v5.0.12 

func CacheVMBytecodeForCleanFilenameWithSource(filename string, program *ast.Program, bytecode interface{}, source string)

func CacheVMBytecodeForFilename added in v5.0.12 

func CacheVMBytecodeForFilename(filename string, program *ast.Program, bytecode interface{})

func CacheVMBytecodeForFilenameWithSource added in v5.0.12 

func CacheVMBytecodeForFilenameWithSource(filename string, program *ast.Program, bytecode interface{}, source string)

func CachedASTProgram added in v5.0.12 

func CachedASTProgram(filename string, ctx hctx.Context) (*ast.Program, bool)

func CachedASTProgramWithSource added in v5.0.12 

func CachedASTProgramWithSource(filename string, ctx hctx.Context, source string) (*ast.Program, bool)

func CachedVMBytecode added in v5.0.12 

func CachedVMBytecode(filename string, ctx hctx.Context) (interface{}, bool)

func CachedVMBytecodeForCleanFilename added in v5.0.12 

func CachedVMBytecodeForCleanFilename(filename string) (interface{}, bool)

func CachedVMBytecodeForCleanFilenameWithSource added in v5.0.12 

func CachedVMBytecodeForCleanFilenameWithSource(filename string, source string) (interface{}, bool)

func CachedVMBytecodeForFilename added in v5.0.12 

func CachedVMBytecodeForFilename(filename string) (interface{}, bool)

func CachedVMBytecodeForFilenameWithSource added in v5.0.12 

func CachedVMBytecodeForFilenameWithSource(filename string, source string) (interface{}, bool)

func ClearTemplateCache added in v5.0.8 

func ClearTemplateCache()

func DisableRenderVMHotspotDiagnostics added in v5.0.12 

func DisableRenderVMHotspotDiagnostics(ctx hctx.Context)

func EnableRenderVMHotspotDiagnostics added in v5.0.12 

func EnableRenderVMHotspotDiagnostics(ctx hctx.Context)

func FillPunchHoles added in v5.0.12 

func FillPunchHoles(rendered string, holes []HoleMarker) (string, error)

func GenerateASTKey added in v5.0.10 

func GenerateASTKey(filename string) string

func GenerateASTKeyFromCleanFilename added in v5.0.12 

func GenerateASTKeyFromCleanFilename(cleanFilename string) string

func GetPunchHoleConcurrencyLimit added in v5.0.12 

func GetPunchHoleConcurrencyLimit() int

func GroupByHelper 

func GroupByHelper(size int, underlying interface{}) (*groupBy, error)

func InterpreterPartialRenderEnabled added in v5.0.12 

func InterpreterPartialRenderEnabled(ctx hctx.Context) bool

InterpreterPartialRenderEnabled reports whether partials should stay on the interpreter path for the current render.

func IsHoleRender added in v5.0.12 

func IsHoleRender(ctx hctx.Context) bool

func IsPlushTemplateFile added in v5.0.12 

func IsPlushTemplateFile(filename string) bool

func IsPunchHoleCacheExpired added in v5.0.12 

func IsPunchHoleCacheExpired(err error) bool

func IsVMBytecodeCacheableTemplateFile added in v5.0.12 

func IsVMBytecodeCacheableTemplateFile(filename string) bool

func PartialHelper 

func PartialHelper(name string, data map[string]interface{}, help HelperContext) (template.HTML, error)

func PlushCacheSetup added in v5.0.8 

func PlushCacheSetup(ts TemplateCache)

func PunchHoleMarkerName added in v5.0.12 

func PunchHoleMarkerName(index int) string

func PunchHoleTemplateFilename added in v5.0.12 

func PunchHoleTemplateFilename(ctx hctx.Context) string

func RegisterVMRenderer added in v5.0.12 

func RegisterVMRenderer(renderer RenderFunc)

func Render 

func Render(input string, ctx hctx.Context) (string, error)

Render a string using the given context.

Example

ExampleRender using `if`, `for`, `else`, functions, etc... 

package main

import (
	"fmt"
	"log"

	"github.com/gobuffalo/plush/v5"
)

func main() {
	html := `<html>
<%= if (names && len(names) > 0) { %>
<ul>
<%= for (n) in names { %>
	<li><%= capitalize(n) %></li>
<% } %>
</ul>
<% } else { %>
	<h1>Sorry, no names. :(</h1>
<% } %>
</html>`

	ctx := plush.NewContext()
	ctx.Set("names", []string{"john", "paul", "george", "ringo"})

	s, err := plush.Render(html, ctx)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Print(s)
}

Output:
<html>

<ul>

	<li>John</li>

	<li>Paul</li>

	<li>George</li>

	<li>Ringo</li>

</ul>

</html>
Example (CustomHelperFunctions) 
package main

import (
	"fmt"
	"html/template"
	"log"

	"github.com/gobuffalo/plush/v5"
)

func main() {
	html := `<p><%= one() %></p>
<p><%= greet("mark")%></p>
<%= can("update") { %>
<p>i can update</p>
<% } %>
<%= can("destroy") { %>
<p>i can destroy</p>
<% } %>
`

	ctx := plush.NewContext()
	ctx.Set("one", func() int {
		return 1
	})
	ctx.Set("greet", func(s string) string {
		return fmt.Sprintf("Hi %s", s)
	})
	ctx.Set("can", func(s string, help plush.HelperContext) (template.HTML, error) {
		if s == "update" {
			h, err := help.Block()
			return template.HTML(h), err
		}
		return "", nil
	})

	s, err := plush.Render(html, ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(s)
}

Output:
<p>1</p>
<p>Hi mark</p>

<p>i can update</p>
Example (ForIterator) 
package main

import (
	"fmt"
	"log"

	"github.com/gobuffalo/plush/v5"
)

func main() {
	html := `<%= for (v) in between(3,6) { %><%=v%><% } %>`

	s, err := plush.Render(html, plush.NewContext())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(s)
}

Output:
45
Example (ScripletTags) 
package main

import (
	"fmt"
	"log"

	"github.com/gobuffalo/plush/v5"
)

func main() {
	html := `<%
let h = {name: "mark"}
let greet = fn(n) {
  return "hi " + n
}
%>
<h1><%= greet(h["name"]) %></h1>`

	s, err := plush.Render(html, plush.NewContext())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(s)
}

Output:
<h1>hi mark</h1>

func RenderDiagnosticsRootActive added in v5.0.12 

func RenderDiagnosticsRootActive(ctx hctx.Context) bool

func RenderFromPunchHoleCache added in v5.0.12 

func RenderFromPunchHoleCache(filename string, ctx hctx.Context) (string, error)

func RenderFromPunchHoleCacheWithSource added in v5.0.12 

func RenderFromPunchHoleCacheWithSource(filename string, source string, ctx hctx.Context) (string, error)

func RenderInterpreter added in v5.0.12 

func RenderInterpreter(input string, ctx hctx.Context) (string, error)

func RenderR 

func RenderR(input io.Reader, ctx hctx.Context) (string, error)

func RenderVMHotspotDiagnosticsEnabled added in v5.0.12 

func RenderVMHotspotDiagnosticsEnabled(ctx hctx.Context) bool

func RenderWithBudget added in v5.0.12 

func RenderWithBudget(input string, limit int64, ctx *Context) (string, error)

RenderWithBudget renders a template and enforces a work-unit limit. Returns ErrBudgetExceeded if the template exhausts the budget. Existing Render() is completely unchanged.

func RenderWithBudgetConfig added in v5.0.12 

func RenderWithBudgetConfig(input string, limit int64, costs BudgetCosts, ctx *Context) (string, error)

RenderWithBudgetConfig renders with a fully custom cost configuration.

func RunScript 

func RunScript(input string, ctx hctx.Context) error

RunScript allows for "pure" plush scripts to be executed.

func SetPunchHoleConcurrencyLimit added in v5.0.12 

func SetPunchHoleConcurrencyLimit(limit int) int

func SetRenderDiagnostics added in v5.0.12 

func SetRenderDiagnostics(ctx hctx.Context, diagnostics RenderDiagnostics)

func SetRenderDiagnosticsRootActive added in v5.0.12 

func SetRenderDiagnosticsRootActive(ctx hctx.Context, active bool) func()

func SetRenderVMHotspotDiagnostics added in v5.0.12 

func SetRenderVMHotspotDiagnostics(ctx hctx.Context, enabled bool)

func SetVMGenericFallback added in v5.0.12 

func SetVMGenericFallback(enabled bool) bool

func UpdateRenderDiagnostics added in v5.0.12 

func UpdateRenderDiagnostics(ctx hctx.Context, update func(*RenderDiagnostics))

func UpdateRenderDiagnosticsForTemplate added in v5.0.12 

func UpdateRenderDiagnosticsForTemplate(ctx hctx.Context, filename string, update func(*RenderDiagnostics))

func VMGenericFallbackEnabled added in v5.0.12 

func VMGenericFallbackEnabled() bool

Types

type Budget added in v5.0.12 

type Budget struct {
	// contains filtered or unexported fields
}

Budget tracks render work units during template evaluation. A nil Budget is always unlimited — zero breaking changes.

func NewBudget added in v5.0.12 

func NewBudget(limit int64) *Budget

NewBudget creates a Budget with a limit and default costs.

func NewBudgetWithCosts added in v5.0.12 

func NewBudgetWithCosts(limit int64, costs BudgetCosts) *Budget

NewBudgetWithCosts creates a Budget with fully custom per-operation costs.

func (*Budget) Costs added in v5.0.12 

func (b *Budget) Costs() BudgetCosts

Costs returns the active cost configuration.

func (*Budget) Remaining added in v5.0.12 

func (b *Budget) Remaining() int64

Remaining returns units left before the limit is hit.

func (*Budget) SpendAssignment added in v5.0.12 

func (b *Budget) SpendAssignment() error

SpendAssignment spends the assignment cost.

func (*Budget) SpendCondition added in v5.0.12 

func (b *Budget) SpendCondition() error

SpendCondition spends the condition check cost.

func (*Budget) SpendFilter added in v5.0.12 

func (b *Budget) SpendFilter() error

SpendFilter spends the filter call cost.

func (*Budget) SpendFunctionCall added in v5.0.12 

func (b *Budget) SpendFunctionCall(name string) error

SpendFunctionCall spends the cost for a named function call. Uses FunctionCosts[name] if set, otherwise falls back to HelperCall cost.

func (*Budget) SpendHelperCall added in v5.0.12 

func (b *Budget) SpendHelperCall() error

SpendHelperCall spends the helper call cost.

func (*Budget) SpendLoop added in v5.0.12 

func (b *Budget) SpendLoop() error

SpendLoop spends the loop iteration cost.

func (*Budget) SpendObjectTraversal added in v5.0.12 

func (b *Budget) SpendObjectTraversal(segments int) error

SpendObjectTraversal spends ObjectTraversal * segments units. e.g. product.variants.first = 3 segments → costs ObjectTraversal * 3

func (*Budget) SpendSubRender added in v5.0.12 

func (b *Budget) SpendSubRender() error

SpendSubRender spends the sub-render cost.

func (*Budget) Stats added in v5.0.12 

func (b *Budget) Stats() BudgetStats

Stats returns a snapshot of work units consumed per operation category. Safe to call at any point during or after rendering.

func (*Budget) Used added in v5.0.12 

func (b *Budget) Used() int64

Used returns total units consumed so far.

func (*Budget) WithCosts added in v5.0.12 

func (b *Budget) WithCosts(costs BudgetCosts) *Budget

WithCosts replaces the cost configuration. Returns self for chaining.

type BudgetCosts added in v5.0.12 

type BudgetCosts struct {
	// LoopIteration is spent once per for-loop iteration.
	// Default: 1
	LoopIteration int64

	// HelperCall is spent each time a registered helper is invoked.
	// Default: 5
	HelperCall int64

	// FilterCall is spent per filter applied (sort, map, where).
	// Default: 3
	FilterCall int64

	// SubRender is spent each time a partial/snippet is rendered.
	// Default: 10
	SubRender int64

	// ConditionCheck is spent per if/unless/case evaluation.
	// Default: 1
	ConditionCheck int64

	// Assignment is spent per variable assignment.
	// Default: 0 (free — rarely the bottleneck)
	Assignment int64

	// ObjectTraversal is spent per dot-notation segment accessed.
	// e.g. product.variants.first = 3 segments = 3 units
	// Default: 1
	ObjectTraversal int64

	// FunctionCosts overrides the default HelperCall cost for specific named
	// functions. The key is the function name as registered in the context.
	// If a name is present here, its cost is used instead of HelperCall.
	// e.g. costs.FunctionCosts = map[string]int64{"expensiveQuery": 50}
	FunctionCosts map[string]int64
}

BudgetCosts defines the work-unit cost for each operation type.

func DefaultBudgetCosts added in v5.0.12 

func DefaultBudgetCosts() BudgetCosts

DefaultBudgetCosts returns recommended production defaults.

func ZeroCosts added in v5.0.12 

func ZeroCosts() BudgetCosts

ZeroCosts returns all-zero costs. Useful for isolating one operation type in tests.

type BudgetStats added in v5.0.12 

type BudgetStats struct {
	// TotalUsed is the sum of all units spent (equals b.Used()).
	TotalUsed int64
	// LoopIterations is total units charged by loop iterations.
	LoopIterations int64
	// FunctionCalls is total units charged by all function/helper calls.
	FunctionCalls int64
	// FilterCalls is total units charged by filter calls.
	FilterCalls int64
	// SubRenders is total units charged by partial/snippet renders.
	SubRenders int64
	// ConditionChecks is total units charged by if/unless evaluations.
	ConditionChecks int64
	// Assignments is total units charged by variable assignments.
	Assignments int64
	// ObjectTraversals is total units charged by dot-notation traversal.
	ObjectTraversals int64
	// ByFunction breaks FunctionCalls down by name for calls made via
	// SpendFunctionCall. Functions without a FunctionCosts override appear
	// here using the generic HelperCall cost.
	ByFunction map[string]int64
}

BudgetStats is a snapshot of work units consumed per operation category. Retrieve it after rendering via b.Stats().

type Context 

type Context struct {
	context.Context
	// contains filtered or unexported fields
}

Context holds all of the data for the template that is being rendered.

func NewContext 

func NewContext() *Context

NewContext returns a fully formed context ready to go

func NewContextWith 

func NewContextWith(data map[string]interface{}) *Context

NewContextWith returns a fully formed context using the data provided.

func NewContextWithContext 

func NewContextWithContext(ctx context.Context) *Context

NewContextWithContext returns a new plush.Context given another context

func NewContextWithOuter 

func NewContextWithOuter(data map[string]interface{}, out *Context) *Context

NewContextWith returns a fully formed context using the data provided and setting the outer context with the passed seccond argument.

func (*Context) Budget added in v5.0.12 

func (c *Context) Budget() *Budget

Budget returns the active budget, walking up the outer chain. Returns nil if no budget is set (unlimited).

func (*Context) Has 

func (c *Context) Has(key string) bool

Has checks the existence of the key in the context.

func (*Context) InternID added in v5.0.12 

func (c *Context) InternID(key string) int

func (*Context) InternIDs added in v5.0.12 

func (c *Context) InternIDs(keys []string, ids []int)

func (*Context) Lookup added in v5.0.12 

func (c *Context) Lookup(key string) (interface{}, bool)

func (*Context) LookupID added in v5.0.12 

func (c *Context) LookupID(id int) (interface{}, bool)

func (*Context) New 

func (c *Context) New() hctx.Context

New context containing the current context. Values set on the new context will not be set onto the original context, however, the original context's values will be available to the new context.

func (*Context) Set 

func (c *Context) Set(key string, value interface{})

Set a value onto the context

func (*Context) SetID added in v5.0.12 

func (c *Context) SetID(id int, value interface{})

func (*Context) Update added in v5.0.4 

func (c *Context) Update(key string, value interface{}) bool

func (*Context) UpdateID added in v5.0.12 

func (c *Context) UpdateID(id int, value interface{}) bool

func (*Context) Value 

func (c *Context) Value(key interface{}) interface{}

Value from the context, or it's parent's context if one exists.

func (*Context) WithBudget added in v5.0.12 

func (c *Context) WithBudget(b *Budget) *Context

WithBudget attaches a Budget to this context. Returns self for chaining.

type ErrUnknownIdentifier 

type ErrUnknownIdentifier struct {
	ID  string
	Err error
}

func (*ErrUnknownIdentifier) Error 

func (e *ErrUnknownIdentifier) Error() string

type HTMLer 

type HTMLer interface {
	HTML() template.HTML
}

HTMLer generates HTML source

type HelperContext 

type HelperContext struct {
	hctx.Context
	// contains filtered or unexported fields
}

HelperContext is an optional last argument to helpers that provides the current context of the call, and access to an optional "block" of code that can be executed from within the helper.

func NewHelperContext added in v5.0.12 

func NewHelperContext(ctx hctx.Context, runner func(hctx.Context) (string, error)) HelperContext

NewHelperContext returns a HelperContext that can execute an optional block using the supplied runner. It is used by alternate execution engines that need to interoperate with helpers accepting plush.HelperContext.

func (HelperContext) Block 

func (h HelperContext) Block() (string, error)

Block executes the block of template associated with the helper, think the block inside of an "if" or "each" statement.

func (HelperContext) BlockWith 

func (h HelperContext) BlockWith(hc hctx.Context) (string, error)

BlockWith executes the block of template associated with the helper, think the block inside of an "if" or "each" statement, but with it's own context.

func (HelperContext) HasBlock 

func (h HelperContext) HasBlock() bool

HasBlock returns true if a block is associated with the helper function

func (HelperContext) Render 

func (h HelperContext) Render(s string) (string, error)

Render a string with the current context

type HoleMarker added in v5.0.8 

type HoleMarker struct {
	// contains filtered or unexported fields
}

func FinalizePunchHolePositions added in v5.0.12 

func FinalizePunchHolePositions(rendered string, holes []HoleMarker) []HoleMarker

func NewHoleMarker added in v5.0.12 

func NewHoleMarker(markerName, input string, start, end int) HoleMarker

func RenderPunchHolesConcurrently added in v5.0.12 

func RenderPunchHolesConcurrently(holes []HoleMarker, ctx hctx.Context) []HoleMarker

func RenderPunchHolesConcurrentlyWith added in v5.0.12 

func RenderPunchHolesConcurrentlyWith(holes []HoleMarker, ctx hctx.Context, renderer func(string, hctx.Context) (string, error)) []HoleMarker

func (HoleMarker) Content added in v5.0.12 

func (h HoleMarker) Content() string

func (HoleMarker) End added in v5.0.12 

func (h HoleMarker) End() int

func (HoleMarker) Err added in v5.0.12 

func (h HoleMarker) Err() error

func (HoleMarker) Input added in v5.0.12 

func (h HoleMarker) Input() string

func (HoleMarker) MarkerName added in v5.0.12 

func (h HoleMarker) MarkerName() string

func (HoleMarker) Start added in v5.0.12 

func (h HoleMarker) Start() int

type InternTable added in v5.0.4 

type InternTable struct {
	// contains filtered or unexported fields
}

func NewInternTable added in v5.0.4 

func NewInternTable() *InternTable

func (*InternTable) Intern added in v5.0.4 

func (it *InternTable) Intern(name string) int

func (*InternTable) Lookup added in v5.0.4 

func (it *InternTable) Lookup(name string) (int, bool)

func (*InternTable) Name added in v5.0.12 

func (it *InternTable) Name(id int) (string, bool)

func (*InternTable) SymbolName added in v5.0.4 

func (it *InternTable) SymbolName(id int) string

type Iterator 

type Iterator interface {
	Next() interface{}
}

Iterator type can be implemented and used by the `for` command to build loops in templates

type PartialFeeder 

type PartialFeeder func(string) (string, error)

PartialFeeder is callback function should implemented on application side.

type RenderDiagnostics added in v5.0.12 

type RenderDiagnostics struct {
	Mode             string
	TemplateFilename string
	VMBytecodeCache  string
	FastPath         string
	FastRejectLine   int
	FastReject       string
	PunchHoleCache   string
	EngineDuration   time.Duration
	FastPlan         RenderFastPlanDiagnostics
	VMHotspots       RenderVMHotspotDiagnostics
}

func RenderDiagnosticsFromContext added in v5.0.12 

func RenderDiagnosticsFromContext(ctx hctx.Context) (RenderDiagnostics, bool)

func RenderDiagnosticsFromData added in v5.0.12 

func RenderDiagnosticsFromData(data map[string]interface{}) (RenderDiagnostics, bool)

func (RenderDiagnostics) EngineDurationMilliseconds added in v5.0.12 

func (d RenderDiagnostics) EngineDurationMilliseconds() float64

func (RenderDiagnostics) FastPlanHelperNamesHeader added in v5.0.12 

func (d RenderDiagnostics) FastPlanHelperNamesHeader() string

func (RenderDiagnostics) FastPlanPartialNamesHeader added in v5.0.12 

func (d RenderDiagnostics) FastPlanPartialNamesHeader() string

func (RenderDiagnostics) VMHelperDurationMilliseconds added in v5.0.12 

func (d RenderDiagnostics) VMHelperDurationMilliseconds() float64

func (RenderDiagnostics) VMHelperHotspotsHeader added in v5.0.12 

func (d RenderDiagnostics) VMHelperHotspotsHeader() string

func (RenderDiagnostics) VMPartialDurationMilliseconds added in v5.0.12 

func (d RenderDiagnostics) VMPartialDurationMilliseconds() float64

func (RenderDiagnostics) VMPartialHotspotsHeader added in v5.0.12 

func (d RenderDiagnostics) VMPartialHotspotsHeader() string

type RenderFastPlanDiagnostics added in v5.0.12 

type RenderFastPlanDiagnostics struct {
	Bindings       int
	Segments       int
	StaticSegments int
	NameSegments   int
	PropertyReads  int
	ValueWrites    int
	HelperCalls    int
	Conditionals   int
	Loops          int
	LoopParts      int
	Partials       int
	MaxDepth       int
	HelperNames    []string
	PartialNames   []string
}

type RenderFunc added in v5.0.12 

type RenderFunc func(string, hctx.Context) (string, error)

type RenderMode added in v5.0.12 

type RenderMode int32
const (
	RenderModeInterpreter RenderMode = iota
	RenderModeVM
)

func GetRenderMode added in v5.0.12 

func GetRenderMode() RenderMode

func SetRenderMode added in v5.0.12 

func SetRenderMode(mode RenderMode) RenderMode

type RenderVMHotspot added in v5.0.12 

type RenderVMHotspot struct {
	Name     string
	Calls    int
	Duration time.Duration
}

type RenderVMHotspotDiagnostics added in v5.0.12 

type RenderVMHotspotDiagnostics struct {
	HelperCalls     int
	HelperDuration  time.Duration
	PartialCalls    int
	PartialDuration time.Duration
	Helpers         []RenderVMHotspot
	Partials        []RenderVMHotspot
}

type SymbolTable added in v5.0.4 

type SymbolTable struct {
	// contains filtered or unexported fields
}

SymbolTable represents a scope

func NewScope added in v5.0.4 

func NewScope(parent *SymbolTable) *SymbolTable

NewScope creates a new scope with an optional parent

func (*SymbolTable) Assign added in v5.0.4 

func (s *SymbolTable) Assign(name string, value interface{}) bool

Assign searches outer scopes and updates an existing variable

func (*SymbolTable) AssignID added in v5.0.12 

func (s *SymbolTable) AssignID(id int, value interface{}) bool

func (*SymbolTable) Declare added in v5.0.4 

func (s *SymbolTable) Declare(name string, value interface{})

Declare adds or updates a variable in the current scope

func (*SymbolTable) DeclareID added in v5.0.12 

func (s *SymbolTable) DeclareID(id int, value interface{})

func (*SymbolTable) Has added in v5.0.4 

func (s *SymbolTable) Has(name string) bool

Has finds the value of a variable

func (*SymbolTable) Resolve added in v5.0.4 

func (s *SymbolTable) Resolve(name string) (interface{}, bool)

Resolve finds the value of a variable

func (*SymbolTable) ResolveID added in v5.0.12 

func (s *SymbolTable) ResolveID(id int) (interface{}, bool)

func (*SymbolTable) SymbolName added in v5.0.12 

func (s *SymbolTable) SymbolName(id int) (string, bool)

type Template 

type Template struct {
	Input      string
	Program    *ast.Program
	PunchHole  []HoleMarker
	Skeleton   string
	VMBytecode interface{}
	SourceHash string
	IsCache    bool
	LastCached time.Time
}

Template represents an input and helpers to be used to evaluate and render the input.

func NewTemplate 

func NewTemplate(input string) (*Template, error)

NewTemplate from the input string. Adds all of the global helper functions from "Helpers", this function does not cache the template.

func Parse 

func Parse(input ...string) (*Template, error)

Parse an input string and return a Template, and caches the parsed template.

func (*Template) Clone 

func (t *Template) Clone() *Template

Clone a template. This is useful for defining helpers on per "instance" of the template.

func (*Template) Exec 

func (t *Template) Exec(ctx hctx.Context) (string, []HoleMarker, error)

Exec the template using the content and return the results

func (*Template) Parse 

func (t *Template) Parse() error

Parse the template this can be called many times as a successful result is cached and is used on subsequent uses.

type TemplateCache added in v5.0.8 

type TemplateCache interface {
	// Get retrieves a cached template by key.
	Get(key string) (*Template, bool)
	// Set stores a template in the cache.
	Set(key string, t *Template)
	// Delete removes a template from the cache.
	Delete(key ...string)

	Clear()
}

Source Files

View all Source files

Directories

Path Synopsis
content
debug
encoders
env
escapes
hctx
helptest
inflections
iterators
meta
paths
text
templatecache
inmemory
vm
code
compiler
object
plush

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.