Jet Template Engine

Jet is a high-performance template engine for Go designed to be easy to use, powerful, and secure. It is optimized for low memory footprint and fast execution, often outperforming pre-compiled engines.

Key features include:

• Simple Syntax: Familiar C-like expressions.
• Template Logic: Supports inheritance via extends and composition via block/yield, import, and include.
• Security: Automatic HTML escaping.
• Developer Experience: Descriptive error messages that include filenames and line numbers.

Jet supports standard arithmetic and logical operators:

Arithmetic: +, -, *, /, % Logical: && (and), || (or), ! (not), == (equal), != (not equal), >, >=, <, <= Ternary: x ? y : z (evaluates to y if x is truthy, else z)

Jet uses {{ and }} as default delimiters for template expressions. You can configure alternative delimiters like [[ and ]].

To control whitespace around delimiters, use the {{- and -}} syntax. This trims whitespace (spaces, tabs, carriage returns, and newlines) preceding and following the delimiter. Note that a space character must be adjacent to the dash.

By default, all text outside delimiters is copied verbatim.

Comments in Jet start with {* and end with *}. They are dropped during template parsing and can span multiple lines. Content inside comments, including other template tags, will not be executed.

{* this is a comment *}

{* 
    none of this will be executed: 
    {{ asd }}
    {{ include "./foo.jet" }}
*}

Use try to attempt rendering a block of code without crashing the template engine if an error occurs.

• Buffering: All output inside a try block is buffered. If an error occurs, no content from the try block is included in the final output.
• Catching Errors: You can use a catch block to provide fallback content. You can assign the error to a variable (e.g., {{ catch err }}) to inspect it. Since the error is a Go error, use err.Error() to get the string message.
• Limitations: Errors occurring inside a catch block are not caught and will abort execution. The error variable is only available within the catch block.

{{ try }}
    {{ foo }}
{{ catch err }}
    {{ log(err.Error()) }}
    uh oh, something went wrong: {{ err.Error() }}
{{ end }}

Jet supports several ways to access data from strings, slices, maps, and structs:

• Indexing []: Use this for strings (returns ASCII value), slices/arrays, maps, or structs.
• Field Access .: Use dot notation for maps and structs. If the identifier before the dot is omitted (e.g., {{ .field }}), Jet looks up the field in the current context.
• Slicing [start:end]: Use Go-like syntax to re-slice arrays or slices. The start index is inclusive, and the end index is exclusive.

Jet uses a SafeWriter function type to write directly to the render output stream. This allows you to bypass Jet's default HTML escaping when you want to output pre-escaped or raw content.

Available built-in SafeWriter functions:

• safeHtml: An alias for template.HTMLEscape. Escapes everything that could be interpreted as HTML.
• safeJs: An alias for template.JSEscape. Escapes data to be safe for use in a JavaScript context.
• raw (or unsafe): A writer that performs no escaping at all. Use with extreme caution to avoid XSS vulnerabilities.

The asset packaging workflow relies on Go's go generate tool and build tags:

1. Trigger: When you run go generate, the tool scans your source files for //go:generate annotations.
2. Generation: The command go run assets/generate.go is executed, which uses vfsgen to scan your template directories and generate a Go file (e.g., templates_vfsdata.go).
3. Embedding: By using specific build tags (e.g., // +build deploy_build), the generated file containing the binary data is only included in the binary during specific build processes, preventing development files from bloating your standard builds.
4. Loading: At runtime, the Jet template engine is configured to use the http.FileSystem interface implemented by the generated code to locate and load templates from memory.

Variables must be initialized before use using the := operator. Once initialized, they can be updated using the = operator. Variables in Jet are dynamically typed.

To execute a function or expression without storing its result or rendering it to the output, assign the result to the underscore _ identifier.

{{ foo := "bar" }}
{{ foo = "asd" }}
{{ foo = 4711 }}

{{ _ := stillRuns() }}
{{ _ = stillRuns() }}