Gonja Template Engine

PyString is a feature in Gonja that attempts to provide string manipulation behavior as similar as possible to Python 3's string.Formatter and standard string methods. It is designed to bridge the gap for developers moving from Python to Gonja templates.

Key Characteristics

• Python 3 Parity: The implementation targets Python 3.X behavior. Python 2.X (string % dict) compatibility is explicitly out of scope.
• Dialects: Because Python implementations can vary between versions, Gonja supports "dialects" via feature flags to achieve direct parity with specific Python versions.

Tests in Gonja are used with the is operator to trigger conditional behavior within {% if %} blocks or expressions. They allow you to check the properties or types of variables.

{% if variable is string %}
   This was a string: {{ variable }}
{% elif variable is sequence %}
   This was a list: {{ variable | join(",") }}
{% endif %}

Gonja provides global variables that are available in the root scope of your templates by default. You can access these variables directly within your template syntax without passing them explicitly through the context.

{{ gonja.version }}

Variables can be modified using filters. A filter is applied to a variable using the pipe symbol (|) and can accept optional arguments in parentheses. Filters can be chained together, where the output of one filter becomes the input for the next.

Examples

Chaining filters:

{{ "a,b,c" | split(",") | tojson }}

Assigning filtered values:

{% set number = "123" | int %}

Iterating over filtered sequences:

{% for x in {"first": 1, "second": 2} | values %}
  {{- x }}
{% endfor %}

Template inheritance allows you to create a base 'skeleton' template using {% block %} tags. Child templates then use {% extends %} to inherit from the base and override specific blocks with their own content.

Note: The {% extends %} tag must be the very first tag in the child template.

{# base.html #}
<!DOCTYPE html>
<html>
<head>
    {% block head %}{% endblock %}
    <title>{% block title %}{% endblock %}</title>
</head>
<body>
    {% block content %}{% endblock %}
</body>
</html>

{# child.html #}
{% extends "base.html" %}
{% block title %}Index{% endblock %}
{% block content %}
    <h1>Index</h1>
{% endblock %}

Gonja implements most Python str methods to provide high compatibility. However, due to differences between Go and Python (specifically regarding Unicode handling), some discrepancies may exist. For example, unicode.IsNumber("三") in Go returns false, whereas Python's char.isnumeric() returns true.

Not implemented or differently implemented:

• maketrans: Too complex.
• translate: Too complex.
• isidentifier: Not considered highly relevant outside of Python.
• index: Use find instead (it behaves similarly but returns -1 instead of raising an error).
• rindex: Use rfind instead.

Gonja supports calling methods on native Python types using Go implementations. You can invoke these methods directly on string, integer, float, or boolean values within your templates using the standard Python dot notation.

{{ "hello".upper() }}

When using gonja, be aware of the following differences from the original Python Jinja implementation:

• format filter: Uses Go's string formatting syntax instead of Python's. For example, {{ 3.14|stringformat:"%.2f" }} behaves like fmt.Sprintf("%.2f", 3.14).
• Escaping: The escape filter is applied immediately. Consequently, the force_escape filter is not needed.
• Type Methods: Only a subset of native Python type methods (bool, int, float, str, dict, and list) are re-implemented in Go, and their behavior may differ slightly from Python.

To use gonja in your Go project, install or update the v2 package using go get:

go get github.com/nikolalohinski/gonja/v2

You can extend gonja functionality by registering custom filters. To use a custom filter, define a function that matches the expected signature and register it with the gonja environment. Once registered, the filter can be invoked within a template using the pipe (|) syntax.

// Example pattern for registering and using a custom filter
// 1. Define the filter function
myFilter := func(ctx *gonja.Context, args ...interface{}) (interface{}, error) {
    // implementation
    return args[0], nil
}

// 2. Register it with the environment
env := gonja.NewEnvironment()
env.AddFilter("my_filter_name", myFilter)

// 3. Use it in a template string
template, _ := env.FromString("{{ value | my_filter_name }}")