kavun

package module
v0.2.2 Latest Latest
Warning

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

 Go to latest Published: May 12, 2026 License: MIT Imports: 15 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 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.
  • 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

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

Variables

This section is empty.

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 AssignmentMode 

type AssignmentMode int

AssignmentMode controls how plain '=' handles unresolved identifiers. 

const (
	// AssignmentModeSmart declares a variable in current scope for unresolved '=' assignments.
	AssignmentModeSmart AssignmentMode = iota

	// AssignmentModeStrict requires variables to already exist for '=' assignments.
	AssignmentModeStrict
)

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 added in v0.0.7 

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 Compiler 

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

Compiler compiles the AST into a bytecode.

func NewCompiler 

func NewCompiler(
	alloc *core.Arena,
	file *parser.SourceFile,
	symbolTable *vm.SymbolTable,
	constants []core.Value,
	modules vm.ModuleGetter,
	trace io.Writer,
) *Compiler

NewCompiler creates a Compiler.

func (*Compiler) Bytecode 

func (c *Compiler) Bytecode() *vm.Bytecode

Bytecode returns a compiled bytecode.

func (*Compiler) Compile 

func (c *Compiler) Compile(node parser.Node) error

Compile compiles the AST node.

func (*Compiler) EnableFileImport 

func (c *Compiler) EnableFileImport(enable bool)

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

func (*Compiler) GetAssignmentMode 

func (c *Compiler) GetAssignmentMode() AssignmentMode

GetAssignmentMode returns the active assignment mode.

func (*Compiler) GetImportFileExt 

func (c *Compiler) GetImportFileExt() []string

GetImportFileExt returns the current list of extension name. These are the complementary suffix of the source file to search and load local module files.

func (*Compiler) SetAssignmentMode 

func (c *Compiler) SetAssignmentMode(mode AssignmentMode)

SetAssignmentMode sets how plain '=' handles unresolved identifiers.

func (*Compiler) SetImportDir 

func (c *Compiler) SetImportDir(dir string)

SetImportDir sets the initial import directory path for file imports.

func (*Compiler) SetImportFileExt 

func (c *Compiler) SetImportFileExt(exts ...string) error

SetImportFileExt sets the extension name of the source file for loading local module files. Use this method if you want other source file extension than ".kvn". This function requires at least one argument, since it will replace the current list of extension name.

type CompilerError 

type CompilerError struct {
	FileSet *parser.SourceFileSet
	Node    parser.Node
	Err     error
}

CompilerError represents a compiler error.

func (*CompilerError) Error 

func (e *CompilerError) Error() string

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 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 added in v0.0.6 

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.

Source Files

View all Source files

Directories

Path Synopsis
cmd
bench command
gen-templates command
kavun command
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
conv
format
json
require
unit
unit/stdlib/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.