vibes

package
v0.19.0 Latest Latest
Warning

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

Go to latest
Published: Feb 20, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package vibes implements the VibeScript execution engine. The initial version supports a Ruby-flavoured syntax with the following constructs:

  • Function definitions via `def name(args...) ... end` with implicit return.
  • Literals for ints, floats, strings, bools, nil, arrays, hashes, and symbols.
  • Arithmetic and comparison expressions (+, -, *, /, >, <, ==, !=).
  • Logical operators (and/or/not) and parentheses for grouping.
  • Indexing via `object[expr]` and property access via `object.attr`.
  • Function and method calls with positional and keyword arguments.
  • Built-ins such as `assert`, `money`, and `money_cents`; capabilities are provided by the host and accessed as globals (ctx, db, jobs, etc.).

Comments beginning with `#` are ignored. The interpreter enforces a simple step quota, rejecting scripts that exceed configured execution limits.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ArrayLiteral

type ArrayLiteral struct {
	Elements []Expression
	// contains filtered or unexported fields
}

func (*ArrayLiteral) Pos

func (e *ArrayLiteral) Pos() Position

type AssignStmt

type AssignStmt struct {
	Target Expression
	Value  Expression
	// contains filtered or unexported fields
}

func (*AssignStmt) Pos

func (s *AssignStmt) Pos() Position

type BinaryExpr

type BinaryExpr struct {
	Left     Expression
	Operator TokenType
	Right    Expression
	// contains filtered or unexported fields
}

func (*BinaryExpr) Pos

func (e *BinaryExpr) Pos() Position

type Block

type Block struct {
	Params []Param
	Body   []Statement
	Env    *Env
	// contains filtered or unexported fields
}

type BlockLiteral

type BlockLiteral struct {
	Params []Param
	Body   []Statement
	// contains filtered or unexported fields
}

func (*BlockLiteral) Pos

func (b *BlockLiteral) Pos() Position

type BoolLiteral

type BoolLiteral struct {
	Value bool
	// contains filtered or unexported fields
}

func (*BoolLiteral) Pos

func (e *BoolLiteral) Pos() Position

type BreakStmt added in v0.16.0

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

func (*BreakStmt) Pos added in v0.16.0

func (s *BreakStmt) Pos() Position

type Builtin

type Builtin struct {
	Name       string
	Fn         BuiltinFunc
	AutoInvoke bool
}

type BuiltinFunc

type BuiltinFunc func(exec *Execution, receiver Value, args []Value, kwargs map[string]Value, block Value) (Value, error)

type CallExpr

type CallExpr struct {
	Callee Expression
	Args   []Expression
	KwArgs []KeywordArg
	Block  *BlockLiteral
	// contains filtered or unexported fields
}

func (*CallExpr) Pos

func (e *CallExpr) Pos() Position

type CallOptions

type CallOptions struct {
	Globals      map[string]Value
	Capabilities []CapabilityAdapter
	AllowRequire bool
	Keywords     map[string]Value
}

type CapabilityAdapter

type CapabilityAdapter interface {
	Bind(binding CapabilityBinding) (map[string]Value, error)
}

CapabilityAdapter binds host capabilities into a script invocation.

func MustNewContextCapability added in v0.15.0

func MustNewContextCapability(name string, resolver ContextCapabilityResolver) CapabilityAdapter

MustNewContextCapability constructs a capability adapter or panics on invalid arguments.

func MustNewDBCapability added in v0.15.0

func MustNewDBCapability(name string, db Database) CapabilityAdapter

MustNewDBCapability constructs a capability adapter or panics on invalid arguments.

func MustNewEventsCapability added in v0.15.0

func MustNewEventsCapability(name string, publisher EventPublisher) CapabilityAdapter

MustNewEventsCapability constructs a capability adapter or panics on invalid arguments.

func MustNewJobQueueCapability added in v0.6.0

func MustNewJobQueueCapability(name string, queue JobQueue) CapabilityAdapter

MustNewJobQueueCapability constructs a capability adapter or panics on invalid arguments.

