kavun

README

Kavun

Kavun (кавун, watermelon) is a lightweight, high-performance, embeddable scripting language for Go, built around expression-oriented programming and consistent language design principles. Its feature set, including f-strings, arrow-function lambdas, data-type member functions, and fluent chaining, enables transformation-heavy code to be written as clear expressions instead of loop-and-branch boilerplate. It runs on a bytecode VM implemented in Go, making embedding and sandboxing straightforward in Go services and tools.

Quick Start

Install the cli with Go's toolchain:

go install github.com/jokruger/kavun/cmd/kavun@latest

Or download a prebuilt binary from the latest release:

Then you can run Kavun scripts with the kavun command or using hashbang:

#!/usr/bin/env kavun

fmt = import("fmt")

result = [1, 2, 3, 4, 5, 6]
  .filter(x => x % 2 == 0)
  .map(x => x * x)
  .reduce(0, (sum, x) => sum + x)

fmt.println(f"sum of even squares: {result}")

See more examples.

Benchmark Results

Full benchmark results are available in the Kavun Benchmarks report. A summary is shown below:

Rank	Engine	CPU geomean	Avg rank	Worst ratio	Wins	Mem geomean	Tasks run	Missing
1	kavun0	1.03×	1.44	1.16×	5	1.20×	9	0
2	kavun	1.09×	1.78	1.25×	3	1.04×	9	0
3	gopherlua	1.63×	3.78	3.98×	1	208.63×	9	0
4	golua	1.68×	4.33	2.40×	0	291.49×	9	0
5	starlark	2.62×	5.11	5.15×	0	202.66×	9	0
6	tengo	3.30×	5.33	59.98×	0	1502.91×	9	0
7	goja	5.35×	7.22	11.08×	0	379.43×	9	0
8	risor	6.55×	7.00	180.74×	0	3958.94×	9	0

Documentation

• Installing - Instructions for installing the Kavun CLI.
• Embedding - Guide to embedding the Kavun runtime in Go applications.
• Language Reference - Syntax, expressions, statements, functions, modules, built-ins, and diagnostics.
• Type Reference - Detailed builtin type semantics, conversions, and member functions.
• Standard Library - Overview of standard library modules and their APIs.
• Examples - Short, runnable snippets showcasing key language features.
• Virtual Machine - Virtual machine specifics and limitations.
• Project Structure - Explanation of the repository layout and development workflow.
• Coding Conventions - Guidelines for code style and contributions.

Contributing

Before contributing, please review docs/project.md and docs/conventions.md for project layout, coding standards and repository contracts.

1. Fork the repository and clone your fork locally.
2. Make your changes in a focused branch.
3. Run the test suite.
4. Add or update tests in tests/unit for any change that affects language or runtime behavior.
5. Open a pull request describing the motivation for the change and any new or changed semantics.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements

This project is based on script language Tengo by Daniel Kang. A special thanks to Tengo's creator and contributors.

Documentation

Index

• Constants
• func Eval(ctx context.Context, expr string, params map[string]core.Value) (any, error)
• type Compiled
  • func (c *Compiled) Clone(a *core.Arena) (*Compiled, error)
  • func (c *Compiled) Get(name string) *Variable
  • func (c *Compiled) GetAll() []*Variable
  • func (c *Compiled) GetValue(name string) core.Value
  • func (c *Compiled) Run(a *core.Arena, v *vm.VM) error
  • func (c *Compiled) RunContext(ctx context.Context, a *core.Arena, v *vm.VM) (err error)
  • func (c *Compiled) Set(name string, val core.Value) error
  • func (c *Compiled) Size() int64
• type Script
  • func NewScript(input []byte) *Script
  • func (s *Script) Add(name string, val core.Value)
  • func (s *Script) Compile(a *core.Arena) (*Compiled, error)
  • func (s *Script) EnableFileImport(enable bool)
  • func (s *Script) Remove(name string) bool
  • func (s *Script) SetAssignmentMode(mode compiler.AssignmentMode)
  • func (s *Script) SetImportDir(dir string) error
  • func (s *Script) SetImports(modules vm.ModuleGetter)
  • func (s *Script) SetMaxConstObjects(n int)
• type Variable
  • func NewVariable(name string, val core.Value) *Variable
  • func (v *Variable) Array() []any
  • func (v *Variable) Bool() bool
  • func (v *Variable) Bytes() []byte
  • func (v *Variable) Error() error
  • func (v *Variable) Float() float64
  • func (v *Variable) Int() int64
  • func (v *Variable) IsUndefined() bool
  • func (v *Variable) Map() map[string]any
  • func (v *Variable) Name() string
  • func (v *Variable) Object() core.Value
  • func (v *Variable) Rune() rune
  • func (v *Variable) String() string
  • func (v *Variable) Time() time.Time
  • func (v *Variable) Value() core.Value
  • func (v *Variable) ValueType() string

Constants

const (
	// SourceFileExtDefault is the default extension for source files.
	SourceFileExtDefault = ".kvn"
)

Functions

func Eval

func Eval(ctx context.Context, expr string, params map[string]core.Value) (any, error)

Eval compiles and executes given expr with params, and returns an evaluated value. Argument `expr` must be an expression. Otherwise it will fail to compile. Expression must not use or define variable "__res__" as it's reserved for the internal usage.

