add error function

Author: xrstf

docs/README.md

@@ -14,6 +14,7 @@ Welcome to the Rudi documentation :smile:
 * [`delete`](functions/core-delete.md) – removes a key from an object or an item from a vector
 * [`do`](functions/core-do.md) – eval a sequence of statements where only one expression is valid
 * [`empty?`](functions/core-empty.md) – returns true when the given value is empty-ish (0, false, null, "", ...)
+* [`error`](functions/core-error.md) – returns an error
 * [`has?`](functions/core-has.md) – returns true if the given symbol's path expression points to an existing value
 * [`if`](functions/core-if.md) – evaluate one of two expressions based on a condition
 * [`set`](functions/core-set.md) – set a value in a variable/document, only really useful with ! modifier (set!)

docs/functions/README.md

@@ -18,6 +18,7 @@ applied to all functions (so technically `eq?!` is valid, though weird looking).
 * [`delete`](../functions/core-delete.md) – removes a key from an object or an item from a vector
 * [`do`](../functions/core-do.md) – eval a sequence of statements where only one expression is valid
 * [`empty?`](../functions/core-empty.md) – returns true when the given value is empty-ish (0, false, null, "", ...)
+* [`error`](../functions/core-error.md) – returns an error
 * [`has?`](../functions/core-has.md) – returns true if the given symbol's path expression points to an existing value
 * [`if`](../functions/core-if.md) – evaluate one of two expressions based on a condition
 * [`set`](../functions/core-set.md) – set a value in a variable/document, only really useful with ! modifier (set!)

docs/functions/core-error.md

@@ -0,0 +1,28 @@
+# error
+
+`error` creates a new error and returns it, i.e. this function always "fails".
+Errors are constructed using Go's `fmt.Errorf`, so sprintf-style formatting is
+available.
+
+## Examples
+
+* `(error "invalid choice")` -> error `"invalid choice"`
+* `(error "too many replicas: %d" .replicas)` -> error `"too man replicas: 3"`
+
+## Forms
+
+### `(error message)`
+
+* `message` is an arbitrary expression.
+
+`error` evaluates the the message and coalesces it to a string. When successful,
+a new error with the message is created and returned.
+
+### `(error fmt args+)`
+
+* `fmt` is an arbitrary expression.
+* `args` are one ore more expressions.
+
+`error` evaluates the the format and coalesces it to a string. When successful,
+it evaluates all further arguments and passes their results straight into
+`fmt.Errorf` and returns the newly created error.

pkg/builtin/core.go

@@ -307,6 +307,17 @@ func isEmptyFunction(ctx types.Context, args []any) (any, error) {
 	return !boolified, nil
 }
 
+// (error MSG:string)
+// (error FMT:string ARGS+)
+func errorFunction(ctx types.Context, args []any) (any, error) {
+	format, err := ctx.Coalesce().ToString(args[0])
+	if err != nil {
+		return nil, err
+	}
+
+	return nil, fmt.Errorf(format, args[1:]...)
+}
+
 // (strictly EXPR+)
 func strictlyFunction(ctx types.Context, args []ast.Expression) (any, error) {
 	return coalescingChangerFunction(ctx, args, coalescing.NewStrict())

pkg/builtin/functions.go

@@ -14,6 +14,7 @@ var (
 		"delete":  deleteFunction{},
 		"do":      util.NewRawFunction(doFunction, "eval a sequence of statements where only one expression is valid").MinArgs(1),
 		"empty?":  util.NewLiteralFunction(isEmptyFunction, "returns true when the given value is empty-ish (0, false, null, \"\", ...)").MinArgs(1).MaxArgs(1),
+		"error":   util.NewLiteralFunction(errorFunction, "returns an error").MinArgs(1),
 		"has?":    util.NewRawFunction(hasFunction, "returns true if the given symbol's path expression points to an existing value").MinArgs(1).MaxArgs(1),
 		"if":      util.NewRawFunction(ifFunction, "evaluate one of two expressions based on a condition").MinArgs(2).MaxArgs(3),
 		"set":     util.NewRawFunction(setFunction, "set a value in a variable/document, only really useful with ! modifier (set!)").MinArgs(2).MaxArgs(2),