replvar

replvar

A Go library for variable replacement and expression evaluation in strings. It parses template strings containing {{variable}} expressions and resolves them against a context, supporting arithmetic operations, logical operators, comparisons, and nested field access.

Installation

go get github.com/KarpelesLab/replvar

Features

• Variable substitution with {{name}} syntax
• Field/member access with dot notation: {{obj.field}}
• Arithmetic operators: +, -, *, /, % (modulo)
• Bitwise operators: |, &, ^, ~ (NOT), <<, >> (shifts)
• Logical operators: ||, &&, !
• Comparison operators: ==, !=, <, <=, >, >=
• Proper operator precedence (e.g., 2 + 3 * 4 = 14)
• String literals with single quotes, double quotes, or backticks
• Escape sequences in double-quoted strings (\n, \t, \r, \v, \\)
• JSON mode for automatic JSON encoding of embedded values
• Static value optimization (compile once, resolve many times)

Usage

Basic Variable Replacement

package main

import (
    "context"
    "fmt"

    "github.com/KarpelesLab/replvar"
)

func main() {
    // Create a context with values
    ctx := context.Background()
    ctx = context.WithValue(ctx, "name", "World")

    // Replace variables in a string
    result, err := replvar.Replace(ctx, "Hello {{name}}!", "text")
    if err != nil {
        panic(err)
    }
    fmt.Println(result) // Output: Hello World!
}

Field Access

ctx := context.Background()
ctx = context.WithValue(ctx, "user", map[string]any{
    "name": "Alice",
    "age":  30,
})

result, _ := replvar.Replace(ctx, "Name: {{user.name}}, Age: {{user.age}}", "text")
fmt.Println(result) // Output: Name: Alice, Age: 30

Arithmetic Operations

ctx := context.Background()
ctx = context.WithValue(ctx, "price", 100)
ctx = context.WithValue(ctx, "quantity", 5)

result, _ := replvar.Replace(ctx, "Total: {{price * quantity}}", "text")
fmt.Println(result) // Output: Total: 500

Comparisons and Logic

ctx := context.Background()
ctx = context.WithValue(ctx, "score", 85)

result, _ := replvar.Replace(ctx, "Pass: {{score == 85}}", "text")
fmt.Println(result) // Output: Pass: 1

result, _ = replvar.Replace(ctx, "High: {{score != 0}}", "text")
fmt.Println(result) // Output: High: 0

Parse Once, Resolve Many

For better performance when resolving the same template multiple times:

// Parse the template once
template, err := replvar.ParseString("Hello {{name}}!", "text")
if err != nil {
    panic(err)
}

// Check if the template contains only static values
if template.IsStatic() {
    // No variables, result is constant
}

// Resolve with different contexts
ctx1 := context.WithValue(context.Background(), "name", "Alice")
ctx2 := context.WithValue(context.Background(), "name", "Bob")

result1, _ := template.Resolve(ctx1) // "Hello Alice!"
result2, _ := template.Resolve(ctx2) // "Hello Bob!"

JSON Mode

When using "json" mode, embedded variables are automatically JSON-encoded:

ctx := context.Background()
ctx = context.WithValue(ctx, "data", map[string]any{"key": "value"})

result, _ := replvar.Replace(ctx, `{"nested": {{data}}}`, "json")
// Output: {"nested": {"key":"value"}}

String Literals

Variables can contain string literals with different quote types:

// Single quotes - no escape processing
result, _ := replvar.Replace(ctx, "Value: {{'hello world'}}", "text")

// Double quotes - supports escape sequences
result, _ := replvar.Replace(ctx, "Value: {{\"hello\\tworld\"}}", "text")

// Backticks - raw strings, no escape processing
result, _ := replvar.Replace(ctx, "Value: {{`hello\\nworld`}}", "text")

API Reference

Functions

Replace(ctx context.Context, s string, mode string) (string, error)

Parses and resolves a template string in one step. This is the simplest way to perform variable replacement.

• ctx: Context containing variable values (accessed via ctx.Value(key))
• s: Template string with {{variable}} expressions
• mode: Either "text" or "json" (for automatic JSON encoding)

ParseString(s string, mode string) (Var, error)

Parses a template string into a Var that can be resolved multiple times.

ParseVariable(s string) (Var, error)

Parses a variable expression (the content inside {{}}).

Var Interface

type Var interface {
    Resolve(context.Context) (any, error)
    IsStatic() bool
}

• Resolve: Evaluates the expression against the given context
• IsStatic: Returns true if the value is constant (no variables)

Expression Syntax

Operator Precedence

Operators are evaluated according to standard precedence rules (higher precedence binds tighter):

For example, 2 + 3 * 4 evaluates to 14 (not 20), and 1 || 0 && 0 evaluates to 1 (not 0).

License

See LICENSE file for details.