kavun

package module
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 1, 2026 License: MIT Imports: 14 Imported by: 0

README

Kavun

Kavun Logo

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 kavun 1.01× 1.11 1.05× 8 1.04× 9 0
2 gopherlua 1.59× 2.78 4.87× 1 180.03× 9 0
3 golua 1.61× 3.33 2.35× 0 251.53× 9 0
4 starlark 2.55× 4.22 5.17× 0 174.88× 9 0
5 tengo 3.15× 4.33 69.56× 0 1296.87× 9 0
6 goja 5.16× 6.22 10.85× 0 327.41× 9 0
7 risor 6.32× 6.00 230.43× 0 3416.20× 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.
  • Coding Conventions - Guidelines for code style and contributions.

Contributing

Before contributing, please review 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

View Source 
const (
	// SourceFileExtDefault is the default extension for source files.
	SourceFileExtDefault = ".kvn"
	UsedDefinedModule    = module.UserDefined
	UserDefinedType      = value.FirstUserDefinedType
)

Variables

View Source 
var (
	NewBuiltinFunction = core.NewBuiltinFunction
	InitModule         = stdlib.InitModule
	AllModuleNames     = stdlib.AllModuleNames
)

Functions

func Eval 

func Eval(ctx context.Context, expr string, params map[string]any) (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.

func MustValueOf added in v0.4.1 

func MustValueOf(v any) core.Value

func ValueOf added in v0.4.1 

func ValueOf(v any) (core.Value, error)

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() (*Compiled, error)

Clone creates a new copy of Compiled.

func (*Compiled) Get 

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

Get returns the value of a variable identified by the name. If the variable is not defined, it returns Undefined.

func (*Compiled) GetAll 

func (c *Compiled) GetAll() map[string]core.Value

GetAll returns a map of all global variable names to their values.

func (*Compiled) Reset added in v0.4.1 

func (c *Compiled) Reset()

Reset sets all global variable values to Undefined.

func (*Compiled) Run 

func (c *Compiled) Run(v *vm.VM) error

Executes script in the provided virtual machine. It is the caller's responsibility to set all global variables to new values before calling Run.

func (*Compiled) RunContext 

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

Run executes the compiled script in the provided virtual machine with a context for cancellation. It is the caller's responsibility to set all global variables to new values before calling Run.

func (*Compiled) Set 

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

Set sets a variable identified by the name to the value.

type Script 

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

Script represents a script with its source code, variables, and compilation settings. It simplifies the process of compiling and executing embedded scripts by managing the necessary components and configurations.

func NewScript 

func NewScript(source []byte, globals ...string) *Script

NewScript creates a Script instance with the given source code and global variable names (optional). The script is initialized with default settings, including smart assignment mode, file import disabled and all builtin modules allowed.

func (*Script) AddCustomModule added in v0.4.1 

func (s *Script) AddCustomModule(name string, source []byte)

AddCustomModule adds a custom module with the given name and source code.

func (*Script) AddGlobals added in v0.4.1 

func (s *Script) AddGlobals(globals ...string)

AddGlobals adds new global variable names to the script.

func (*Script) Compile 

func (s *Script) Compile() (*Compiled, error)

Compile compiles the script and returns a Compiled instance containing bytecode and global variable indexes.

func (*Script) DisableFileImport added in v0.4.1 

func (s *Script) DisableFileImport()

DisableFileImport disables file import for the script.

func (*Script) EnableFileImport 

func (s *Script) EnableFileImport(path string) error

EnableFileImport enables file import for the script, allowing it to import other scripts from the specified directory.

func (*Script) SetAllowedModules added in v0.4.1 

func (s *Script) SetAllowedModules(modules ...string)

SetAllowedModules sets the allowed builtin module names for import. If not set, all modules are allowed.

func (*Script) SetAssignmentMode 

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

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

func (*Script) SetGlobals added in v0.4.1 

func (s *Script) SetGlobals(globals ...string)

SetGlobals sets the global variable names for the script.

func (*Script) SetSource added in v0.4.1 

func (s *Script) SetSource(source []byte)

SetSource sets the source code for the script.

Source Files

View all Source files

Directories

Path Synopsis
cmd
bench command
gen-templates command
kavun command
bytecode
module
token
value
Package errs defines the structured error type used throughout the Kavun runtime.
 Package errs defines the structured error type used throughout the Kavun runtime.
internal
binary
conv
format
mock
require
json

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.