sutl

README

sutl-go

Dependency-free Go implementation of sUTL 1.0, the sUTL Universal Transform Language (“subtle”).

This module implements the frozen sUTL 1.0 contract. It passes the 88-case conformance corpus and the 44 archived Studio fixtures.

Install

Go modules are published from this public repository. A version tag is enough for go get and pkg.go.dev.

go get github.com/emlynoregan/sutl-go@v1.1.0

The command-line tool:

go install github.com/emlynoregan/sutl-go/cmd/sutl@v1.1.0

Requires Go 1.22 or later.

Evaluate

package main

import (
	"context"
	"fmt"

	"github.com/emlynoregan/sutl-go"
)

func main() {
	source := map[string]any{"name": "Ada"}
	fmt.Println(sutl.Evaluate(source, "^$.name", nil)) // Ada

	// Compile once when the same transform runs against many sources.
	program := sutl.Compile("^$.name", nil)
	fmt.Println(program.Run(source)) // Ada

	limited, err := sutl.CompileLimited("^$.name", nil, sutl.Limits{
		MaxSteps: 100_000,
		MaxDepth: 256,
	})
	if err != nil {
		panic(err)
	}
	name, err := limited.RunContext(context.Background(), source)
	if err != nil {
		panic(err)
	}
	fmt.Println(name) // Ada
}

sutl.DecodeJSON reads a MLSNBN value and keeps JSON object key order. Path wildcards (* and **) walk that order, matching the JavaScript and Python implementations and the Studio fixtures. keys and values still return keys in sorted order.

Maps built as map[string]any do not remember insertion order. Decode JSON when wildcard order matters.

Timings for Evaluate and Compile are in PERFORMANCE.md.

CLI

Arguments are JSON literals. Prefix a path with @, or use - for stdin.

sutl "{\"name\":\"Ada\"}" "\"^$.name\""

--library is a JSON object. --pretty indents the result. --version prints the package version.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package sutl is the dependency-free Go implementation of sUTL 1.0, the sUTL Universal Transform Language (“subtle”).

Index

• Constants
• func AsMap(value Value) (map[string]Value, bool)
• func CompileLib(declarations []Value, distributions [][]Value, seed Library, test bool) map[string]Value
• func Truthy(value Value) bool
• type Library
• type LimitError
  • func (e *LimitError) Error() string
  • func (e *LimitError) Unwrap() error
• type Limits
• type Program
  • func Compile(transform Value, library Library) *Program
  • func CompileLimited(transform Value, library Library, limits Limits) (*Program, error)
  • func (p *Program) Run(source Value) Value
  • func (p *Program) RunContext(ctx context.Context, source Value) (Value, error)
• type Runner
  • func NewRunner() *Runner
  • func (r *Runner) Evaluate(source, transform Value, library Library) Value
• type Value
  • func DecodeJSON(data []byte) (Value, error)
  • func Evaluate(source, transform Value, library Library) Value
  • func EvaluateLimited(ctx context.Context, source, transform Value, library Library, limits Limits) (Value, error)

Constants

const ContractVersion = "1.0.0"

ContractVersion is the sUTL language contract implemented by this module.

const Version = "1.1.0"

Version is this module's release. The language contract is still sUTL 1.0.0.

Functions

func AsMap

func AsMap(value Value) (map[string]Value, bool)

AsMap reports whether value is a MLSNBN map and returns its entries. Objects decoded with DecodeJSON are maps.

func CompileLib

func CompileLib(declarations []Value, distributions [][]Value, seed Library, test bool) map[string]Value

CompileLib resolves declaration requirements into a transform library. It returns either {"lib": library} or {"fail": failures}.

func Truthy

func Truthy(value Value) bool

Truthy reports sUTL truthiness.

Types

type Library

type Library map[string]Value

Library is a named collection of transforms.

type LimitError

type LimitError struct {
	Reason string
	Err    error
}

LimitError is returned when evaluation exceeds a limit or the host cancels. Reason is "steps", "depth", or "cancelled". A cancelled error unwraps to the context error.

func (*LimitError) Error

func (e *LimitError) Error() string

func (*LimitError) Unwrap

func (e *LimitError) Unwrap() error

type Limits

type Limits struct {
	MaxSteps int
	MaxDepth int
}

Limits bound one evaluation. Zero means that bound is unset.

type Program

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

Program is a transform compiled to a Go function. Compile once, then Run the same transform against many sources.

func Compile

func Compile(transform Value, library Library) *Program

Compile prepares a transform so it can be applied repeatedly. Dynamic eval (! ) stays on the walker until that transform has been seen, then the compiled form is reused. A library is captured by reference.

func CompileLimited

func CompileLimited(transform Value, library Library, limits Limits) (*Program, error)

CompileLimited compiles transform and applies limits on every run.

func (*Program) Run

func (p *Program) Run(source Value) Value

Run applies the compiled transform to source. A program created with CompileLimited panics with *LimitError if a limit is exceeded. Use RunContext to receive that error as a value.

func (*Program) RunContext

func (p *Program) RunContext(ctx context.Context, source Value) (Value, error)

RunContext runs the compiled transform. Limits set by CompileLimited are enforced here, and ctx is checked at every step. A context that cannot be cancelled and a program with no limits use the compiled function directly.

type Runner

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

Runner evaluates sUTL transforms with an optional transform library.

func NewRunner

func NewRunner() *Runner

NewRunner constructs a reusable evaluator.

func (*Runner) Evaluate

func (r *Runner) Evaluate(source, transform Value, library Library) Value

Evaluate runs a transform against a source value and optional library.

type Value

type Value = any

Value is a MLSNBN value: a map, list, string, number, boolean, or null.

func DecodeJSON

func DecodeJSON(data []byte) (Value, error)

DecodeJSON reads a MLSNBN value, preserving object key order.

func Evaluate

func Evaluate(source, transform Value, library Library) Value

Evaluate runs a transform against a source value and optional library. The builtin table is reused across calls. Compile a transform with Compile when the same transform runs against many sources.

func EvaluateLimited

func EvaluateLimited(ctx context.Context, source, transform Value, library Library, limits Limits) (Value, error)

EvaluateLimited runs a transform with limits and cancellation.