add support for MultiValue

Author: seborama

.github/FUNDING.yml

@@ -0,0 +1,7 @@
+# These are supported funding model platforms
+
+ko_fi: # Replace with a single Ko-fi username
+liberapay: # Replace with a single Liberapay username
+polar: # Replace with a single Polar username
+buy_me_a_coffee: seborama
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

README.md

@@ -1,12 +1,12 @@
 # Go Eval
 
 <p align="center">
-  <a href="https://pkg.go.dev/github.com/seborama/gal/v7">
+  <a href="https://pkg.go.dev/github.com/seborama/gal/v8">
     <img src="https://img.shields.io/badge/godoc-reference-blue.svg" alt="gal">
   </a>
 
-  <a href="https://goreportcard.com/report/github.com/seborama/gal/v7">
-    <img src="https://goreportcard.com/badge/github.com/seborama/gal/v7" alt="gal">
+  <a href="https://goreportcard.com/report/github.com/seborama/gal/v8">
+    <img src="https://goreportcard.com/badge/github.com/seborama/gal/v8" alt="gal">
   </a>
 </p>
 
@@ -105,15 +105,17 @@ Numbers implement arbitrary precision fixed-point decimal arithmetic with [shops
 * Types: String, Number, Bool
 * Associativity with parentheses
 * Functions:
-    * Pre-defined: pi, cos, floor, sin, sqrt, trunc, and more (see `function.go`: `Eval()`)
+    * Built-in: pi, cos, floor, sin, sqrt, trunc, and more (see `function.go`: `Eval()`)
     * User-defined, injected via `WithFunctions()`
 * Variables, defined as `:variable_name:` and injected via `WithVariables()`
 
 ## Functions
 
 Function names are case-insensitive.
 
-A function can optionally accept one or more space-separated arguments, but it must return a single Value.
+A function can optionally accept one or more **space-separated** arguments, but it must return a single `Value`.
+
+It should be noted that a `MultiValue` type is available that can hold multiple `Value`. A function can use `MultiValue` as its return type to effectively return multiple `Value`'s. Of course, as `MultiValue` is a `Value` type, functions can also accept it as part of their argument(s). Refer to the tests (`TestMultiValueFunctions`) for such examples.
 
 User function definitions are passed as a `map[string]FunctionalValue` using `WithFunctions` when calling `Eval` from `Tree`.
 

function.go

@@ -11,9 +11,6 @@ import (
 type FunctionalValue func(...Value) Value
 
 func (fv FunctionalValue) String() string {
-	// TODO: This is only to support the tests (see Function.Equal)).
-	//       This is not elegant but so far the only solution I have to compare
-	//       Functions in the tests.
 	return fmt.Sprintf("FunctionalValue @%p", fv)
 }
 
@@ -35,10 +32,8 @@ func (Function) kind() entryKind {
 	return functionEntryKind
 }
 
+// Equal satisfies the external Equaler interface such as in testify assertions and the cmp package
 func (f Function) Equal(other Function) bool {
-	// TODO: This is only to support the tests.
-	//       This is not elegant but so far the only solution I have to compare
-	//       Functions in the tests.
 	return f.Name == other.Name &&
 		f.BodyFn.String() == other.BodyFn.String() &&
 		cmp.Equal(f.Args, other.Args)
@@ -58,7 +53,7 @@ func (f Function) Eval(opts ...treeOption) Value {
 	return f.BodyFn(args...)
 }
 
-var preDefinedFunctions = map[string]FunctionalValue{
+var builtInFunctions = map[string]FunctionalValue{
 	"pi":        Pi,
 	"factorial": Factorial,
 	"cos":       Cos,
@@ -69,14 +64,14 @@ var preDefinedFunctions = map[string]FunctionalValue{
 	"trunc":     Trunc,
 }
 
-// PreDefinedFunction returns a pre-defined function body if known.
-// It returns `nil` when no pre-defined function exists by the specified name.
+// BuiltInFunction returns a built-in function body if known.
+// It returns `nil` when no built-in function exists by the specified name.
 // This signals the Evaluator to attempt to find a user defined function.
-func PreDefinedFunction(name string) FunctionalValue {
+func BuiltInFunction(name string) FunctionalValue {
 	// note: for now function names are arbitrarily case-insensitive
 	lowerName := strings.ToLower(name)
 
-	bodyFn, ok := preDefinedFunctions[lowerName]
+	bodyFn, ok := builtInFunctions[lowerName]
 	if ok {
 		return bodyFn
 	}

function_test.go

@@ -4,7 +4,7 @@ import (
 	"math"
 	"testing"
 
-	"github.com/seborama/gal/v7"
+	"github.com/seborama/gal/v8"
 	"github.com/stretchr/testify/assert"
 )
 

gal_test.go

@@ -1,10 +1,11 @@
 package gal_test
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
-	"github.com/seborama/gal/v7"
+	"github.com/seborama/gal/v8"
 	"github.com/stretchr/testify/assert"
 )
 
@@ -65,6 +66,56 @@ func TestTreeBuilder_FromExpr_UnknownVariable(t *testing.T) {
 	}
 }
 
+func TestEval_Boolean(t *testing.T) {
+	expr := `2 > 1`
+	val := gal.Parse(expr).Eval()
+	assert.Equal(t, gal.True.String(), val.String())
+
+	expr = `2 > 2`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.False.String(), val.String())
+
+	expr = `2 >= 2`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.True.String(), val.String())
+
+	expr = `2 < 1`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.False.String(), val.String())
+
+	expr = `2 < 2`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.False.String(), val.String())
+
+	expr = `2 <= 2`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.True.String(), val.String())
+
+	expr = `2 != 2`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.False.String(), val.String())
+
+	expr = `1 != 2`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.True.String(), val.String())
+
+	expr = `3 != 2`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.True.String(), val.String())
+
+	expr = `2 == 2`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.True.String(), val.String())
+
+	expr = `1 == 2`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.False.String(), val.String())
+
+	expr = `3 == 2`
+	val = gal.Parse(expr).Eval()
+	assert.Equal(t, gal.False.String(), val.String())
+}
+
 func TestWithVariablesAndFunctions(t *testing.T) {
 	expr := `double(:val1:) + triple(:val2:)`
 	parsedExpr := gal.Parse(expr)
@@ -143,52 +194,140 @@ func TestWithVariablesAndFunctions(t *testing.T) {
 	}
 }
 
