vibes

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Dec 21, 2025 License: MIT Imports: 14 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 []string
	Body   []Statement
	Env    *Env
}

type BlockLiteral

type BlockLiteral struct {
	Params []string
	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 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
}

type CapabilityAdapter

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

CapabilityAdapter binds host capabilities into a script invocation.

func NewJobQueueCapability

func NewJobQueueCapability(name string, queue JobQueue) CapabilityAdapter

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 Config

type Config struct {
	StepQuota        int
	MemoryQuotaBytes int
	StrictEffects    bool
	RecursionLimit   int
	ModulePaths      []string
	MaxCachedModules int
}

Config controls interpreter execution bounds and enforcement modes.

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 NewEngine

func NewEngine(cfg Config) *Engine

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) 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 Execution

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

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 []string
	Body   []Statement
	// 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 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 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 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 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 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 {
	Message 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) Function

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

Function looks up a compiled function by name.

type ScriptFunction

type ScriptFunction struct {
	Name   string
	Params []string
	Body   []Statement
	Pos    Position
	Env    *Env
}

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 UnaryExpr

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

func (*UnaryExpr) Pos

func (e *UnaryExpr) 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 []string, body []Statement, env *Env) Value

func NewBool

func NewBool(b bool) Value

func NewBuiltin

func NewBuiltin(name string, fn BuiltinFunc) 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 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 (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) 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) 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) 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
	KindSymbol
	KindObject
	KindRange
	KindBlock
)

func (ValueKind) String

func (k ValueKind) String() string

Jump to

Keyboard shortcuts

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