Documentation
¶
Overview ¶
Package quickjs Go bindings to QuickJS: a fast, small, and embeddable ES2020 JavaScript interpreter
Example ¶
// Create a new runtime rt := quickjs.NewRuntime( quickjs.WithExecuteTimeout(30), quickjs.WithMemoryLimit(128*1024), quickjs.WithGCThreshold(256*1024), quickjs.WithMaxStackSize(65534), quickjs.WithCanBlock(true), ) defer rt.Close() // Create a new context ctx := rt.NewContext() defer ctx.Close() // Create a new object test := ctx.Object() defer test.Free() // bind properties to the object test.Set("A", test.Context().String("String A")) test.Set("B", ctx.Int32(0)) test.Set("C", ctx.Bool(false)) // bind go function to js object test.Set("hello", ctx.Function(func(ctx *quickjs.Context, this quickjs.Value, args []quickjs.Value) quickjs.Value { return ctx.String("Hello " + args[0].String()) })) // bind "test" object to global object ctx.Globals().Set("test", test) // call js function by js js_ret, _ := ctx.Eval(`test.hello("Javascript!")`) fmt.Println(js_ret.String()) // call js function by go go_ret := ctx.Globals().Get("test").Call("hello", ctx.String("Golang!")) fmt.Println(go_ret.String()) //bind go function to Javascript async function ctx.Globals().Set("testAsync", ctx.AsyncFunction(func(ctx *quickjs.Context, this quickjs.Value, promise quickjs.Value, args []quickjs.Value) quickjs.Value { return promise.Call("resolve", ctx.String("Hello Async Function!")) })) ret, _ := ctx.Eval(` var ret; testAsync().then(v => ret = v) `) defer ret.Free() // wait for promise resolve ctx.Loop() asyncRet, _ := ctx.Eval("ret") defer asyncRet.Free() fmt.Println(asyncRet.String())
Output: Hello Javascript! Hello Golang! Hello Async Function!
Index ¶
- type Array
- func (a Array) Delete(index int64) (bool, error)
- func (a Array) Free()
- func (a Array) Get(index int64) (Value, error)
- func (a Array) HasIdx(i int64) bool
- func (a Array) Len() int64
- func (a Array) Push(elements ...Value) int64
- func (a Array) Set(index int64, value Value) error
- func (a Array) ToValue() Value
- type Atom
- type Context
- func (ctx *Context) Array() *Array
- func (ctx *Context) ArrayBuffer(binaryData []byte) Value
- func (ctx *Context) AsyncFunction(asyncFn func(ctx *Context, this Value, promise Value, args []Value) Value) Value
- func (ctx *Context) Atom(v string) Atom
- func (ctx *Context) AtomIdx(idx int64) Atom
- func (ctx *Context) Await(v Value) (Value, error)
- func (ctx *Context) BigInt64(v int64) Value
- func (ctx *Context) BigUint64(v uint64) Value
- func (ctx *Context) Bool(b bool) Value
- func (ctx *Context) Close()
- func (ctx *Context) Compile(code string, opts ...EvalOption) ([]byte, error)
- func (ctx *Context) CompileFile(filePath string, opts ...EvalOption) ([]byte, error)
- func (ctx *Context) Error(err error) Value
- func (ctx *Context) Eval(code string, opts ...EvalOption) (Value, error)
- func (ctx *Context) EvalBytecode(buf []byte) (Value, error)
- func (ctx *Context) EvalFile(filePath string, opts ...EvalOption) (Value, error)
- func (ctx *Context) Exception() error
- func (ctx *Context) Float64(v float64) Value
- func (ctx *Context) Function(fn func(ctx *Context, this Value, args []Value) Value) Value
- func (ctx *Context) Globals() Value
- func (ctx *Context) Int32(v int32) Value
- func (ctx *Context) Int64(v int64) Value
- func (ctx *Context) Invoke(fn Value, this Value, args ...Value) Value
- func (ctx *Context) LoadModule(code string, moduleName string) (Value, error)
- func (ctx *Context) LoadModuleBytecode(buf []byte, moduleName string) (Value, error)
- func (ctx *Context) LoadModuleFile(filePath string, moduleName string) (Value, error)
- func (ctx *Context) Loop()
- func (ctx *Context) Map() *Map
- func (ctx *Context) Null() Value
- func (ctx *Context) Object() Value
- func (ctx *Context) ParseJSON(v string) Value
- func (ctx *Context) Runtime() *Runtime
- func (ctx *Context) Set() *Set
- func (ctx *Context) SetInterruptHandler(handler InterruptHandler)
- func (ctx *Context) String(v string) Value
- func (ctx *Context) Throw(v Value) Value
- func (ctx *Context) ThrowError(err error) Value
- func (ctx *Context) ThrowInternalError(format string, args ...interface{}) Value
- func (ctx *Context) ThrowRangeError(format string, args ...interface{}) Value
- func (ctx *Context) ThrowReferenceError(format string, args ...interface{}) Value
- func (ctx *Context) ThrowSyntaxError(format string, args ...interface{}) Value
- func (ctx *Context) ThrowTypeError(format string, args ...interface{}) Value
- func (ctx *Context) Uint32(v uint32) Value
- func (ctx *Context) Undefined() Value
- func (ctx *Context) Uninitialized() Value
- type Error
- type EvalOption
- func EvalAwait(await bool) EvalOption
- func EvalFileName(filename string) EvalOption
- func EvalFlagCompileOnly(compileOnly bool) EvalOption
- func EvalFlagGlobal(global bool) EvalOption
- func EvalFlagModule(module bool) EvalOption
- func EvalFlagStrict(strict bool) EvalOption
- func EvalFlagStrip(strip bool) EvalOption
- type EvalOptions
- type InterruptHandler
- type Map
- func (m Map) Call(funcName string, values []Value) Value
- func (m Map) Delete(key Value)
- func (m Map) ForEach(forFn func(key Value, value Value))
- func (m Map) Free()
- func (m Map) Get(key Value) Value
- func (m Map) Has(key Value) bool
- func (m Map) Put(key Value, value Value)
- func (m Map) ToValue() Value
- type Option
- type Options
- type Runtime
- func (r Runtime) Close()
- func (r Runtime) NewContext() *Context
- func (r Runtime) RunGC()
- func (r Runtime) SetCanBlock(canBlock bool)
- func (r Runtime) SetExecuteTimeout(timeout uint64)
- func (r Runtime) SetGCThreshold(threshold uint64)
- func (r Runtime) SetMaxStackSize(stack_size uint64)
- func (r Runtime) SetMemoryLimit(limit uint64)
- type Set
- type Value
- func (v Value) BigFloat() *big.Float
- func (v Value) BigInt() *big.Int
- func (v Value) Bool() bool
- func (v Value) ByteLen() int64
- func (v Value) Call(fname string, args ...Value) Value
- func (v Value) Context() *Context
- func (v Value) Delete(name string) bool
- func (v Value) DeleteIdx(idx int64) bool
- func (v Value) Error() error
- func (v Value) Float64() float64
- func (v Value) Free()
- func (v Value) Get(name string) Value
- func (v Value) GetIdx(idx int64) Value
- func (v Value) Has(name string) bool
- func (v Value) HasIdx(idx int64) bool
- func (v Value) Int32() int32
- func (v Value) Int64() int64
- func (v Value) IsArray() bool
- func (v Value) IsBigDecimal() bool
- func (v Value) IsBigFloat() bool
- func (v Value) IsBigInt() bool
- func (v Value) IsBool() bool
- func (v Value) IsByteArray() bool
- func (v Value) IsError() bool
- func (v Value) IsException() bool
- func (v Value) IsFunction() bool
- func (v Value) IsMap() bool
- func (v Value) IsNull() bool
- func (v Value) IsNumber() bool
- func (v Value) IsObject() bool
- func (v Value) IsPromise() bool
- func (v Value) IsSet() bool
- func (v Value) IsString() bool
- func (v Value) IsSymbol() bool
- func (v Value) IsUndefined() bool
- func (v Value) IsUninitialized() bool
- func (v Value) JSONStringify() string
- func (v Value) Len() int64
- func (v Value) PropertyNames() ([]string, error)
- func (v Value) Set(name string, val Value)
- func (v Value) SetIdx(idx int64, val Value)
- func (v Value) String() string
- func (v Value) ToArray() *Array
- func (v Value) ToByteArray(size uint) ([]byte, error)
- func (v Value) ToMap() *Map
- func (v Value) ToSet() *Set
- func (v Value) Uint32() uint32
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Array ¶
type Array struct {
// contains filtered or unexported fields
}
func NewQjsArray ¶
func (Array) Get ¶
Get
@Description: get the specific value by subscript @receiver a : @param index : @return Value
func (Array) HasIdx ¶
HasIdx
@Description: Determine whether there is data at the current subscript position @receiver a : @param i : @return bool
func (Array) Push ¶
Push
@Description: add one or more elements after the array,returns the new array length @receiver a : @param elements : @return int64
type Atom ¶
type Atom struct {
// contains filtered or unexported fields
}
Object property names and some strings are stored as Atoms (unique strings) to save memory and allow fast comparison. Atoms are represented as a 32 bit integer. Half of the atom range is reserved for immediate integer literals from 0 to 2^{31}-1.
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context represents a Javascript context (or Realm). Each JSContext has its own global objects and system objects. There can be several JSContexts per JSRuntime and they can share objects, similar to frames of the same origin sharing Javascript objects in a web browser.
func (*Context) ArrayBuffer ¶
ArrayBuffer returns a string value with given binary data.
func (*Context) AsyncFunction ¶
func (ctx *Context) AsyncFunction(asyncFn func(ctx *Context, this Value, promise Value, args []Value) Value) Value
AsyncFunction returns a js async function value with given function template.
func (*Context) Await ¶
Wait for a promise and execute pending jobs while waiting for it. Return the promise result or JS_EXCEPTION in case of promise rejection.
func (*Context) Close ¶
func (ctx *Context) Close()
Free will free context and all associated objects.
func (*Context) Compile ¶
func (ctx *Context) Compile(code string, opts ...EvalOption) ([]byte, error)
Compile returns a compiled bytecode with given code.
func (*Context) CompileFile ¶
func (ctx *Context) CompileFile(filePath string, opts ...EvalOption) ([]byte, error)
Compile returns a compiled bytecode with given filename.
func (*Context) Eval ¶
func (ctx *Context) Eval(code string, opts ...EvalOption) (Value, error)
Eval returns a js value with given code. Need call Free() `quickjs.Value`'s returned by `Eval()` and `EvalFile()` and `EvalBytecode()`. func (ctx *Context) Eval(code string) (Value, error) { return ctx.EvalFile(code, "code") }
func (*Context) EvalBytecode ¶
EvalBytecode returns a js value with given bytecode. Need call Free() `quickjs.Value`'s returned by `Eval()` and `EvalFile()` and `EvalBytecode()`.
func (*Context) EvalFile ¶
func (ctx *Context) EvalFile(filePath string, opts ...EvalOption) (Value, error)
EvalFile returns a js value with given code and filename. Need call Free() `quickjs.Value`'s returned by `Eval()` and `EvalFile()` and `EvalBytecode()`.
func (*Context) LoadModule ¶
LoadModule returns a js value with given code and module name.
func (*Context) LoadModuleBytecode ¶
LoadModuleByteCode returns a js value with given bytecode and module name.
func (*Context) LoadModuleFile ¶
LoadModuleFile returns a js value with given file path and module name.
func (*Context) SetInterruptHandler ¶
func (ctx *Context) SetInterruptHandler(handler InterruptHandler)
SetInterruptHandler sets a interrupt handler.
func (*Context) ThrowError ¶
ThrowError returns a context's exception value with given error message.
func (*Context) ThrowInternalError ¶
ThrowInternalError returns a context's exception value with given error message.
func (*Context) ThrowRangeError ¶
ThrowRangeError returns a context's exception value with given error message.
func (*Context) ThrowReferenceError ¶
ThrowReferenceError returns a context's exception value with given error message.
func (*Context) ThrowSyntaxError ¶
ThrowSyntaxError returns a context's exception value with given error message.
func (*Context) ThrowTypeError ¶
ThrowTypeError returns a context's exception value with given error message.
func (*Context) Uninitialized ¶
Uninitialized returns a uninitialized value.
type EvalOption ¶
type EvalOption func(*EvalOptions)
func EvalAwait ¶
func EvalAwait(await bool) EvalOption
func EvalFileName ¶
func EvalFileName(filename string) EvalOption
func EvalFlagCompileOnly ¶
func EvalFlagCompileOnly(compileOnly bool) EvalOption
func EvalFlagGlobal ¶
func EvalFlagGlobal(global bool) EvalOption
func EvalFlagModule ¶
func EvalFlagModule(module bool) EvalOption
func EvalFlagStrict ¶
func EvalFlagStrict(strict bool) EvalOption
func EvalFlagStrip ¶
func EvalFlagStrip(strip bool) EvalOption
type EvalOptions ¶
type EvalOptions struct {
// contains filtered or unexported fields
}
type InterruptHandler ¶
type InterruptHandler func() int
InterruptHandler is a function type for interrupt handler.
return != 0 if the JS code needs to be interrupted
type Map ¶
type Map struct {
// contains filtered or unexported fields
}
func (Map) Call ¶
Call
@Description: call some internal methods of js @receiver a : @param funcName : @param values : @return Value
func (Map) Delete ¶
Delete
@Description:delete the value of an element by key @receiver m : @param key :
type Option ¶
type Option func(*Options)
func WithCanBlock ¶
WithCanBlock will set the runtime's can block; default is true
func WithExecuteTimeout ¶
WithExecuteTimeout will set the runtime's execute timeout; default is 0
func WithGCThreshold ¶
WithGCThreshold will set the runtime's GC threshold; use -1 to disable automatic GC.
func WithMaxStackSize ¶
WithMaxStackSize will set max runtime's stack size; default is 255
func WithMemoryLimit ¶
WithMemoryLimit will set the runtime memory limit; if not set, it will be unlimit.
func WithModuleImport ¶
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime represents a Javascript runtime corresponding to an object heap. Several runtimes can exist at the same time but they cannot exchange objects. Inside a given runtime, no multi-threading is supported.
func (Runtime) NewContext ¶
NewContext creates a new JavaScript context. enable BigFloat/BigDecimal support and enable . enable operator overloading.
func (Runtime) SetCanBlock ¶
SetCanBlock will set the runtime's can block; default is true
func (Runtime) SetExecuteTimeout ¶
SetExecuteTimeout will set the runtime's execute timeout; default is 0
func (Runtime) SetGCThreshold ¶
SetGCThreshold the runtime's GC threshold; use -1 to disable automatic GC.
func (Runtime) SetMaxStackSize ¶
SetMaxStackSize will set max runtime's stack size; default is 255
func (Runtime) SetMemoryLimit ¶
SetMemoryLimit the runtime memory limit; if not set, it will be unlimit.
type Set ¶
type Set struct {
// contains filtered or unexported fields
}
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
JSValue represents a Javascript value which can be a primitive type or an object. Reference counting is used, so it is important to explicitly duplicate (JS_DupValue(), increment the reference count) or free (JS_FreeValue(), decrement the reference count) JSValues.
func (Value) IsBigDecimal ¶
func (Value) IsBigFloat ¶
func (Value) IsByteArray ¶
IsByteArray return true if the value is array buffer
func (Value) IsException ¶
func (Value) IsFunction ¶
func (Value) IsUndefined ¶
func (Value) IsUninitialized ¶
func (Value) JSONStringify ¶
JSONString returns the JSON string representation of the value.
func (Value) PropertyNames ¶
PropertyNames returns the names of the properties of the value.