func NewContextCapability added in v0.15.0

func NewContextCapability(name string, resolver ContextCapabilityResolver) (CapabilityAdapter, error)

NewContextCapability constructs a data-only context capability adapter.

func NewDBCapability added in v0.15.0

func NewDBCapability(name string, db Database) (CapabilityAdapter, error)

NewDBCapability constructs a capability adapter bound to the provided name.

func NewEventsCapability added in v0.15.0

func NewEventsCapability(name string, publisher EventPublisher) (CapabilityAdapter, error)

NewEventsCapability constructs a capability adapter bound to the provided name.

func NewJobQueueCapability

func NewJobQueueCapability(name string, queue JobQueue) (CapabilityAdapter, error)

NewJobQueueCapability constructs a capability adapter bound to the provided name.

type CapabilityBinding

type CapabilityBinding struct {
	Context context.Context
	Engine  *Engine
}

CapabilityBinding provides execution context for adapters during binding.

type CapabilityContractProvider added in v0.13.0

type CapabilityContractProvider interface {
	CapabilityContracts() map[string]CapabilityMethodContract
}

CapabilityContractProvider exposes per-method contracts for capability adapters. Contract keys must match builtin method names exposed to scripts (for example "jobs.enqueue").

type CapabilityMethodContract added in v0.13.0

type CapabilityMethodContract struct {
	ValidateArgs   func(args []Value, kwargs map[string]Value, block Value) error
	ValidateReturn func(result Value) error
}

CapabilityMethodContract validates capability method calls at the boundary. These contracts run before and after a capability builtin executes.

type CaseExpr added in v0.16.0

type CaseExpr struct {
	Target   Expression
	Clauses  []CaseWhenClause
	ElseExpr Expression
	// contains filtered or unexported fields
}

func (*CaseExpr) Pos added in v0.16.0

func (e *CaseExpr) Pos() Position

type CaseWhenClause added in v0.16.0

type CaseWhenClause struct {
	Values []Expression
	Result Expression
}

type ClassDef added in v0.5.0

type ClassDef struct {
	Name         string
	Methods      map[string]*ScriptFunction
	ClassMethods map[string]*ScriptFunction
	ClassVars    map[string]Value
	Body         []Statement
	// contains filtered or unexported fields
}

type ClassStmt added in v0.5.0

type ClassStmt struct {
	Name         string
	Methods      []*FunctionStmt
	ClassMethods []*FunctionStmt
	Properties   []PropertyDecl
	Body         []Statement
	// contains filtered or unexported fields
}

func (*ClassStmt) Pos added in v0.5.0

func (s *ClassStmt) Pos() Position

type ClassVarExpr added in v0.5.0

type ClassVarExpr struct {
	Name string
	// contains filtered or unexported fields
}

func (*ClassVarExpr) Pos added in v0.5.0

func (e *ClassVarExpr) Pos() Position

type Config

type Config struct {
	StepQuota        int
	MemoryQuotaBytes int
	StrictEffects    bool
	RecursionLimit   int
	ModulePaths      []string
	ModuleAllowList  []string
	ModuleDenyList   []string
	RandomReader     io.Reader
	MaxCachedModules int
}

Config controls interpreter execution bounds and enforcement modes.

type ContextCapabilityResolver added in v0.15.0

type ContextCapabilityResolver func(ctx context.Context) (Value, error)

ContextCapabilityResolver resolves call-scoped context data for script access.

type DBEachRequest added in v0.15.0

type DBEachRequest struct {
	Collection string
	Options    map[string]Value
}

DBEachRequest captures db.each calls.

type DBFindRequest added in v0.15.0

type DBFindRequest struct {
	Collection string
	ID         Value
	Options    map[string]Value
}

DBFindRequest captures db.find calls.

type DBQueryRequest added in v0.15.0

type DBQueryRequest struct {
	Collection string
	Options    map[string]Value
}

DBQueryRequest captures db.query calls.

type DBSumRequest added in v0.15.0

type DBSumRequest struct {
	Collection string
	Field      string
	Options    map[string]Value
}