-func TestEval_Boolean(t *testing.T) {
-	expr := `2 > 1`
-	val := gal.Parse(expr).Eval()
-	assert.Equal(t, gal.True.String(), val.String())
+func TestNestedFunctions(t *testing.T) {
+	expr := `double(triple(7))`
+	parsedExpr := gal.Parse(expr)
 
-	expr = `2 > 2`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.False.String(), val.String())
+	// step 1: define funcs and vars and Eval the expression
+	funcs := gal.Functions{
+		"double": func(args ...gal.Value) gal.Value {
+			if len(args) != 1 {
+				return gal.NewUndefinedWithReasonf("double() requires a single argument, got %d", len(args))
+			}
 
-	expr = `2 >= 2`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.True.String(), val.String())
+			value, ok := args[0].(gal.Numberer)
+			if !ok {
+				return gal.NewUndefinedWithReasonf("double(): syntax error - argument must be a number-like value, got '%v'", args[0])
+			}
 
-	expr = `2 < 1`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.False.String(), val.String())
+			return value.Number().Multiply(gal.NewNumber(2))
+		},
+		"triple": func(args ...gal.Value) gal.Value {
+			if len(args) != 1 {
+				return gal.NewUndefinedWithReasonf("triple() requires a single argument, got %d", len(args))
+			}
 
-	expr = `2 < 2`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.False.String(), val.String())
+			value, ok := args[0].(gal.Numberer)
+			if !ok {
+				return gal.NewUndefinedWithReasonf("triple(): syntax error - argument must be a number-like value, got '%v'", args[0])
+			}
 
-	expr = `2 <= 2`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.True.String(), val.String())
+			return value.Number().Multiply(gal.NewNumber(3))
+		},
+	}
 
-	expr = `2 != 2`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.False.String(), val.String())
+	got := parsedExpr.Eval(
+		gal.WithFunctions(funcs),
+	)
+	expected := gal.NewNumber(42)
+	assert.Equal(t, expected.String(), got.String())
+}
 
