Documentation
¶
Index ¶
- Variables
- func FormatCallFrame(frame CallFrame) string
- func FormatCallStack(stack []CallFrame) string
- func FormatPlain(obj Object) string
- func IsError(obj Object) bool
- func IsTruthy(obj Object) bool
- func ParseBoolEnvDefault(name string, def bool) bool
- func ParseCSVEnv(name string) []string
- func ParsePositiveInt64Env(name string) int64
- func ParsePositiveIntEnv(name string) int
- func RegisterShutdownHook(hook func(ctx context.Context))
- func ReleasePooledEnvironment(env *Environment)
- func RunShutdownHooks(grace time.Duration)
- func SameCallFrame(a, b CallFrame) bool
- type ADTTypeDef
- type ADTValue
- type Array
- type Boolean
- type Break
- type Builtin
- type BuiltinFunction
- type BuiltinFunction1
- type BuiltinFunctionWithEnv
- type CallFrame
- type Channel
- type ClassFieldDef
- type ClassInstance
- type ClassObject
- func (c *ClassObject) GetMethod(name string) (*Function, bool)
- func (c *ClassObject) GetMethodOwner(name string) (*Function, *ClassObject, bool)
- func (c *ClassObject) GetStaticFieldOwner(name string) (Object, *ClassObject, bool)
- func (c *ClassObject) GetStaticMethod(name string) (*Function, bool)
- func (c *ClassObject) GetStaticMethodOwner(name string) (*Function, *ClassObject, bool)
- func (c *ClassObject) Inspect() string
- func (c *ClassObject) NewInstance() *ClassInstance
- func (c *ClassObject) Type() ObjectType
- type Continue
- type DB
- type DBTx
- type Environment
- func (e *Environment) AddRenderArtifact(art *RenderArtifact)
- func (e *Environment) Assign(name string, val Object) (Object, bool)
- func (e *Environment) BindingsSealed() bool
- func (e *Environment) EnsureOwnerID() string
- func (e *Environment) Get(name string) (Object, bool)
- func (e *Environment) GetSecurityPolicy() *SecurityPolicy
- func (e *Environment) HasOwner(ownerID string) bool
- func (e *Environment) IsConstant(name string) bool
- func (e *Environment) ModuleCacheMap() map[string]ModuleCacheEntry
- func (e *Environment) ModuleLoadingMap() map[string]bool
- func (e *Environment) Names() []string
- func (e *Environment) RegisterCleanup(fn func())
- func (e *Environment) Reset()
- func (e *Environment) RunCleanup()
- func (e *Environment) SealBindings()
- func (e *Environment) Set(name string, val Object) Object
- func (e *Environment) SetConst(name string, val Object) Object
- func (e *Environment) SetSecurityPolicy(policy *SecurityPolicy)
- func (e *Environment) Snapshot() map[string]Object
- type Error
- type FileValue
- type Float
- type Function
- type Future
- type GeneratorValue
- type Hash
- type HashKey
- type HashPair
- type Hashable
- type ImageValue
- type ImmutableValue
- type Integer
- type InterfaceLiteral
- type LazyValue
- type Macro
- type ModuleCacheEntry
- type ModuleContext
- type Null
- type Object
- type ObjectType
- type OwnedValue
- type RenderArtifact
- type RenderConfig
- type ReturnValue
- type RuntimeLimits
- type Secret
- type SecurityPolicy
- type Stream
- type String
- type SuperBinding
- type TableValue
- type TestStats
Constants ¶
This section is empty.
Variables ¶
var ( TRUE = &Boolean{Value: true} FALSE = &Boolean{Value: false} NULL = &Null{} BREAK = &Break{} CONT = &Continue{} )
var ApplyFunctionFn func(fn Object, args []Object, env *Environment) Object
ApplyFunctionFn calls a function object (Function or Builtin) with args.
var EvalFn func(node ast.Node, env *Environment) Object
EvalFn evaluates an AST node in the given environment.
var ExtendFunctionEnvFn func(fn *Function, args []Object, callerEnv *Environment) *Environment
ExtendFunctionEnvFn creates a new enclosed environment for a function call.
var UnwrapReturnValueFn func(obj Object) Object
UnwrapReturnValueFn unwraps a ReturnValue object to its inner value.
Functions ¶
func FormatCallFrame ¶
func FormatCallStack ¶
func FormatPlain ¶
func ParseBoolEnvDefault ¶
func ParseCSVEnv ¶
func ParsePositiveInt64Env ¶
ParsePositiveInt64Env reads an environment variable and returns its value as a positive int64. Returns 0 if unset, empty, or not a positive integer.
func ParsePositiveIntEnv ¶
ParsePositiveIntEnv reads an environment variable and returns its value as a positive int. Returns 0 if unset, empty, or not a positive integer.
func RegisterShutdownHook ¶
RegisterShutdownHook registers a function to be called when the process is asked to shut down gracefully. The hook receives a context bounded by the overall grace period passed to RunShutdownHooks and should respect it rather than blocking indefinitely.
func ReleasePooledEnvironment ¶
func ReleasePooledEnvironment(env *Environment)
func RunShutdownHooks ¶
RunShutdownHooks invokes every registered shutdown hook concurrently and waits for them to finish or for the grace period to elapse, whichever comes first.
func SameCallFrame ¶
Types ¶
type ADTTypeDef ¶
func (*ADTTypeDef) Inspect ¶
func (a *ADTTypeDef) Inspect() string
func (*ADTTypeDef) Type ¶
func (a *ADTTypeDef) Type() ObjectType
type ADTValue ¶
type ADTValue struct {
TypeName string
VariantName string
FieldNames []string
Values []Object
AllVariants []string
}
func (*ADTValue) Type ¶
func (a *ADTValue) Type() ObjectType
type Array ¶
type Array struct {
Elements []Object
}
func (*Array) Type ¶
func (ao *Array) Type() ObjectType
type Boolean ¶
type Boolean struct {
Value bool
}
func NativeBoolToBooleanObject ¶
NativeBoolToBooleanObject converts a Go bool to the canonical Boolean singleton.
func (*Boolean) Type ¶
func (b *Boolean) Type() ObjectType
type Builtin ¶
type Builtin struct {
Fn BuiltinFunction
Fn1 BuiltinFunction1
FnWithEnv BuiltinFunctionWithEnv
Env *Environment
}
func (*Builtin) BindEnv ¶
func (b *Builtin) BindEnv(env *Environment) *Builtin
func (*Builtin) Type ¶
func (b *Builtin) Type() ObjectType
type BuiltinFunction ¶
type BuiltinFunction1 ¶
type BuiltinFunctionWithEnv ¶
type BuiltinFunctionWithEnv func(env *Environment, args ...Object) Object
type Channel ¶
type Channel struct {
Ch chan Object
}
func (*Channel) Type ¶
func (c *Channel) Type() ObjectType
type ClassFieldDef ¶
type ClassFieldDef struct {
Name string
ValueExpr ast.Expression
Env *Environment
IsPrivate bool
}
ClassFieldDef is a declared instance or static field on a class body (e.g. `private count = 0;`). ValueExpr/Env are used to (re-)evaluate the default per-instance so mutable defaults (arrays, hashes) aren't shared.
type ClassInstance ¶
type ClassInstance struct {
Class *ClassObject
Fields map[string]Object
// PrivateOwner maps a private field/method name to the name of the
// class that declared it private, for access-control checks.
PrivateOwner map[string]string
}
func (*ClassInstance) Inspect ¶
func (ci *ClassInstance) Inspect() string
func (*ClassInstance) Set ¶
func (ci *ClassInstance) Set(name string, val Object)
func (*ClassInstance) Type ¶
func (ci *ClassInstance) Type() ObjectType
type ClassObject ¶
type ClassObject struct {
Name string
Parent *ClassObject
Methods map[string]*Function
StaticMethods map[string]*Function
Fields map[string]Object // evaluated static field values
InstanceFieldDefs []*ClassFieldDef // instance fields declared directly on this class
PrivateMembers map[string]bool // method/static-field names declared private on this class
IsAbstract bool
Builtin *Builtin
Implements []string
}
func (*ClassObject) GetMethodOwner ¶
func (c *ClassObject) GetMethodOwner(name string) (*Function, *ClassObject, bool)
func (*ClassObject) GetStaticFieldOwner ¶
func (c *ClassObject) GetStaticFieldOwner(name string) (Object, *ClassObject, bool)
func (*ClassObject) GetStaticMethod ¶
func (c *ClassObject) GetStaticMethod(name string) (*Function, bool)
func (*ClassObject) GetStaticMethodOwner ¶
func (c *ClassObject) GetStaticMethodOwner(name string) (*Function, *ClassObject, bool)
func (*ClassObject) Inspect ¶
func (c *ClassObject) Inspect() string
func (*ClassObject) NewInstance ¶
func (c *ClassObject) NewInstance() *ClassInstance
func (*ClassObject) Type ¶
func (c *ClassObject) Type() ObjectType
type DB ¶
type DB struct {
Handle any
}
DB represents an optional database connection value. The concrete Handle is owned by an opt-in database builtin package so the core object package does not depend on any database driver module.
func (*DB) Type ¶
func (db *DB) Type() ObjectType
type DBTx ¶
type DBTx struct {
Handle any
}
DBTx represents an optional database transaction value. The concrete Handle is owned by an opt-in database builtin package.
func (*DBTx) Type ¶
func (tx *DBTx) Type() ObjectType
type Environment ¶
type Environment struct {
Mu sync.RWMutex
Store map[string]Object
Constants map[string]struct{}
Outer *Environment
ModuleContext *ModuleContext
ModuleDir string
SourcePath string
ModuleCache map[string]ModuleCacheEntry
ModuleLoading map[string]bool
RuntimeLimits *RuntimeLimits
SecurityPolicy *SecurityPolicy
Output io.Writer
RenderConfig *RenderConfig
RenderArtifacts []*RenderArtifact
RenderArtifactSink *[]*RenderArtifact
CollectRenderArtifacts bool
CallStack []CallFrame
OwnerID string
Cleanup []func()
YieldSink *[]Object
// contains filtered or unexported fields
}
func NewEnclosedEnvironment ¶
func NewEnclosedEnvironment(outer *Environment) *Environment
func NewEnvironment ¶
func NewEnvironment() *Environment
func NewGlobalEnvironment ¶
func NewGlobalEnvironment(args []string) *Environment
func NewPooledEnvironment ¶
func NewPooledEnvironment() *Environment
NewPooledEnvironment returns a reusable environment for allocation-sensitive embedding paths. Call ReleasePooledEnvironment when the evaluation is done.
func (*Environment) AddRenderArtifact ¶
func (e *Environment) AddRenderArtifact(art *RenderArtifact)
func (*Environment) BindingsSealed ¶
func (e *Environment) BindingsSealed() bool
BindingsSealed reports whether binding mutation has been disabled.
func (*Environment) EnsureOwnerID ¶
func (e *Environment) EnsureOwnerID() string
func (*Environment) GetSecurityPolicy ¶
func (e *Environment) GetSecurityPolicy() *SecurityPolicy
GetSecurityPolicy returns the environment's current per-execution security policy override. SecurityPolicy is an ordinary struct field shared across goroutines that close over the same Environment (e.g. via go/go_async/spawn builtins), so reads and writes go through this lock-guarded accessor rather than touching the field directly.
func (*Environment) HasOwner ¶
func (e *Environment) HasOwner(ownerID string) bool
HasOwner reports whether ownerID belongs to e or any of its ancestor scopes. Reading a variable through a nested scope (closures, loop bodies, blocks) walks up this chain via the normal lexical lookup, so an owner found anywhere in the chain is a legitimate read rather than a cross-scope move.
func (*Environment) IsConstant ¶
func (e *Environment) IsConstant(name string) bool
IsConstant reports whether name resolves to a constant in the lexical chain.
func (*Environment) ModuleCacheMap ¶
func (e *Environment) ModuleCacheMap() map[string]ModuleCacheEntry
func (*Environment) ModuleLoadingMap ¶
func (e *Environment) ModuleLoadingMap() map[string]bool
func (*Environment) Names ¶
func (e *Environment) Names() []string
func (*Environment) RegisterCleanup ¶
func (e *Environment) RegisterCleanup(fn func())
func (*Environment) Reset ¶
func (e *Environment) Reset()
func (*Environment) RunCleanup ¶
func (e *Environment) RunCleanup()
func (*Environment) SealBindings ¶
func (e *Environment) SealBindings()
SealBindings marks the current binding map as immutable and enables lock-free reads. It is intended for prepared, expression-only workloads. Any subsequent Set, SetConst, or Assign call panics; call Reset to reuse a pooled environment as writable again. Seal only after all bindings have been injected and while no goroutine is mutating the environment.
func (*Environment) SetConst ¶
func (e *Environment) SetConst(name string, val Object) Object
SetConst creates an immutable binding. The bound object itself is not deep-frozen; use immutable() when deep mutation must also be prohibited.
func (*Environment) SetSecurityPolicy ¶
func (e *Environment) SetSecurityPolicy(policy *SecurityPolicy)
SetSecurityPolicy sets the environment's per-execution security policy override. See GetSecurityPolicy for why this must not be a bare field write.
func (*Environment) Snapshot ¶
func (e *Environment) Snapshot() map[string]Object
type Error ¶
type Error struct {
Message string
Code string
Path string
Line int
Column int
Stack []CallFrame
// ModuleChain records the import path of each module a runtime error
// propagated through, outermost first (e.g. the entry script's own
// import, then the module it imported, ...), ending with the module
// where the error actually occurred. Populated alongside Message
// (which still carries the same information as one concatenated
// string, for callers - e.g. SPL try/catch - that only look at
// Message/Inspect()) so CLI-style callers can render each hop on its
// own line instead of parsing that string back apart.
ModuleChain []string
// LeafMessage is the original, unwrapped error message from the
// innermost module (before any "module runtime error in ..." prefixes
// were added), captured once at the point the error first occurred.
LeafMessage string
}
func (*Error) Type ¶
func (e *Error) Type() ObjectType
type FileValue ¶
type FileValue struct {
Name string
Path string
MIME string
Encoding string
SourceType string
Size int64
Data []byte
}
func (*FileValue) Type ¶
func (f *FileValue) Type() ObjectType
type Float ¶
type Float struct {
Value float64
}
func (*Float) Type ¶
func (f *Float) Type() ObjectType
type Function ¶
type Function struct {
Name string
Parameters []*ast.Identifier
ParamTypes []string
Defaults []ast.Expression
ReturnType string
HasRest bool
Body *ast.BlockStatement
Env *Environment
IsAsync bool
IsGenerator bool
}
func (*Function) Type ¶
func (f *Function) Type() ObjectType
type Future ¶
func (*Future) Type ¶
func (f *Future) Type() ObjectType
type GeneratorValue ¶
type GeneratorValue struct {
Elements []Object
Env *Environment
Body *ast.BlockStatement
Func *Function
Index int
Done bool
}
func (*GeneratorValue) Inspect ¶
func (g *GeneratorValue) Inspect() string
func (*GeneratorValue) Next ¶
func (g *GeneratorValue) Next() (Object, bool)
func (*GeneratorValue) Type ¶
func (g *GeneratorValue) Type() ObjectType
type HashKey ¶
type HashKey struct {
Type ObjectType
Value uint64
}
type ImageValue ¶
type ImageValue struct {
Name string
Path string
MIME string
Format string
SourceType string
Width int64
Height int64
Data []byte
Image image.Image
}
func (*ImageValue) Inspect ¶
func (i *ImageValue) Inspect() string
func (*ImageValue) Type ¶
func (i *ImageValue) Type() ObjectType
type ImmutableValue ¶
type ImmutableValue struct {
Inner Object
}
func (*ImmutableValue) Inspect ¶
func (i *ImmutableValue) Inspect() string
func (*ImmutableValue) Type ¶
func (i *ImmutableValue) Type() ObjectType
type Integer ¶
type Integer struct {
Value int64
}
func IntegerObj ¶
IntegerObj returns an *Integer, using the cache for small values.
func (*Integer) Type ¶
func (i *Integer) Type() ObjectType
type InterfaceLiteral ¶
type InterfaceLiteral struct {
Methods map[string]*ast.InterfaceMethod
}
func (*InterfaceLiteral) Inspect ¶
func (il *InterfaceLiteral) Inspect() string
func (*InterfaceLiteral) Type ¶
func (il *InterfaceLiteral) Type() ObjectType
type LazyValue ¶
type LazyValue struct {
Env *Environment
Expr ast.Expression
Evaluated bool
Result Object
Mu sync.Mutex
}
func (*LazyValue) Type ¶
func (lv *LazyValue) Type() ObjectType
type Macro ¶
type Macro struct {
Name string
Parameters []*ast.Identifier
Body *ast.BlockStatement
}
func (*Macro) Type ¶
func (m *Macro) Type() ObjectType
type ModuleCacheEntry ¶
type ModuleContext ¶
type Object ¶
type Object interface {
Type() ObjectType
Inspect() string
}
type ObjectType ¶
type ObjectType int
const ( INTEGER_OBJ ObjectType = iota FLOAT_OBJ BOOLEAN_OBJ STRING_OBJ NULL_OBJ ERROR_OBJ RETURN_VALUE_OBJ BREAK_OBJ CONTINUE_OBJ FUNCTION_OBJ BUILTIN_OBJ ARRAY_OBJ HASH_OBJ DB_OBJ DB_TX_OBJ FUTURE_OBJ INTERFACE_OBJ ADT_TYPE_OBJ ADT_VALUE_OBJ LAZY_OBJ OWNED_OBJ SECRET_OBJ RENDER_ARTIFACT_OBJ FILE_VALUE_OBJ IMAGE_VALUE_OBJ TABLE_VALUE_OBJ MACRO_OBJ )
const ( SERVER_OBJ ObjectType = 100 REQUEST_OBJ ObjectType = 101 RESPONSE_OBJ ObjectType = 102 SSE_WRITER_OBJ ObjectType = 103 QUERY_BUILDER_OBJ ObjectType = 104 LAZY_DB_QUERY_OBJ ObjectType = 105 SIGNAL_OBJ ObjectType = 106 COMPUTED_OBJ ObjectType = 107 EFFECT_OBJ ObjectType = 108 FILE_FINDER_OBJ ObjectType = 109 ROUTE_GROUP_OBJ ObjectType = 110 RULES_SERVICE_OBJ ObjectType = 111 TCPGUARD_BUNDLE_OBJ ObjectType = 112 TCPGUARD_GUARD_OBJ ObjectType = 113 SUPER_BINDING_OBJ ObjectType = 114 )
Extended ObjectType constants defined by other subsystems.
func (ObjectType) String ¶
func (ot ObjectType) String() string
type OwnedValue ¶
func (*OwnedValue) Inspect ¶
func (ov *OwnedValue) Inspect() string
func (*OwnedValue) Type ¶
func (ov *OwnedValue) Type() ObjectType
type RenderArtifact ¶
type RenderArtifact struct {
Kind string
Source string
SourceTyp string
MIME string
Name string
Alt string
Width int64
Height int64
MaxBytes int64
Mode string
}
func (*RenderArtifact) Inspect ¶
func (r *RenderArtifact) Inspect() string
func (*RenderArtifact) Type ¶
func (r *RenderArtifact) Type() ObjectType
type RenderConfig ¶
type RenderConfig struct {
Mode string
TerminalProtocol string
MaxBytes int64
AllowURLs bool
AllowURLHosts []string
}
func DefaultRenderConfig ¶
func DefaultRenderConfig() *RenderConfig
func LoadRenderConfigFromEnv ¶
func LoadRenderConfigFromEnv() *RenderConfig
type ReturnValue ¶
type ReturnValue struct {
Value Object
}
func (*ReturnValue) Inspect ¶
func (rv *ReturnValue) Inspect() string
func (*ReturnValue) Type ¶
func (rv *ReturnValue) Type() ObjectType
type RuntimeLimits ¶
type RuntimeLimits struct {
MaxDepth int
CurrentDepth int
MaxSteps int64
Steps int64
Deadline time.Time
Ctx context.Context
MaxHeapBytes uint64
HeapCheckEvery int64
MaxOutputBytes int64
OutputBytes int64
MaxHTTPBodyBytes int64
MaxExecOutputBytes int64
MaxStringBytes int64
MaxArrayLength int
MaxHashEntries int
MaxImportDepth int
CurrentImportDepth int
MaxImportCount int
ImportCount int
}
func LoadRuntimeLimitsFromEnv ¶
func LoadRuntimeLimitsFromEnv() *RuntimeLimits
LoadRuntimeLimitsFromEnv builds a RuntimeLimits from SPL_MAX_RECURSION, SPL_MAX_STEPS, SPL_EVAL_TIMEOUT_MS, and SPL_MAX_HEAP_MB env vars. Returns nil when none are set.
func (*RuntimeLimits) CloneForConcurrentExecution ¶
func (r *RuntimeLimits) CloneForConcurrentExecution() *RuntimeLimits
CloneForConcurrentExecution returns an independent set of runtime counters with the same configured limits, deadline, and cancellation context. Runtime counters such as recursion depth and evaluation steps describe one execution flow and must not be shared by background or scheduled goroutines.
type Secret ¶
type Secret struct {
Value string
}
func (*Secret) Type ¶
func (s *Secret) Type() ObjectType
type SecurityPolicy ¶
type SecurityPolicy struct {
StrictMode bool
ProtectHost bool
AllowEnvWrite bool
AllowedCapabilities []string
DeniedCapabilities []string
AllowedExecCommands []string
DeniedExecCommands []string
AllowedNetworkHosts []string
DeniedNetworkHosts []string
AllowedDBDrivers []string
DeniedDBDrivers []string
AllowedFileReadPaths []string
DeniedFileReadPaths []string
AllowedFileWritePaths []string
DeniedFileWritePaths []string
AllowedDBDSNPatterns []string
DeniedDBDSNPatterns []string
AllowedImportPaths []string
DeniedImportPaths []string
AllowedImportPackages []string
DeniedImportPackages []string
AllowedNativeModules []string
DeniedNativeModules []string
DenyDynamicImports bool
// BlockHardcodedSecrets, when true, rejects scripts whose source text
// looks like it embeds a hardcoded secret (API key, private key, token,
// ...) before parsing/eval. Detection itself is supplied by an optional
// plugin (see security.RegisterSecretScanner, e.g. builtins/secretr) -
// with no scanner registered this is a no-op even when set.
BlockHardcodedSecrets bool
}
type Stream ¶
type Stream struct {
Elements []Object
}
func (*Stream) Type ¶
func (s *Stream) Type() ObjectType
type String ¶
type String struct {
Value string
}
func (*String) Type ¶
func (s *String) Type() ObjectType
type SuperBinding ¶
type SuperBinding struct {
ParentClass *ClassObject
Instance *ClassInstance
// Call implements the bare `super(...)` form.
Call func(callerEnv *Environment, args ...Object) Object
}
SuperBinding is the value bound to the `super` identifier inside a class constructor or method body. It supports both call forms the language documents (docs/features/09-classes-and-interfaces.md): a bare `super(...)` call, which invokes the parent class's same-named method (or `init`, for a constructor) via Call, and a dot-dispatched `super.name(...)` call, which invokes any named method on ParentClass — see pkg/eval.evalDotExpression's SuperBinding case and pkg/eval.ApplyFunction's SuperBinding case for how each form is evaluated.
func (*SuperBinding) Inspect ¶
func (s *SuperBinding) Inspect() string
func (*SuperBinding) Type ¶
func (s *SuperBinding) Type() ObjectType
type TableValue ¶
type TableValue struct {
Name string
Path string
MIME string
SourceType string
Columns []string
Rows []map[string]Object
}
func (*TableValue) Inspect ¶
func (t *TableValue) Inspect() string
func (*TableValue) Type ¶
func (t *TableValue) Type() ObjectType