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.0.0

The command-line tool:

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

Requires Go 1.22 or later.

Evaluate

package main

import (
	"fmt"

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

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

sutl.DecodeJSON reads a MAS 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.

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 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

Constants

const Version = "1.0.0"

Version is the implementation version and matches the sUTL 1.0.0 contract.

Functions

func AsMap

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

AsMap reports whether value is a MAS 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 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 MAS value: a map, list, string, number, boolean, or null.

func DecodeJSON

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

DecodeJSON reads a MAS 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.