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 Builtin
- type BuiltinFunc
- type CallExpr
- type CallOptions
- type CapabilityAdapter
- type CapabilityBinding
- type ClassDef
- type ClassStmt
- type ClassVarExpr
- type Config
- type Duration
- type Engine
- func (e *Engine) Builtins() map[string]Value
- 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 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 NilLiteral
- type Node
- type Param
- type Position
- type Program
- type PropertyDecl
- 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 TypeExpr
- type TypeKind
- type UnaryExpr
- type Value
- func NewArray(a []Value) Value
- func NewAutoBuiltin(name string, fn BuiltinFunc) Value
- func NewBlock(params []string, 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 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 []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 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 MustNewJobQueueCapability ¶ added in v0.6.0
func MustNewJobQueueCapability(name string, queue JobQueue) CapabilityAdapter
MustNewJobQueueCapability constructs a capability adapter or panics on invalid arguments.
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 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
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.
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) 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 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
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 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 {
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
}
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 UnaryExpr ¶
type UnaryExpr struct {
Operator TokenType
Right Expression
// 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