-	expr = `1 != 2`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.True.String(), val.String())
+// If renaming this test, also update the README.md file, where it is mentioned.
+func TestMultiValueFunctions(t *testing.T) {
+	expr := `sum(div(triple(7) double(4)))`
+	parsedExpr := gal.Parse(expr)
 
-	expr = `3 != 2`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.True.String(), val.String())
+	// step 1: define funcs and vars and Eval the expression
+	funcs := gal.Functions{
+		"double": func(args ...gal.Value) gal.Value {
+			if len(args) != 1 {
+				return gal.NewUndefinedWithReasonf("double() requires a single argument, got %d", len(args))
+			}
 
-	expr = `2 == 2`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.True.String(), val.String())
+			value, ok := args[0].(gal.Numberer)
+			if !ok {
+				return gal.NewUndefinedWithReasonf("double(): syntax error - argument must be a number-like value, got '%v'", args[0])
+			}
 
-	expr = `1 == 2`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.False.String(), val.String())
+			return value.Number().Multiply(gal.NewNumber(2))
+		},
+		"triple": func(args ...gal.Value) gal.Value {
+			if len(args) != 1 {
+				return gal.NewUndefinedWithReasonf("triple() requires a single argument, got %d", len(args))
+			}
 
-	expr = `3 == 2`
-	val = gal.Parse(expr).Eval()
-	assert.Equal(t, gal.False.String(), val.String())
+			value, ok := args[0].(gal.Numberer)
+			if !ok {
+				return gal.NewUndefinedWithReasonf("triple(): syntax error - argument must be a number-like value, got '%v'", args[0])
+			}
+
+			return value.Number().Multiply(gal.NewNumber(3))
+		},
+		"div": func(args ...gal.Value) gal.Value {
+			// returns the division of value1 by value2 as the interger portion and the remainder
+			if len(args) != 2 {
+				return gal.NewUndefinedWithReasonf("mult() requires two arguments, got %d", len(args))
+			}
+
+			dividend := args[0].(gal.Numberer).Number()
+			divisor := args[1].(gal.Numberer).Number()
+
+			quotient := dividend.Divide(divisor).(gal.Numberer).Number().IntPart()
+			remainder := dividend.Number().Sub(quotient.(gal.Number).Multiply(divisor.Number()))
+			return gal.NewMultiValue(quotient, remainder)
+		},
+		"sum": func(args ...gal.Value) gal.Value {
+			// NOTE: we convert the args to a MultiValue to make this function "bilingual".
+			// That way, it can receiv either two Numberer's or one single MultiValue that holds 2 Numberer's.
+			var margs gal.MultiValue
+			if len(args) == 1 {
+				fmt.Println("DEBUG - a single MultiValue")
+				margs = args[0].(gal.MultiValue) // not checking type satisfaction for simplicity
+			}
+			if len(args) == 2 {
+				fmt.Println("DEBUG - two Value's")
+				margs = gal.NewMultiValue(args...)
+			}
+			if margs.Size() != 2 {
+				return gal.NewUndefinedWithReasonf("sum() requires either two Numberer-type Value's or one MultiValue holdings 2 Numberer's, as arguments, but got %d arguments", margs.Size())
+			}
+
+			value1 := args[0].(gal.MultiValue).Get(0).(gal.Numberer)
+			value2 := args[0].(gal.MultiValue).Get(1).(gal.Numberer)
+
+			return value1.Number().Add(value2.Number())
+		},
+	}
+
+	got := parsedExpr.Eval(
+		gal.WithFunctions(funcs),
+	)
+	expected := gal.NewNumber(7)
+	assert.Equal(t, expected.String(), got.String())
+}
+
+func TestStringsWithSpaces(t *testing.T) {
+	expr := `"ab cd" + "ef gh"`
+	parsedExpr := gal.Parse(expr)
+
+	got := parsedExpr.Eval()
+	assert.Equal(t, "ab cdef gh", got.String())
+}
+
+func TestFunctionsAndStringsWithSpaces(t *testing.T) {
+	expr := `f("ab cd") + f("ef gh")`
+	parsedExpr := gal.Parse(expr)
+
+	got := parsedExpr.Eval(
+		gal.WithFunctions(gal.Functions{
+			"f": func(args ...gal.Value) gal.Value {
+				if len(args) != 1 {
+					return gal.NewUndefinedWithReasonf("f() requires a single argument, got %d", len(args))
+				}
+				return args[0]
+			},
+		}),
+	)
+	assert.Equal(t, "ab cdef gh", got.String())
 }

go.mod

@@ -1,4 +1,4 @@
-module github.com/seborama/gal/v7
+module github.com/seborama/gal/v8
 
 go 1.20
 

tree_builder.go

@@ -74,9 +74,11 @@ func (tb TreeBuilder) FromExpr(expr string) (Tree, error) {
 				return nil, err
 			}
 			if fname == "" {
+				// parenthesis grouping, not a real function per-se.
+				// conceptually, parenthesis grouping is a special case of anonymous identity function
 				tree = append(tree, v)
 			} else {
-				bodyFn := PreDefinedFunction(fname)
+				bodyFn := BuiltInFunction(fname)
 				tree = append(tree, NewFunction(fname, bodyFn, v.Split()...))
 			}
 
@@ -166,7 +168,7 @@ func extractPart(expr string) (string, exprType, int, error) {
 	}
 
 	// read part - number
-	// TODO: complex numbers are not supported
+	// TODO: complex numbers are not supported - could be "native" or via function or perhaps even a MultiValue?
 	s, l, err := readNumber(expr[pos:])
 	if err != nil {
 		return "", unknownType, 0, err

tree_builder_test.go

@@ -4,7 +4,7 @@ import (
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
-	"github.com/seborama/gal/v7"
+	"github.com/seborama/gal/v8"
 	"github.com/stretchr/testify/require"
 )
 

tree_test.go

@@ -4,7 +4,7 @@ import (
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
-	"github.com/seborama/gal/v7"
+	"github.com/seborama/gal/v8"
 	"github.com/stretchr/testify/assert"
 )