DBSumRequest captures db.sum calls.

type DBUpdateRequest added in v0.15.0

type DBUpdateRequest struct {
	Collection string
	ID         Value
	Attributes map[string]Value
	Options    map[string]Value
}

DBUpdateRequest captures db.update calls.

type Database added in v0.15.0

type Database interface {
	Find(ctx context.Context, req DBFindRequest) (Value, error)
	Query(ctx context.Context, req DBQueryRequest) (Value, error)
	Update(ctx context.Context, req DBUpdateRequest) (Value, error)
	Sum(ctx context.Context, req DBSumRequest) (Value, error)
	Each(ctx context.Context, req DBEachRequest) ([]Value, error)
}

Database exposes data access capability methods to scripts.

type Duration

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

Duration stores an integer number of seconds for now.

func (Duration) Seconds

func (d Duration) Seconds() int64

func (Duration) String

func (d Duration) String() string

type Engine

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

Engine executes VibeScript programs with deterministic limits.

func MustNewEngine added in v0.6.0

func MustNewEngine(cfg Config) *Engine

MustNewEngine constructs an Engine or panics if the config is invalid.

func NewEngine

func NewEngine(cfg Config) (*Engine, error)

NewEngine constructs an Engine with sane defaults and registers built-ins.

func (*Engine) Builtins

func (e *Engine) Builtins() map[string]Value

Builtins returns a copy of the registered builtin map.

func (*Engine) ClearModuleCache added in v0.17.0

func (e *Engine) ClearModuleCache() int

ClearModuleCache drops all cached modules and returns the number of entries removed. Long-running hosts can call this between script runs to force fresh module reloads.

func (*Engine) Compile

func (e *Engine) Compile(source string) (*Script, error)

func (*Engine) ConfigSummary

func (e *Engine) ConfigSummary() string

ConfigSummary provides a human-readable description of the interpreter limits.

func (*Engine) Execute

func (e *Engine) Execute(ctx context.Context, script string) error

Execute compiles the provided source ensuring it is valid under current config.

func (*Engine) RegisterBuiltin

func (e *Engine) RegisterBuiltin(name string, fn BuiltinFunc)

RegisterBuiltin registers a callable global available to scripts.

func (*Engine) RegisterZeroArgBuiltin

func (e *Engine) RegisterZeroArgBuiltin(name string, fn BuiltinFunc)

RegisterZeroArgBuiltin registers a builtin that can be invoked without arguments or parentheses.

type Env

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

func (*Env) Assign

func (e *Env) Assign(name string, val Value) bool

func (*Env) CloneShallow

func (e *Env) CloneShallow() *Env

func (*Env) Define

func (e *Env) Define(name string, val Value)

func (*Env) Get

func (e *Env) Get(name string) (Value, bool)

type EventPublishRequest added in v0.15.0

type EventPublishRequest struct {
	Topic   string
	Payload map[string]Value
	Options map[string]Value
}

EventPublishRequest captures events.publish calls.

type EventPublisher added in v0.15.0

type EventPublisher interface {
	Publish(ctx context.Context, req EventPublishRequest) (Value, error)
}

EventPublisher exposes event publication capability methods to scripts.

type Execution

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

func (*Execution) CallBlock added in v0.5.1

func (exec *Execution) CallBlock(block Value, args []Value) (Value, error)

CallBlock invokes a block value with the provided arguments. This is the public entry point for capability adapters that need to call user-supplied blocks (e.g. db.each, db.tx).

type ExprStmt

type ExprStmt struct {
	Expr Expression
	// contains filtered or unexported fields
}

func (*ExprStmt) Pos

func (s *ExprStmt) Pos() Position

type Expression

type Expression interface {
	Node
	// contains filtered or unexported methods
}

type FloatLiteral

type FloatLiteral struct {
	Value float64
	// contains filtered or unexported fields
}

func (*FloatLiteral) Pos

func (e *FloatLiteral) Pos() Position

type ForStmt

type ForStmt struct {
	Iterator string
	Iterable Expression
	Body     []Statement
	// contains filtered or unexported fields
}

