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 ¶
- type ArrayLiteral
- type AssignStmt
- type BinaryExpr
- type Block
- type BlockLiteral
- type BoolLiteral
- type BreakStmt
- type Builtin
- type BuiltinFunc
- type CallExpr
- type CallOptions
- type CapabilityAdapter
- func MustNewContextCapability(name string, resolver ContextCapabilityResolver) CapabilityAdapter
- func MustNewDBCapability(name string, db Database) CapabilityAdapter
- func MustNewEventsCapability(name string, publisher EventPublisher) CapabilityAdapter
- func MustNewJobQueueCapability(name string, queue JobQueue) CapabilityAdapter
- func NewContextCapability(name string, resolver ContextCapabilityResolver) (CapabilityAdapter, error)
- func NewDBCapability(name string, db Database) (CapabilityAdapter, error)
- func NewEventsCapability(name string, publisher EventPublisher) (CapabilityAdapter, error)
- func NewJobQueueCapability(name string, queue JobQueue) (CapabilityAdapter, error)
- type CapabilityBinding
- type CapabilityContractProvider
- type CapabilityMethodContract
- type CaseExpr
- type CaseWhenClause
- type ClassDef
- type ClassStmt
- type ClassVarExpr
- type Config
- type ContextCapabilityResolver
- type DBEachRequest
- type DBFindRequest
- type DBQueryRequest
- type DBSumRequest
- type DBUpdateRequest
- type Database
- type Duration
- type Engine
- func (e *Engine) Builtins() map[string]Value
- func (e *Engine) ClearModuleCache() int
- func (e *Engine) Compile(source string) (*Script, error)
- func (e *Engine) ConfigSummary() string
- func (e *Engine) Execute(ctx context.Context, script string) error
- func (e *Engine) RegisterBuiltin(name string, fn BuiltinFunc)
- func (e *Engine) RegisterZeroArgBuiltin(name string, fn BuiltinFunc)
- type Env
- type EventPublishRequest
- type EventPublisher
- type Execution
- type ExprStmt
- type Expression
- type FloatLiteral
- type ForStmt
- type FunctionStmt
- type HashLiteral
- type HashPair
- type Identifier
- type IfStmt
- type IndexExpr
- type Instance
- type IntegerLiteral
- type InterpolatedString
- type IvarExpr
- type JobQueue
- type JobQueueEnqueueOptions
- type JobQueueJob
- type JobQueueRetryRequest
- type JobQueueWithRetry
- type KeywordArg
- type MemberExpr
- type Money
- type NextStmt
- type NilLiteral
- type Node
- type Param
- type Position
- type Program
- type PropertyDecl
- type RaiseStmt
- type Range
- type RangeExpr
- type ReturnStmt
- type RuntimeError
- type Script
- type ScriptFunction
- type StackFrame
- type Statement
- type StringExpr
- type StringLiteral
- type StringPart
- type StringText
- type SymbolLiteral
- type Token
- type TokenType
- type TryStmt
- type TypeExpr
- type TypeKind
- type UnaryExpr
- type UntilStmt
- type Value
- func NewArray(a []Value) Value
- func NewAutoBuiltin(name string, fn BuiltinFunc) Value
- func NewBlock(params []Param, body []Statement, env *Env) Value
- func NewBool(b bool) Value
- func NewBuiltin(name string, fn BuiltinFunc) Value
- func NewClass(def *ClassDef) Value
- func NewDuration(d Duration) Value
- func NewFloat(f float64) Value
- func NewFunction(fn *ScriptFunction) Value
- func NewHash(h map[string]Value) Value
- func NewInstance(inst *Instance) Value
- func NewInt(i int64) Value
- func NewMoney(m Money) Value
- func NewNil() Value
- func NewObject(attrs map[string]Value) Value
- func NewRange(r Range) Value
- func NewString(s string) Value
- func NewSymbol(name string) Value
- func NewTime(t time.Time) Value
- func (v Value) Array() []Value
- func (v Value) Block() *Block
- func (v Value) Bool() bool
- func (v Value) Builtin() *Builtin
- func (v Value) Class() *ClassDef
- func (v Value) Duration() Duration
- func (v Value) Equal(other Value) bool
- func (v Value) Float() float64
- func (v Value) Function() *ScriptFunction
- func (v Value) Hash() map[string]Value
- func (v Value) Instance() *Instance
- func (v Value) Int() int64
- func (v Value) IsNil() bool
- func (v Value) Kind() ValueKind
- func (v Value) Money() Money
- func (v Value) Range() Range
- func (v Value) String() string
- func (v Value) Time() time.Time
- func (v Value) Truthy() bool
- type ValueKind
- type WhileStmt
- type YieldExpr
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 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
}
type Builtin ¶
type Builtin struct {
Name string
Fn BuiltinFunc
AutoInvoke bool
}
type BuiltinFunc ¶
type CallExpr ¶
type CallExpr struct {
Callee Expression
Args []Expression
KwArgs []KeywordArg
Block *BlockLiteral
// contains filtered or unexported fields
}
type CallOptions ¶
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 ¶
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
}
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
}
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
ContextCapabilityResolver resolves call-scoped context data for script access.
type DBEachRequest ¶ added in v0.15.0
DBEachRequest captures db.each calls.
type DBFindRequest ¶ added in v0.15.0
DBFindRequest captures db.find calls.
type DBQueryRequest ¶ added in v0.15.0
DBQueryRequest captures db.query calls.
type DBSumRequest ¶ added in v0.15.0
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.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine executes VibeScript programs with deterministic limits.
func MustNewEngine ¶ added in v0.6.0
MustNewEngine constructs an Engine or panics if the config is invalid.
func (*Engine) ClearModuleCache ¶ added in v0.17.0
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) ConfigSummary ¶
ConfigSummary provides a human-readable description of the interpreter limits.
func (*Engine) Execute ¶
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 EventPublishRequest ¶ added in v0.15.0
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 ExprStmt ¶
type ExprStmt struct {
Expr Expression
// contains filtered or unexported fields
}
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
}
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
}
type IndexExpr ¶
type IndexExpr struct {
Object Expression
Index Expression
// contains filtered or unexported fields
}
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
}
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 ¶
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 ¶
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.
type NilLiteral ¶
type NilLiteral struct {
// contains filtered or unexported fields
}
func (*NilLiteral) Pos ¶
func (e *NilLiteral) Pos() Position
type Param ¶ added in v0.5.0
type Param struct {
Name string
Type *TypeExpr
DefaultVal Expression
IsIvar bool
}
type PropertyDecl ¶ added in v0.5.0
type RaiseStmt ¶ added in v0.17.0
type RaiseStmt struct {
Value Expression
// contains filtered or unexported fields
}
type RangeExpr ¶
type RangeExpr struct {
Start Expression
End Expression
// contains filtered or unexported fields
}
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) Classes ¶ added in v0.19.0
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 StackFrame ¶
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 TryStmt ¶ added in v0.17.0
type UnaryExpr ¶
type UnaryExpr struct {
Operator TokenType
Right Expression
// contains filtered or unexported fields
}
type UntilStmt ¶ added in v0.16.0
type UntilStmt struct {
Condition Expression
Body []Statement
// contains filtered or unexported fields
}
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
func NewAutoBuiltin ¶
func NewAutoBuiltin(name string, fn BuiltinFunc) Value
func NewBuiltin ¶
func NewBuiltin(name string, fn BuiltinFunc) Value
func NewDuration ¶
func NewFunction ¶
func NewFunction(fn *ScriptFunction) Value
func NewInstance ¶ added in v0.5.0
func (Value) Function ¶
func (v Value) Function() *ScriptFunction
type WhileStmt ¶ added in v0.16.0
type WhileStmt struct {
Condition Expression
Body []Statement
// contains filtered or unexported fields
}
Source Files
¶
- ast.go
- builtins.go
- call_rebind.go
- capabilities.go
- capability_common.go
- capability_context.go
- capability_contracts.go
- capability_db.go
- capability_events.go
- capability_jobqueue.go
- class.go
- doc.go
- duration.go
- env.go
- error_format.go
- execution.go
- interpreter.go
- lexer.go
- memory.go
- modules.go
- money.go
- parser.go
- strict_effects.go
- time_member.go
- time_value.go
- token.go
- value.go