Documentation
¶
Index ¶
- Constants
- Variables
- func ApplyFunctionGIL(ctx context.Context, fn object.Object, args []object.Object, ...) object.Object
- func ContextWithCallDepth(ctx context.Context, maxDepth int) context.Context
- func ContextWithSourceFile(ctx context.Context, filename string) context.Context
- func EnsureCallDepth(ctx context.Context) context.Context
- func Eval(node ast.Node, env *object.Environment) object.Object
- func EvalWithContext(ctx context.Context, node ast.Node, env *object.Environment) object.Object
- func GetEnvFromContext(ctx context.Context) *object.Environment
- func GetImportBuiltin() *object.Builtin
- func GetSourceFileFromContext(ctx context.Context) string
- func SetCallDepthInContext(ctx context.Context, cd *CallDepth) context.Context
- func SetEnvInContext(ctx context.Context, env *object.Environment) context.Context
- func TrackResource(ctx context.Context, owner any, close func()) (release func())
- func WithEvaluator(ctx context.Context) context.Context
- type CallDepth
Constants ¶
const DefaultMaxCallDepth = 1000
DefaultMaxCallDepth is the default maximum call depth (1000)
Variables ¶
var ( NULL = &object.Null{} TRUE = object.NewBoolean(true) FALSE = object.NewBoolean(false) )
var BytesBuiltin = &object.Builtin{ Fn: bytesConstructorFn, HelpText: `bytes(source="", encoding="utf-8") - Construct a Bytes value Returns an immutable Bytes object holding the given binary data. Bytes is the canonical binary type in Scriptling and is produced by hashlib.digest(), hmac.digest(), base64.b64decode(), and msgpack.packb(). Parameters: source: A string (encoded as UTF-8), a list/tuple of ints (0-255), an existing Bytes value, or nothing (empty bytes). encoding (str, optional): Encoding to use when source is a string. Only "utf-8" is supported. Default: "utf-8". Returns: bytes: a Bytes object. Example: b = bytes("hi") # b'hi' b = bytes([104, 105]) # b'hi' b = bytes() # b'' s = b.decode() # "hi" b = bytes.fromhex("6869") # b'hi'`, Attributes: map[string]object.Object{ "fromhex": &object.Builtin{ Fn: func(ctx context.Context, kwargs object.Kwargs, args ...object.Object) object.Object { if err := errors.ExactArgs(args, 1); err != nil { return err } s, err := args[0].AsString() if err != nil { return err } decoded, decodeErr := hex.DecodeString(s) if decodeErr != nil { return errors.NewError("bytes.fromhex: %s", decodeErr.Error()) } return object.NewBytes(decoded) }, HelpText: `bytes.fromhex(hex_string) - Build Bytes from a hex string Returns a Bytes value whose contents are the decoded hex. Example: b = bytes.fromhex("6869") # b'hi'`, }, "frombase64": &object.Builtin{ Fn: func(ctx context.Context, kwargs object.Kwargs, args ...object.Object) object.Object { if err := errors.ExactArgs(args, 1); err != nil { return err } s, err := args[0].AsString() if err != nil { return err } decoded, decodeErr := base64.StdEncoding.DecodeString(s) if decodeErr != nil { return errors.NewError("bytes.frombase64: %s", decodeErr.Error()) } return object.NewBytes(decoded) }, HelpText: `bytes.frombase64(b64_string) - Build Bytes from a Base64 string Returns a Bytes value whose contents are the decoded Base64 input. Example: b = bytes.frombase64("aGk=") # b'hi'`, }, }, }
BytesBuiltin is the global bytes builtin. Calling bytes(...) invokes the constructor; bytes.fromhex(...) and bytes.frombase64(...) go through the Attributes map.
var SentinelBuiltin = &object.Builtin{
Fn: sentinelConstructorFn,
HelpText: `sentinel(name, *, repr=None) - Create a unique sentinel value
Returns a new object that is equal only to itself, for use as a "value was
not supplied" marker that cannot collide with real data:
MISSING = sentinel("MISSING")
def fetch(key, default=MISSING):
if default is MISSING:
...
Parameters:
name (str): The sentinel's name, used for repr() and the __name__ attribute.
repr (str, optional): Overrides the repr() output; defaults to the name.
Each call returns a new, distinct sentinel. Sentinels are truthy, are not
callable, have no ordering comparisons, and can be stored in sets. Check them
with the is operator (== is true only against the same sentinel).`,
}
SentinelBuiltin is the global sentinel builtin (PEP 661, Python 3.15).
Functions ¶
func ApplyFunctionGIL ¶ added in v0.15.0
func ApplyFunctionGIL(ctx context.Context, fn object.Object, args []object.Object, keywords map[string]object.Object, env *object.Environment) object.Object
applyFunction calls a function object with arguments and keyword arguments.
It is unexported because it does NOT acquire the interpreter lock: it is the internal dispatch used while the lock is already held (dunder-method dispatch, recursion, etc.). The locking boundaries are EvalWithContext, ApplyFunctionGIL, and the evaliface adapter (CallFunction/CallObjectFunction/CallMethod). Go callers outside the evaluator package must use ApplyFunctionGIL.
ApplyFunctionGIL acquires the environment's interpreter lock (reentrant via goroutine-id ownership, so nested calls from the same goroutine don't deadlock) and then dispatches via applyFunction. Host code that calls script functions — especially concurrently against a shared environment — must use this rather than the unexported applyFunction, which assumes the lock is held.
func ContextWithCallDepth ¶
ContextWithCallDepth creates a context with a call depth tracker
func ContextWithSourceFile ¶
ContextWithSourceFile creates a context with source file info for error reporting
func EnsureCallDepth ¶ added in v0.31.0
EnsureCallDepth returns ctx with a call-depth tracker, adding one with the default depth when ctx has none. Hosts that call script functions directly use it so the recursion limit applies as it does to a full evaluation.
func EvalWithContext ¶
EvalWithContext executes with context for timeout/cancellation
func GetEnvFromContext ¶
func GetEnvFromContext(ctx context.Context) *object.Environment
GetEnvFromContext retrieves environment from context for external functions
func GetImportBuiltin ¶
func GetSourceFileFromContext ¶
GetSourceFileFromContext retrieves source file name from context
func SetCallDepthInContext ¶
SetCallDepthInContext stores call depth tracker in context
func SetEnvInContext ¶
SetEnvInContext stores environment in context for builtin functions.
Every builtin call goes through here, and context.WithValue allocates, so the result is memoised on the environment: the base context is stable for the duration of an evaluation, so the same derived context can be handed out repeatedly instead of rebuilt per call.
func TrackResource ¶ added in v0.38.0
TrackResource registers something a library opened for the script running in ctx (a client, a connection, a child process, a file handle) so it does not outlive the script's use of it: close runs when the interpreter is reset or closed, and once owner, the object the script holds, is garbage collected. The library calls release when the script closes it itself.
close must be safe to call more than once and from any goroutine, and neither it nor release may hold on to owner, or owner could never be collected. owner may be nil: then only the interpreter closes it.
Types ¶
type CallDepth ¶
type CallDepth struct {
// contains filtered or unexported fields
}
CallDepth tracks function call depth to prevent stack overflow
func GetCallDepthFromContext ¶
GetCallDepthFromContext retrieves call depth tracker from context
func NewCallDepth ¶
NewCallDepth creates a new CallDepth tracker with the specified max depth
func (*CallDepth) LimitError ¶ added in v0.31.0
LimitError returns the error for a failed Enter, and undoes its depth increment, since the call does not happen.
Source Files