func (*ForStmt) Pos

func (s *ForStmt) Pos() Position

type FunctionStmt

type FunctionStmt struct {
	Name          string
	Params        []Param
	ReturnTy      *TypeExpr
	Body          []Statement
	IsClassMethod bool
	Exported      bool
	Private       bool
	// contains filtered or unexported fields
}

func (*FunctionStmt) Pos

func (s *FunctionStmt) Pos() Position

type HashLiteral

type HashLiteral struct {
	Pairs []HashPair
	// contains filtered or unexported fields
}

func (*HashLiteral) Pos

func (e *HashLiteral) Pos() Position

type HashPair

type HashPair struct {
	Key   Expression
	Value Expression
}

type Identifier

type Identifier struct {
	Name string
	// contains filtered or unexported fields
}

func (*Identifier) Pos

func (e *Identifier) Pos() Position

type IfStmt

type IfStmt struct {
	Condition  Expression
	Consequent []Statement
	ElseIf     []*IfStmt
	Alternate  []Statement
	// contains filtered or unexported fields
}

func (*IfStmt) Pos

func (s *IfStmt) Pos() Position

type IndexExpr

type IndexExpr struct {
	Object Expression
	Index  Expression
	// contains filtered or unexported fields
}

func (*IndexExpr) Pos

func (e *IndexExpr) Pos() Position

type Instance added in v0.5.0

type Instance struct {
	Class *ClassDef
	Ivars map[string]Value
}

type IntegerLiteral

type IntegerLiteral struct {
	Value int64
	// contains filtered or unexported fields
}

func (*IntegerLiteral) Pos

func (e *IntegerLiteral) Pos() Position

type InterpolatedString

type InterpolatedString struct {
	Parts []StringPart
	// contains filtered or unexported fields
}

func (*InterpolatedString) Pos

func (s *InterpolatedString) Pos() Position

type IvarExpr added in v0.5.0

type IvarExpr struct {
	Name string
	// contains filtered or unexported fields
}

func (*IvarExpr) Pos added in v0.5.0

func (e *IvarExpr) Pos() Position

type JobQueue

type JobQueue interface {
	Enqueue(ctx context.Context, job JobQueueJob) (Value, error)
}

JobQueue exposes queue functionality to scripts via strongly-typed adapters.

type JobQueueEnqueueOptions

type JobQueueEnqueueOptions struct {
	Delay  *time.Duration
	Key    *string
	Kwargs map[string]Value
}

JobQueueEnqueueOptions represent keyword arguments supplied to enqueue.

type JobQueueJob

type JobQueueJob struct {
	Name    string
	Payload map[string]Value
	Options JobQueueEnqueueOptions
}

JobQueueJob captures a job invocation from script code.

type JobQueueRetryRequest

type JobQueueRetryRequest struct {
	JobID   string
	Options map[string]Value
}

JobQueueRetryRequest captures retry invocations.

type JobQueueWithRetry

type JobQueueWithRetry interface {
	JobQueue
	Retry(ctx context.Context, req JobQueueRetryRequest) (Value, error)
}

JobQueueWithRetry extends JobQueue with a retry operation.

type KeywordArg

type KeywordArg struct {
	Name  string
	Value Expression
}

type MemberExpr

type MemberExpr struct {
	Object   Expression
	Property string
	// contains filtered or unexported fields
}

func (*MemberExpr) Pos

func (e *MemberExpr) Pos() Position

type Money

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

Money represents an ISO-4217 currency amount stored as integer cents.

func (Money) Cents

func (m Money) Cents() int64

func (Money) Currency

func (m Money) Currency() string

func (Money) String

func (m Money) String() string

type NextStmt added in v0.16.0

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

func (*NextStmt) Pos added in v0.16.0

func (s *NextStmt) Pos() Position

type NilLiteral

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

func (*NilLiteral) Pos

func (e *NilLiteral) Pos() Position

type Node

type Node interface {
	Pos() Position
}

type Param added in v0.5.0

