spiffing

Documentation

Overview

Example

package main

import (
	"fmt"
	"math"
	"os"

	"github.com/mandelsoft/spiff/dynaml"
)

func func_pow(arguments []interface{}, binding dynaml.Binding) (interface{}, dynaml.EvaluationInfo, bool) {
	info := dynaml.DefaultInfo()

	if len(arguments) != 2 {
		return info.Error("pow takes 2 arguments")
	}

	args, wasInt, err := dynaml.NumberOperandsN(dynaml.TYPE_FLOAT, arguments...)

	if err != nil {
		return info.Error("%s", err)
	}
	r := math.Pow(args[0].(float64), args[1].(float64))
	if wasInt && float64(int64(r)) == r {
		return int64(r), info, true
	}
	return r, info, true
}

var state = `
state: {}
`
var stub = `
unused: (( input ))
ages:
  alice: (( pow(2,5) ))
  bob: (( alice + 1 ))
`

var template = `
state:
  <<<: (( &state ))
  random: (( rand("[:alnum:]", 10) )) 
ages: (( &temporary ))

example:
  name: (( input ))  # direct reference to additional values 
  sum: (( sum[ages|0|s,k,v|->s + v] ))
  int: (( pow(2,4) ))
  pow: (( pow(1.1e-1,2) ))
`

func Error(err error) {
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
		os.Exit(1)
	}
}

func main() {
	values := map[string]interface{}{}
	values["input"] = "this is an input"

	functions := NewFunctions()
	functions.RegisterFunction("pow", func_pow)

	spiff, err := New().WithFunctions(functions).WithValues(values)
	Error(err)
	pstate, err := spiff.Unmarshal("state", []byte(state))
	Error(err)
	pstub, err := spiff.Unmarshal("stub", []byte(stub))
	Error(err)
	ptempl, err := spiff.Unmarshal("template", []byte(template))
	Error(err)
	result, err := spiff.Cascade(ptempl, []Node{pstub}, pstate)
	Error(err)
	b, err := spiff.Marshal(result)
	Error(err)
	newstate, err := spiff.Marshal(spiff.DetermineState(result))
	Error(err)
	fmt.Printf("==== new state ===\n")
	fmt.Printf("%s\n", string(newstate))
	fmt.Printf("==== result ===\n")
	fmt.Printf("%s\n", string(b))
}

Index

• Constants
• func Cascade(s Spiff, template Source, stubs []Source, optstate ...Source) ([]byte, []byte, error)
• func EvaluateDynamlExpression(s Spiff, expr string) ([]byte, error)
• func Normalize(n Node) (interface{}, error)
• func Process(s Spiff, template Source) ([]byte, error)
• func ProcessFile(s Spiff, path string) ([]byte, error)
• type Functions
  • func NewFunctions() Functions
• type Node
  • func ToNode(name string, data interface{}) (Node, error)
• type Options
• type Source
  • func NewSourceData(name string, data []byte) Source
  • func NewSourceFile(path string, optfs ...vfs.FileSystem) Source
• type Spiff
  • func New() Spiff

Examples

• Package
• EvaluateDynamlExpression
• EvaluateDynamlExpression (Complex_data)

Constants

const MODE_DEFAULT = MODE_OS_ACCESS | MODE_FILE_ACCESS

MODE_DEFAULT (default) enables all os related spiff functions

const MODE_FILE_ACCESS = flow.MODE_FILE_ACCESS

MODE_FILE_ACCESS allows file access to virtual filesystem

const MODE_OS_ACCESS = flow.MODE_OS_ACCESS

MODE_OS_ACCESS allows os command execution (pipe, exec)

const MODE_PRIVATE = 0

MODE_PRIVATE does not allow access to any external resources

Functions

func Cascade

func Cascade(s Spiff, template Source, stubs []Source, optstate ...Source) ([]byte, []byte, error)

Cascade processes a template source with a list of stub sources and optional state and devivers the cascading results and the new state as yaml data

func EvaluateDynamlExpression

func EvaluateDynamlExpression(s Spiff, expr string) ([]byte, error)

EvaluateDynamlExpression just processes a plain dynaml expression with the values set in the execution context.

Example

ctx, _ := New().WithValues(map[string]interface{}{
	"values": map[string]interface{}{
		"alice": 25,
		"bob":   26,
	},
})
result, _ := EvaluateDynamlExpression(ctx, "values.alice + values.bob")
fmt.Printf("%s", result)

Output:

51

Example (Complex_data)