Types

type Compiled

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

Compiled is a compiled instance of the user script. Use Script.Compile() to create Compiled object.

func (*Compiled) Clone

func (c *Compiled) Clone(a *core.Arena) (*Compiled, error)

Clone creates a new copy of Compiled.

func (*Compiled) Get

func (c *Compiled) Get(name string) *Variable

Get returns a variable identified by the name. Must be used right after script execution to get the updated variable. Otherwise, the result in ambiguous.

func (*Compiled) GetAll

func (c *Compiled) GetAll() []*Variable

GetAll returns all the variables that are defined by the compiled script. Must be used right after script execution to get the updated variables. Otherwise, the result in ambiguous.

func (*Compiled) GetValue

func (c *Compiled) GetValue(name string) core.Value

GetValue returns a value identified by the name. Must be used right after script execution to get the updated value. Otherwise, the result in ambiguous.

func (*Compiled) Run

func (c *Compiled) Run(a *core.Arena, v *vm.VM) error

Run executes the compiled script in the virtual machine.

func (*Compiled) RunContext

func (c *Compiled) RunContext(ctx context.Context, a *core.Arena, v *vm.VM) (err error)

RunContext is like Run but includes a context.

func (*Compiled) Set

func (c *Compiled) Set(name string, val core.Value) error

Set replaces the value of a global variable identified by the name (must be used before script execution). An error will be returned if the name was not defined during compilation.

func (*Compiled) Size

func (c *Compiled) Size() int64

Size of compiled script in bytes (as much as we can calculate it without reflection and black magic)

type Script

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

Script simplifies compilation and execution of embedded scripts.

func NewScript

func NewScript(input []byte) *Script

NewScript creates a Script instance with an input script.

func (*Script) Add

func (s *Script) Add(name string, val core.Value)

Add adds a new variable or updates an existing variable to the script.

func (*Script) Compile

func (s *Script) Compile(a *core.Arena) (*Compiled, error)

Compile compiles the script with all the defined variables, and, returns Compiled object. If compile-time arena is not provided, a new default arena will be used.

func (*Script) EnableFileImport

func (s *Script) EnableFileImport(enable bool)

EnableFileImport enables or disables module loading from local files. Local file modules are disabled by default.

func (*Script) Remove

func (s *Script) Remove(name string) bool

Remove removes (undefine) an existing variable for the script. It returns false if the variable name is not defined.

func (*Script) SetAssignmentMode

func (s *Script) SetAssignmentMode(mode compiler.AssignmentMode)

SetAssignmentMode sets how plain '=' handles unresolved identifiers during compilation.

func (*Script) SetImportDir

func (s *Script) SetImportDir(dir string) error

SetImportDir sets the initial import directory for script files.

func (*Script) SetImports

func (s *Script) SetImports(modules vm.ModuleGetter)

SetImports sets import modules.

func (*Script) SetMaxConstObjects

func (s *Script) SetMaxConstObjects(n int)

SetMaxConstObjects sets the maximum number of objects in the compiled constants.

type Variable

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

Variable is a user-defined variable for the script.

func NewVariable

func NewVariable(name string, val core.Value) *Variable

NewVariable creates a Variable.

func (*Variable) Array

func (v *Variable) Array() []any

Array returns []interface value of the variable value. It returns 0 if the value is not convertible to []interface.

func (*Variable) Bool

func (v *Variable) Bool() bool

Bool returns bool value of the variable value. It returns 0 if the value is not convertible to bool.

func (*Variable) Bytes

func (v *Variable) Bytes() []byte

Bytes returns a byte slice of the variable value. It returns nil if the value is not convertible to byte slice.

func (*Variable) Error

func (v *Variable) Error() error

Error returns an error if the underlying value is error object. If not, this returns nil.

func (*Variable) Float

func (v *Variable) Float() float64

Float returns float64 value of the variable value. It returns 0.0 if the value is not convertible to float64.

func (*Variable) Int

func (v *Variable) Int() int64

Int returns int64 value of the variable value. It returns 0 if the value is not convertible to int64.

func (*Variable) IsUndefined

func (v *Variable) IsUndefined() bool

IsUndefined returns true if the underlying value is undefined.

func (*Variable) Map

func (v *Variable) Map() map[string]any

Map returns map[string]any value of the variable value. It returns 0 if the value is not convertible to map[string]any.

func (*Variable) Name

func (v *Variable) Name() string

Name returns the name of the variable.

func (*Variable) Object

func (v *Variable) Object() core.Value

Object returns an underlying Object of the variable value. Note that returned Object is a copy of an actual Object used in the script.

func (*Variable) Rune

func (v *Variable) Rune() rune

Rune returns rune value of the variable value. It returns 0 if the value is not convertible to rune.

func (*Variable) String

func (v *Variable) String() string

String returns string value of the variable value. It returns 0 if the value is not convertible to string.

func (*Variable) Time

func (v *Variable) Time() time.Time

Time returns time.Time value of the variable value. It returns zero time if the value is not convertible to time.Time.

func (*Variable) Value

func (v *Variable) Value() core.Value

Value returns the value of the variable.

func (*Variable) ValueType

func (v *Variable) ValueType() string

ValueType returns the name of the value type.