type Param struct {
	Name       string
	Type       *TypeExpr
	DefaultVal Expression
	IsIvar     bool
}

type Position

type Position struct {
	Line   int
	Column int
}

Position identifies a byte offset in the source file.

type Program

type Program struct {
	Statements []Statement
}

func (*Program) Pos

func (p *Program) Pos() Position

type PropertyDecl added in v0.5.0

type PropertyDecl struct {
	Names []string
	Kind  string // property/getter/setter
	// contains filtered or unexported fields
}

type RaiseStmt added in v0.17.0

type RaiseStmt struct {
	Value Expression
	// contains filtered or unexported fields
}

func (*RaiseStmt) Pos added in v0.17.0

func (s *RaiseStmt) Pos() Position

type Range

type Range struct {
	Start int64
	End   int64
}

type RangeExpr

type RangeExpr struct {
	Start Expression
	End   Expression
	// contains filtered or unexported fields
}

func (*RangeExpr) Pos

func (e *RangeExpr) Pos() Position

type ReturnStmt

type ReturnStmt struct {
	Value Expression
	// contains filtered or unexported fields
}

func (*ReturnStmt) Pos

func (s *ReturnStmt) Pos() Position

type RuntimeError

type RuntimeError struct {
	Type      string
	Message   string
	CodeFrame string
	Frames    []StackFrame
}

func (*RuntimeError) Error

func (re *RuntimeError) Error() string

func (*RuntimeError) Unwrap

func (re *RuntimeError) Unwrap() error

Unwrap returns nil to satisfy the error unwrapping interface. RuntimeError is a terminal error that wraps the original error message but not the error itself.

type Script

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

func (*Script) Call

func (s *Script) Call(ctx context.Context, name string, args []Value, opts CallOptions) (Value, error)

func (*Script) Classes added in v0.19.0

func (s *Script) Classes() []*ClassDef

Classes returns compiled classes in deterministic name order.

func (*Script) Function

func (s *Script) Function(name string) (*ScriptFunction, bool)

Function looks up a compiled function by name.

func (*Script) Functions added in v0.19.0

func (s *Script) Functions() []*ScriptFunction

Functions returns compiled functions in deterministic name order.

type ScriptFunction

type ScriptFunction struct {
	Name     string
	Params   []Param
	ReturnTy *TypeExpr
	Body     []Statement
	Pos      Position
	Env      *Env
	Exported bool
	Private  bool
	// contains filtered or unexported fields
}

type StackFrame

type StackFrame struct {
	Function string
	Pos      Position
}

type Statement

type Statement interface {
	Node
	// contains filtered or unexported methods
}

type StringExpr

type StringExpr struct {
	Expr Expression
}

type StringLiteral

type StringLiteral struct {
	Value string
	// contains filtered or unexported fields
}

func (*StringLiteral) Pos

func (e *StringLiteral) Pos() Position

type StringPart

type StringPart interface {
	// contains filtered or unexported methods
}

type StringText

type StringText struct {
	Text string
}

type SymbolLiteral

type SymbolLiteral struct {
	Name string
	// contains filtered or unexported fields
}

func (*SymbolLiteral) Pos

func (e *SymbolLiteral) Pos() Position

type Token

type Token struct {
	Type    TokenType
	Literal string
	Pos     Position
}

Token captures lexical information for the parser.

type TokenType

type TokenType string

TokenType identifies the lexical category of a token.

type TryStmt added in v0.17.0

type TryStmt struct {
	Body     []Statement
	RescueTy *TypeExpr
	Rescue   []Statement
	Ensure   []Statement
	// contains filtered or unexported fields
}

func (*TryStmt) Pos added in v0.17.0

func (s *TryStmt) Pos() Position

type TypeExpr added in v0.5.0

type TypeExpr struct {
	Name     string
	Kind     TypeKind
	Nullable bool
	TypeArgs []*TypeExpr
	Shape    map[string]*TypeExpr
	Union    []*TypeExpr
	// contains filtered or unexported fields
}

type TypeKind added in v0.5.1