ctx, _ := New().WithValues(map[string]interface{}{
	"values": map[string]interface{}{
		"alice": 25,
		"bob":   26,
	},
})
result, _ := EvaluateDynamlExpression(ctx, "[values.alice, values.bob]")
fmt.Printf("%s", result)

Output:

- 25
- 26

func Normalize

func Normalize(n Node) (interface{}, error)

func Process

func Process(s Spiff, template Source) ([]byte, error)

Process just processes a template with the values set in the execution context. It directly takes and delivers byte array containing yaml data.

func ProcessFile

func ProcessFile(s Spiff, path string) ([]byte, error)

ProcessFile just processes a template give by a file with the values set in the execution context. The path name of the file is interpreted in the context of the filesystem found in the execution context, which is defaulted by the OS filesystem.

Types

type Functions

type Functions = dynaml.Registry

Functions provides access to a set of spiff functions used to extend the standrd function set

func NewFunctions

func NewFunctions() Functions

NewFunctions provides a new registry for additional spiff functions

type Node

type Node = yaml.Node

Node is a document node of the processing representation of a document

func ToNode

func ToNode(name string, data interface{}) (Node, error)

type Options

type Options = flow.Options

Options described the processing options

type Source

type Source interface {
	// Name resturns the name of the source
	// For file based sources this should be the path name of the file.
	Name() string
	// Data returns the yaml representation of the source document
	Data() ([]byte, error)
}

Source is used to get access to a template or stub source data and name

func NewSourceData

func NewSourceData(name string, data []byte) Source

NewSourceData creates a source based on yaml data

func NewSourceFile

func NewSourceFile(path string, optfs ...vfs.FileSystem) Source

NewSourceFile returns a source based on a file in a virtual filesystem If no filesystem is given the os filesystem is used by default

type Spiff

type Spiff interface {
	// WithEncryptionKey creates a new context with
	// dedicated encryption key used for the spiff encryption feature
	WithEncryptionKey(key string) Spiff
	// WithMode creates a new context with the given processing mode.
	// (see MODE constants)
	WithMode(mode int) Spiff
	// WithFileSystem creates a new context with the given
	// virtual filesystem used for filesystem functions during
	// prcessing. Setting a filesystem disables the command
	// execution functions.
	WithFileSystem(fs vfs.FileSystem) Spiff
	// WithFunctions creates a new context with the given
	// additional function definitions
	WithFunctions(functions Functions) Spiff
	// WithValues creates a new context with the given
	// additional structured values usable by path expressions
	// during processing.
	// It is highly recommended to decide for a common root
	// value (like `values`) to minimize the blocked root
	// elements in the processed documents.
	WithValues(values map[string]interface{}) (Spiff, error)

	// FileSystem return the virtual filesystem set for the execution context.
	FileSystem() vfs.FileSystem
	// FileSource create a new file source based on the configured file system.
	FileSource(path string) Source

	// Unmarshal parses a single document yaml representation and
	// returns the internal representation
	Unmarshal(name string, source []byte) (Node, error)
	// Unmarshal parses a single source and
	// returns the internal representation
	UnmarshalSource(source Source) (Node, error)
	// UnmarshalMulti parses a multi document yaml representation and
	// returns the list of documents in the internal representation
	UnmarshalMulti(name string, source []byte) ([]Node, error)
	// UnmarshalMultiSource parses a multi document source and
	// returns the list of documents in the internal representation
	UnmarshalMultiSource(source Source) ([]Node, error)
	// Marshal transform the internal node representation into a
	// yaml representation
	Marshal(node Node) ([]byte, error)
	// DetermineState extracts the intended new state representation from
	// a processing result.
	DetermineState(node Node) Node
	// Normalize transform the node representation to a regular go value representation
	// consisting of map[string]interface{}`, `[]interface{}`, `string `boolean`,
	// `int64`, `float64` and []byte objects
	Normalize(node Node) (interface{}, error)

	// Cascade processes a template with a list of given subs and state
	// documents
	Cascade(template Node, stubs []Node, states ...Node) (Node, error)
	// PrepareStubs processes a list a stubs and returns a prepared
	// represenation usable to process a template
	PrepareStubs(stubs ...Node) ([]Node, error)
	// ApplyStubs uses already prepared subs to process a template.
	ApplyStubs(template Node, preparedstubs []Node) (Node, error)
}

Spiff is a configuration end execution context for executing spiff operations

func New

func New() Spiff

New create a new default spiff context.