yamlprocessor

README

yamlprocessor

Integrates expr-lang/expr with goccy/go-yaml.

⚠ This library is in very early stage of development. Use at your own risk.

So far, all the work that has been done was experimental to check feasibility and there are a lot of flaws, poor error handling, performance issues and lack tests.

What does it do?

This library allows you to use expressions in your YAML files. The expressions are evaluated using the expr library.

name: "John Doe"
age: ${2024 - 2000}
history:
  ${file("history.yaml")}

Usage

package main

import "github.com/jamillosantos/yamlprocessor"

type Entry struct {
	Year int `yaml:"year"`
	Event string `yaml:"event"`
}

type Person struct {
	Name    string `yaml:"name"`
	Age     int   `yaml:"age"`
	History []Entry `yaml:"history"`
}

func main() {
	d := []byte(`
name: "John Doe"
age: ${2024 - 2000}
history:
  ${file("history.yaml")}
`)
	var p Person
	err := yamlprocessor.Unmarshal(d, &p)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", p)
}

// history.yaml
// - year: 2000
//   event: "Something happened"
// - year: 2001
//   event: "Something else happened"

Adding new functions

You can add new capabilities to the processor by adding new functions to the processor.

// ...
processor := yamlprocessor.NewProcessor()
processor.Env.Add("add", func(ctx *yamlprocessor.Context) any {
	return func(a, b int) int {
        return a + b
    }
})

var p Person
err := processor.Unmarshal([]byte(`name: "Name ${add(1, 2)}"`), &p)

Adding new variables

You can add new variables to the processor by adding new variables to the processor.

processor := yamlprocessor.NewProcessor()
processor.Env.Add("var1", yamlprocessor.Value(10))

Documentation

Index

• Variables
• func Add(name string, function ExprEntry) error
• func Env(ctx *Context) any
• func File(ctx *Context) any
• type Context
• type ExprEntry
  • func Value(val any) ExprEntry
• type ExprEnv
  • func (f *ExprEnv) Add(name string, function ExprEntry) error
• type Processor
  • func NewProcessor() Processor
  • func (p *Processor) ParseBytes(data []byte, mode parser.Mode) (*ast.File, error)
  • func (p *Processor) Tokenize(src string) (token.Tokens, error)
  • func (p *Processor) Unmarshal(data []byte, v interface{}) error
• type Scanner
  • func (s *Scanner) Init(src string)
  • func (s *Scanner) Scan() (token.Tokens, error)

Variables

var DefaultProcessor = NewProcessor()

var ErrEntryAlreadyRegistered = errors.New("function already registered")

var Unmarshal = DefaultProcessor.Unmarshal

Functions

func Add

func Add(name string, function ExprEntry) error

func Env

func Env(ctx *Context) any

Env will return the value of the environment variable with the given name.

func File

func File(ctx *Context) any

File will load and paste the content of the YAML file in the place where it is called. The file loaded will be processed by the same processor that is calling this function. Also, all the expressions will be evaluated.

Types

type Context

type Context struct {
	Processor *Processor
}

type ExprEntry

type ExprEntry func(ctx *Context) any

ExprEntry is a type alias for a function. The function receives a Context and returns should return a func() that receives and return any number of params.

func Value

func Value(val any) ExprEntry

Value is a helper function that helps to add variables in the ExprEnv map for when expressions are evaluated.

type ExprEnv

type ExprEnv map[string]ExprEntry

ExprEnv is a map of functions that can be registered to the processor.

func (*ExprEnv) Add

func (f *ExprEnv) Add(name string, function ExprEntry) error

Add adds a function to the ExprEnv map making it available to be acessible for the Processor. If the map is not initialised, it will be initialised.

type Processor

type Processor struct {
	Env ExprEnv
}

Processor is a struct that holds lexer and parser functions.

func NewProcessor

func NewProcessor() Processor

NewProcessor returns a new Processor.

func (*Processor) ParseBytes

func (p *Processor) ParseBytes(data []byte, mode parser.Mode) (*ast.File, error)

func (*Processor) Tokenize

func (p *Processor) Tokenize(src string) (token.Tokens, error)

Tokenize split to token instances from string

func (*Processor) Unmarshal

func (p *Processor) Unmarshal(data []byte, v interface{}) error

Unmarshal will unmarshal the given data into the given interface. It will use the ParseBytes method to parse the data with the expressions and then unmarshal the parsed data into the given interface.

This methods resource wasteful as it will parse the data twice, once to resolve the expressions (In the future releaseWe could try to parse the data directly from the AST built from the ParseBytes).

type Scanner

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

Scanner is a scanner for YAML. It is a wrapper around the scanner.Scanner of the goccy/go-yaml library adding the ability to scan expressions inside the YAML string values.

This Scanner uses the Processor LexerFunctions as the expr.Run env.

func (*Scanner) Init

func (s *Scanner) Init(src string)

func (*Scanner) Scan

func (s *Scanner) Scan() (token.Tokens, error)

Scan scans the YAML string and returns the tokens found in the string, using the goccy/go-yaml Scanner. If an expression (${...}) is found in the string, it will be compiled and executed (using the expr-lang/expr library) using the Processor LexerFunctions.