type TypeKind int
const (
	TypeAny TypeKind = iota
	TypeInt
	TypeFloat
	TypeNumber
	TypeString
	TypeBool
	TypeNil
	TypeDuration
	TypeTime
	TypeMoney
	TypeArray
	TypeHash
	TypeFunction
	TypeShape
	TypeUnion
	TypeUnknown
)

type UnaryExpr

type UnaryExpr struct {
	Operator TokenType
	Right    Expression
	// contains filtered or unexported fields
}

func (*UnaryExpr) Pos

func (e *UnaryExpr) Pos() Position

type UntilStmt added in v0.16.0

type UntilStmt struct {
	Condition Expression
	Body      []Statement
	// contains filtered or unexported fields
}

func (*UntilStmt) Pos added in v0.16.0

func (s *UntilStmt) Pos() Position

type Value

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

func NewArray

func NewArray(a []Value) Value

func NewAutoBuiltin

func NewAutoBuiltin(name string, fn BuiltinFunc) Value

func NewBlock

func NewBlock(params []Param, body []Statement, env *Env) Value

func NewBool

func NewBool(b bool) Value

func NewBuiltin

func NewBuiltin(name string, fn BuiltinFunc) Value

func NewClass added in v0.5.0

func NewClass(def *ClassDef) Value

func NewDuration

func NewDuration(d Duration) Value

func NewFloat

func NewFloat(f float64) Value

func NewFunction

func NewFunction(fn *ScriptFunction) Value

func NewHash

func NewHash(h map[string]Value) Value

func NewInstance added in v0.5.0

func NewInstance(inst *Instance) Value

func NewInt

func NewInt(i int64) Value

func NewMoney

func NewMoney(m Money) Value

func NewNil

func NewNil() Value

func NewObject

func NewObject(attrs map[string]Value) Value

func NewRange

func NewRange(r Range) Value

func NewString

func NewString(s string) Value

func NewSymbol

func NewSymbol(name string) Value

func NewTime added in v0.4.0

func NewTime(t time.Time) Value

func (Value) Array

func (v Value) Array() []Value

func (Value) Block

func (v Value) Block() *Block

func (Value) Bool

func (v Value) Bool() bool

func (Value) Builtin

func (v Value) Builtin() *Builtin

func (Value) Class added in v0.5.0

func (v Value) Class() *ClassDef

func (Value) Duration

func (v Value) Duration() Duration

func (Value) Equal

func (v Value) Equal(other Value) bool

func (Value) Float

func (v Value) Float() float64

func (Value) Function

func (v Value) Function() *ScriptFunction

func (Value) Hash

func (v Value) Hash() map[string]Value

func (Value) Instance added in v0.5.0

func (v Value) Instance() *Instance

func (Value) Int

func (v Value) Int() int64

func (Value) IsNil

func (v Value) IsNil() bool

func (Value) Kind

func (v Value) Kind() ValueKind

func (Value) Money

func (v Value) Money() Money

func (Value) Range

func (v Value) Range() Range

func (Value) String

func (v Value) String() string

func (Value) Time added in v0.4.0

func (v Value) Time() time.Time

func (Value) Truthy

func (v Value) Truthy() bool

type ValueKind

type ValueKind int
const (
	KindNil ValueKind = iota
	KindBool
	KindInt
	KindFloat
	KindString
	KindArray
	KindHash
	KindFunction
	KindBuiltin
	KindMoney
	KindDuration
	KindTime
	KindSymbol
	KindObject
	KindRange
	KindBlock
	KindClass
	KindInstance
)

func (ValueKind) String

func (k ValueKind) String() string

type WhileStmt added in v0.16.0

type WhileStmt struct {
	Condition Expression
	Body      []Statement
	// contains filtered or unexported fields
}

func (*WhileStmt) Pos added in v0.16.0

func (s *WhileStmt) Pos() Position

type YieldExpr added in v0.5.0

type YieldExpr struct {
	Args []Expression
	// contains filtered or unexported fields
}

func (*YieldExpr) Pos added in v0.5.0

func (y *YieldExpr) Pos() Position

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL