value

func NewIterator ¶

func NewIterator(name string, items []Value) *Iterator

NewIterator creates a new iterator from items.

func GetObjectRepr ¶

func GetObjectRepr(obj Object) ObjectRepr

GetObjectRepr returns the representation type of an object.

func False ¶

func False() Value

False returns the boolean false value.

This is a convenience function equivalent to FromBool(false).

func FromAny ¶

func FromAny(v any) Value

FromAny creates a Value from any Go value using reflection.

FromAny automatically converts Go types to their corresponding Value types:

• nil -> None()
• bool -> FromBool()
• int types -> FromInt()
• uint types -> FromInt()
• float types -> FromFloat()
• string -> FromString()
• []byte -> FromBytes()
• slices/arrays -> FromSlice() (recursively)
• maps -> FromMap() (recursively)
• structs -> FromMap() (using exported fields and json tags)
• pointers/interfaces -> dereference and convert

This is the most convenient way to convert Go data to Values, but it uses reflection and may be slower than using specific constructors.

Example usage:

data := FromAny(map[string]interface{}{
    "name": "Alice",
    "age":  30,
    "tags": []string{"admin", "user"},
})
// Equivalent to:
// FromMap(map[string]Value{
//     "name": FromString("Alice"),
//     "age": FromInt(30),
//     "tags": FromSlice([]Value{
//         FromString("admin"),
//         FromString("user"),
//     }),
// })

func FromBigInt ¶

func FromBigInt(v *big.Int) Value

FromBigInt creates a Value from a big.Int for arbitrary-precision integers.

Big integers are used when values exceed the range of int64. They support the same arithmetic operations as regular integers.

Example usage:

large := new(big.Int)
large.SetString("123456789012345678901234567890", 10)
val := FromBigInt(large)
// In template: {{ val + 1 }}

func FromBool ¶

func FromBool(v bool) Value

FromBool creates a Value from a boolean.

Example usage:

isActive := FromBool(true)
// In template: {% if isActive %}...{% endif %}

func FromBytes ¶

func FromBytes(v []byte) Value

FromBytes creates a Value from a byte slice.

Byte values represent binary data. They can be used for non-text content and are distinct from strings (which are UTF-8 text).

Example usage:

data := FromBytes([]byte{0x48, 0x65, 0x6c, 0x6c, 0x6f})
// In template: {{ data }}  -> Hello

func FromCallable ¶

func FromCallable(c Callable) Value

FromCallable creates a Value from a Callable.

Callables can be invoked from templates using function call syntax. This is useful for exposing custom functions to templates.

Example usage:

type MyFunc struct{}
func (f *MyFunc) Call(args []Value, kwargs map[string]Value) (Value, error) {
    return FromString("Hello!"), nil
}

fn := FromCallable(&MyFunc{})
context := FromMap(map[string]Value{"greet": fn})
// In template: {{ greet() }}  -> Hello!

func FromFloat ¶

func FromFloat(v float64) Value

FromFloat creates a Value from a float64.

Floating-point values support arithmetic operations. Special values like infinity and NaN are handled according to Go's float64 semantics.

Example usage:

price := FromFloat(19.99)
// In template: {{ price * 1.2 }}  -> 23.988

func FromInt ¶

func FromInt(v int64) Value

FromInt creates a Value from an int64.

Integer values support arithmetic operations and can be compared.

Example usage:

count := FromInt(42)
// In template: {{ count + 1 }}  -> 43

func FromIterator ¶

func FromIterator(iter *Iterator) Value

FromIterator creates a Value from an Iterator.

func FromMap ¶

func FromMap(v map[string]Value) Value

FromMap creates a Value from a map of string to Value.

Maps represent key-value associations (dictionaries/objects) that can be accessed using dot notation or bracket notation in templates. They correspond to objects in JSON and dicts in Python.

Example usage:

user := FromMap(map[string]Value{
    "name":  FromString("Alice"),
    "age":   FromInt(30),
    "email": FromString("[email protected]"),
})
// In template: {{ user.name }}  -> Alice
// In template: {{ user["age"] }}  -> 30
// In template: {% for key in user %}{{ key }}{% endfor %}

func FromObject ¶

func FromObject(o Object) Value

FromObject creates a Value from an Object.

Objects expose attributes that can be accessed from templates using dot notation. This is useful for exposing custom types with specific attribute access semantics.

Example usage:

type User struct {
    Name string
    Age  int
}

func (u *User) GetAttr(name string) Value {
    switch name {
    case "name": return FromString(u.Name)
    case "age": return FromInt(int64(u.Age))
    default: return Undefined()
    }
}

user := &User{Name: "Alice", Age: 30}
val := FromObject(user)
// In template: {{ user.name }}  -> Alice

func FromSafeString ¶

func FromSafeString(v string) Value

FromSafeString creates a Value from a safe (pre-escaped) string.

Safe strings are marked as already escaped and will not be escaped again by auto-escaping. This is useful when you want to include HTML or other markup that should be rendered as-is.

Example usage:

html := FromSafeString("<b>Bold</b>")
// In template with escaping: {{ html }}  -> <b>Bold</b>

Use this with caution - ensure the string is actually safe to prevent XSS.

func FromSlice ¶

func FromSlice(v []Value) Value

FromSlice creates a Value from a slice of Values.

Slices represent ordered sequences (arrays/lists) that can be iterated over and indexed by position. They correspond to arrays in JSON and lists in Python.

Example usage:

items := FromSlice([]Value{
    FromString("apple"),
    FromString("banana"),
    FromString("cherry"),
})
// In template: {% for item in items %}{{ item }}{% endfor %}
// In template: {{ items[0] }}  -> apple
// In template: {{ items|length }}  -> 3

func FromString ¶

func FromString(v string) Value

FromString creates a Value from a string.

String values are not marked as safe and will be escaped by auto-escaping if enabled. For pre-escaped HTML, use FromSafeString instead.

Example usage:

name := FromString("Alice")
// In template: {{ name }}  -> Alice
html := FromString("<b>Bold</b>")
// In template with escaping: {{ html }}  -> &lt;b&gt;Bold&lt;/b&gt;

func MakeIterable ¶

func MakeIterable(maker func() iter.Seq[Value]) Value

MakeIterable creates a lazy iterable value from a maker function. The maker is called each time iteration is needed, allowing multiple iterations.

Example:

val := MakeIterable(func() iter.Seq[Value] {
    return func(yield func(Value) bool) {
        for i := 0; i < 10; i++ {
            if !yield(FromInt(int64(i))) {
                return
            }
        }
    }
})

func MakeIterableFromSlice ¶

func MakeIterableFromSlice(maker func() []Value) Value

MakeIterableFromSlice creates an iterable that yields values from a slice. The slice function is called each time to get fresh values.

func MakeObjectMap ¶

func MakeObjectMap(enumerate func() iter.Seq[Value], getAttr func(key Value) Value) Value

MakeObjectMap creates a map-like value that projects onto callbacks.

Parameters:

• enumerate: returns an iterator over the map's keys
• getAttr: returns the value for a given key

Example (projecting a Go map as a Value):

attrs := map[string]string{"id": "link-1", "class": "links"}
val := MakeObjectMap(
    func() iter.Seq[Value] {
        return func(yield func(Value) bool) {
            for k := range attrs {
                if !yield(FromString(k)) {
                    return
                }
            }
        }
    },
    func(key Value) Value {
        if s, ok := key.AsString(); ok {
            if v, exists := attrs[s]; exists {
                return FromString(v)
            }
        }
        return Undefined()
    },
)

func MakeOneShotIterator ¶

func MakeOneShotIterator(seq iter.Seq[Value]) Value

MakeOneShotIterator creates an iterator that can only be consumed once.

Unlike MakeIterable, a one-shot iterator:

• Can only be fully iterated once
• Has no known length (loop.length is undefined)
• Renders as "<iterator>"
• After consumption, subsequent iterations yield nothing

If iteration is stopped early (e.g., with break), the remaining items are preserved for the next iteration attempt.

Example:

val := MakeOneShotIterator(func(yield func(Value) bool) {
    for i := 0; i < 10; i++ {
        if !yield(FromInt(int64(i))) {
            return
        }
    }
})

// First iteration: yields 0, 1, 2, ..., 9
// Second iteration: yields nothing

func MergeMaps ¶

func MergeMaps(sources ...Value) Value

MergeMaps merges multiple map-like values into a single lazy map object.

Later values override earlier ones when keys overlap. Non-map values are ignored for enumeration, but attribute lookups are forwarded to any objects that implement map-like access.

This mirrors the behavior of MiniJinja's context merging in Rust.

func None ¶

func None() Value

None returns the none/null value.

None represents an explicit null value, equivalent to null in JSON, nil in Go, or None in Python.

Example usage:

context := FromMap(map[string]Value{
    "name": FromString("Alice"),
    "age":  None(),  // explicitly null
})

func SilentUndefined ¶ added in v2.16.0

func SilentUndefined() Value

SilentUndefined returns an undefined value that does not trigger strict undefined errors when rendered or evaluated for truthiness.

This is used internally for expressions like "a if cond" where the false branch is omitted.

func True ¶

func True() Value

True returns the boolean true value.

This is a convenience function equivalent to FromBool(true).

func Undefined ¶

func Undefined() Value

Undefined returns the undefined value.

Undefined represents a missing or non-existent value. In templates, undefined values typically render as empty strings unless strict undefined behavior is enabled.

Example usage:

// Return undefined from a custom object
func (obj *MyObject) GetAttr(name string) Value {
    if name == "existing" {
        return FromString("value")
    }
    return Undefined()  // attribute doesn't exist
}