exprml

README

exprml-go

exprml-go is a Go library implementing an ExprML interpreter. The ExprML is a programming language that can evaluate expressions represented in JSON (and JSON-compatible YAML).

The ExprML language specification is available at https://github.com/exprml/exprml-language .

Installation

go get github.com/exprml/exprml-go

Examples

Evaluate an expression

https://pkg.go.dev/github.com/exprml/exprml-go#example-Evaluator

Call Go functions from ExprML

https://pkg.go.dev/github.com/exprml/exprml-go#example-Evaluator-Extension

Hook Go functions before and after each evaluation of nested expressions

https://pkg.go.dev/github.com/exprml/exprml-go#example-Evaluator-BeforeEvaluate

https://pkg.go.dev/github.com/exprml/exprml-go#example-Evaluator-AfterEvaluate

API documentation

https://pkg.go.dev/github.com/exprml/exprml-go

Documentation

Index

• func Append(path *pb.Expr_Path, pos ...any) *pb.Expr_Path
• func ArrValue(arr []*pb.Value) *pb.Value
• func BoolValue(b bool) *pb.Value
• func Find(defStack *pb.DefStack, ident string) *pb.DefStack
• func Format(path *pb.Expr_Path) string
• func Keys(value *pb.Value) []string
• func NewDefinition(path *pb.Expr_Path, ident string, value *pb.Value) *pb.Eval_Definition
• func NumValue(num float64) *pb.Value
• func ObjValue(obj map[string]*pb.Value) *pb.Value
• func Register(defStack *pb.DefStack, def *pb.Eval_Definition) *pb.DefStack
• func StrValue(str string) *pb.Value
• type Config
• type Decoder
  • func NewDecoder() Decoder
• type Encoder
  • func NewEncoder() Encoder
• type Evaluator
  • func NewEvaluator(config *Config) Evaluator
• type Parser
  • func NewParser() Parser

Examples

• Evaluator
• Evaluator (AfterEvaluate)
• Evaluator (BeforeEvaluate)
• Evaluator (Extension)

Functions

func Append

func Append(path *pb.Expr_Path, pos ...any) *pb.Expr_Path

func ArrValue

func ArrValue(arr []*pb.Value) *pb.Value

func BoolValue

func BoolValue(b bool) *pb.Value

func Find

func Find(defStack *pb.DefStack, ident string) *pb.DefStack

func Format

func Format(path *pb.Expr_Path) string

func Keys

func Keys(value *pb.Value) []string

func NewDefinition

func NewDefinition(path *pb.Expr_Path, ident string, value *pb.Value) *pb.Eval_Definition

func NumValue

func NumValue(num float64) *pb.Value

func ObjValue

func ObjValue(obj map[string]*pb.Value) *pb.Value

func Register

func Register(defStack *pb.DefStack, def *pb.Eval_Definition) *pb.DefStack

func StrValue

func StrValue(str string) *pb.Value

Types

type Config

type Config struct {
	Extension      map[string]func(path *pb.Expr_Path, args map[string]*pb.Value) *pb.EvaluateOutput
	BeforeEvaluate func(input *pb.EvaluateInput) error
	AfterEvaluate  func(input *pb.EvaluateInput, output *pb.EvaluateOutput) error
}

type Decoder

type Decoder interface {
	Decode(input *pb.DecodeInput) *pb.DecodeOutput
}

func NewDecoder

func NewDecoder() Decoder

type Encoder

type Encoder interface {
	Encode(input *pb.EncodeInput) *pb.EncodeOutput
}

func NewEncoder

func NewEncoder() Encoder

type Evaluator

type Evaluator interface {
	Evaluate(input *pb.EvaluateInput) *pb.EvaluateOutput
}

Example

// Evaluate an expression

// ExprML source code in JSON-compatible YAML format.
source := "cat: ['`Hello`', '`, `', '`ExprML`', '`!`']"
// Decode source as a JSON value
decoded := exprml.NewDecoder().Decode(&pb.DecodeInput{Text: source})
// Parse an expression
parsed := exprml.NewParser().Parse(&pb.ParseInput{Value: decoded.Value})
// Evaluate parsed expression
evaluated := exprml.NewEvaluator(nil).Evaluate(&pb.EvaluateInput{Expr: parsed.Expr})
// Encode evaluated result
encoded := exprml.NewEncoder().Encode(&pb.EncodeInput{Value: evaluated.Value})

fmt.Println(encoded.Text)

Output:

"Hello, ExprML!"

Example (AfterEvaluate)

// Hook Go functions after each evaluation of nested expressions

source := "cat: ['`Hello`', '`, `', '`ExprML`', '`!`']"
decoded := exprml.NewDecoder().Decode(&pb.DecodeInput{Text: source})
parsed := exprml.NewParser().Parse(&pb.ParseInput{Value: decoded.Value})
evaluator := exprml.NewEvaluator(&exprml.Config{
	/* Hook a function after the evaluation of each expression. */
	AfterEvaluate: func(input *pb.EvaluateInput, output *pb.EvaluateOutput) error {
		fmt.Printf("After evaluation: %q: %v\n", exprml.Format(input.Expr.Path), output.Value.String())
		return nil
	},
})
_ = evaluator.Evaluate(&pb.EvaluateInput{Expr: parsed.Expr})

Output:

After evaluation: "/cat/0": type:STR  str:"Hello"
After evaluation: "/cat/1": type:STR  str:", "
After evaluation: "/cat/2": type:STR  str:"ExprML"
After evaluation: "/cat/3": type:STR  str:"!"
After evaluation: "/": type:STR  str:"Hello, ExprML!"

Example (BeforeEvaluate)

// Hook Go functions before each evaluation of nested expressions

source := "cat: ['`Hello`', '`, `', '`ExprML`', '`!`']"
decoded := exprml.NewDecoder().Decode(&pb.DecodeInput{Text: source})
parsed := exprml.NewParser().Parse(&pb.ParseInput{Value: decoded.Value})
evaluator := exprml.NewEvaluator(&exprml.Config{
	/* Hook a function before the evaluation of each expression. */
	BeforeEvaluate: func(input *pb.EvaluateInput) error {
		fmt.Printf("Before evaluation: %q\n", exprml.Format(input.Expr.Path))
		return nil
	},
})
_ = evaluator.Evaluate(&pb.EvaluateInput{Expr: parsed.Expr})

Output:

Before evaluation: "/"
Before evaluation: "/cat/0"
Before evaluation: "/cat/1"
Before evaluation: "/cat/2"
Before evaluation: "/cat/3"

Example (Extension)

// Call Go functions from ExprML

source := "$hello: { $name: '`ExprML Extension`' }"
decoded := exprml.NewDecoder().Decode(&pb.DecodeInput{Text: source})
parsed := exprml.NewParser().Parse(&pb.ParseInput{Value: decoded.Value})
evaluator := exprml.NewEvaluator(&exprml.Config{
	Extension: map[string]func(path *pb.Expr_Path, args map[string]*pb.Value) *pb.EvaluateOutput{
		// Define an extension function named $hello,
		// which takes an argument $name and returns a greeting string.
		"$hello": func(path *pb.Expr_Path, args map[string]*pb.Value) *pb.EvaluateOutput {
			name, ok := args["$name"]
			if !ok || name.Type != pb.Value_STR {
				return &pb.EvaluateOutput{
					Status:       pb.EvaluateOutput_UNKNOWN_ERROR,
					ErrorPath:    path,
					ErrorMessage: "invalid argument: $name",
				}
			}
			return &pb.EvaluateOutput{
				Value: &pb.Value{Type: pb.Value_STR, Str: "Hello, " + name.Str + "!"},
			}
		},
	},
})
evaluated := evaluator.Evaluate(&pb.EvaluateInput{Expr: parsed.Expr})
encoded := exprml.NewEncoder().Encode(&pb.EncodeInput{Value: evaluated.Value})
fmt.Println(encoded.Text)

Output:

"Hello, ExprML Extension!"

func NewEvaluator

func NewEvaluator(config *Config) Evaluator

type Parser

type Parser interface {
	Parse(input *pb.ParseInput) *pb.ParseOutput
}

func NewParser

func NewParser() Parser