Documentation ¶
Index ¶
- Variables
- func IsInfinity(v Value) bool
- func IsNaN(v Value) bool
- func IsNull(v Value) bool
- func IsUndefined(v Value) bool
- type ArrayBuffer
- type Callable
- type CompilerError
- type CompilerReferenceError
- type CompilerSyntaxError
- type ConstructorCall
- type Exception
- type FieldNameMapper
- type Flag
- type FunctionCall
- type InterruptedError
- type JsonEncodable
- type Now
- type Object
- func (o *Object) ClassName() string
- func (o *Object) DefineAccessorProperty(name string, getter, setter Value, configurable, enumerable Flag) error
- func (o *Object) DefineDataProperty(name string, value Value, writable, configurable, enumerable Flag) error
- func (o *Object) Equals(other Value) bool
- func (o *Object) Export() interface{}
- func (o *Object) ExportType() reflect.Type
- func (o *Object) Get(name string) Value
- func (o *Object) Keys() (keys []string)
- func (o *Object) MarshalJSON() ([]byte, error)
- func (o *Object) SameAs(other Value) bool
- func (o *Object) Set(name string, value interface{}) error
- func (o *Object) StrictEquals(other Value) bool
- func (o *Object) String() string
- func (o *Object) ToBoolean() bool
- func (o *Object) ToFloat() float64
- func (o *Object) ToInteger() int64
- func (o *Object) ToNumber() Value
- func (o *Object) ToObject(*Runtime) *Object
- func (o *Object) ToString() Value
- type Position
- type Program
- type PropertyDescriptor
- type Proxy
- type ProxyTrapConfig
- type RandSource
- type Runtime
- func (r *Runtime) CaptureCallStack(depth int, stack []StackFrame) []StackFrame
- func (r *Runtime) ClearInterrupt()
- func (r *Runtime) CreateObject(proto *Object) *Object
- func (r *Runtime) ExportTo(v Value, target interface{}) error
- func (r *Runtime) Get(name string) Value
- func (r *Runtime) GlobalObject() *Object
- func (r *Runtime) Interrupt(v interface{})
- func (r *Runtime) New(construct Value, args ...Value) (o *Object, err error)
- func (r *Runtime) NewArrayBuffer(data []byte) ArrayBuffer
- func (r *Runtime) NewGoError(err error) *Object
- func (r *Runtime) NewObject() (v *Object)
- func (r *Runtime) NewProxy(target *Object, nativeHandler *ProxyTrapConfig) Proxy
- func (r *Runtime) NewTypeError(args ...interface{}) *Object
- func (r *Runtime) RunProgram(p *Program) (result Value, err error)
- func (r *Runtime) RunScript(name, src string) (Value, error)
- func (r *Runtime) RunString(str string) (Value, error)
- func (r *Runtime) Set(name string, value interface{})
- func (r *Runtime) SetFieldNameMapper(mapper FieldNameMapper)
- func (r *Runtime) SetRandSource(source RandSource)
- func (r *Runtime) SetTimeSource(now Now)
- func (r *Runtime) ToValue(i interface{}) Value
- type SrcFile
- type StackFrame
- type Value
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var (
InvalidRuneError = errors.New("invalid rune")
)
Functions ¶
func IsInfinity ¶
IsInfinity returns true if the supplied is (+/-)Infinity
func IsUndefined ¶
IsUndefined returns true if the supplied Value is undefined. Note, it checks against the real undefined, not against the global object's 'undefined' property.
Types ¶
type ArrayBuffer ¶
type ArrayBuffer struct {
// contains filtered or unexported fields
}
ArrayBuffer is a Go wrapper around ECMAScript ArrayBuffer. Calling Runtime.ToValue() on it returns the underlying ArrayBuffer. Calling Export() on an ECMAScript ArrayBuffer returns a wrapper. Use Runtime.NewArrayBuffer([]byte) to create one.
func (ArrayBuffer) Bytes ¶
func (a ArrayBuffer) Bytes() []byte
Bytes returns the underlying []byte for this ArrayBuffer. For detached ArrayBuffers returns nil.
func (ArrayBuffer) Detach ¶
func (a ArrayBuffer) Detach() bool
Detach the ArrayBuffer. After this, the underlying []byte becomes unreferenced and any attempt to use this ArrayBuffer results in a TypeError. Returns false if it was already detached, true otherwise. Note, this method may only be called from the goroutine that 'owns' the Runtime, it may not be called concurrently.
func (ArrayBuffer) Detached ¶
func (a ArrayBuffer) Detached() bool
Detached returns true if the ArrayBuffer is detached.
type Callable ¶
Callable represents a JavaScript function that can be called from Go.
func AssertFunction ¶
AssertFunction checks if the Value is a function and returns a Callable.
Example ¶
vm := New() _, err := vm.RunString(` function sum(a, b) { return a+b; } `) if err != nil { panic(err) } sum, ok := AssertFunction(vm.Get("sum")) if !ok { panic("Not a function") } res, err := sum(Undefined(), vm.ToValue(40), vm.ToValue(2)) if err != nil { panic(err) } fmt.Println(res)
Output: 42
type CompilerError ¶
type CompilerReferenceError ¶
type CompilerReferenceError struct {
CompilerError
}
func (*CompilerReferenceError) Error ¶
func (e *CompilerReferenceError) Error() string
type CompilerSyntaxError ¶
type CompilerSyntaxError struct {
CompilerError
}
func (*CompilerSyntaxError) Error ¶
func (e *CompilerSyntaxError) Error() string
type ConstructorCall ¶
func (ConstructorCall) Argument ¶
func (f ConstructorCall) Argument(idx int) Value
type FieldNameMapper ¶
type FieldNameMapper interface { // FieldName returns a JavaScript name for the given struct field in the given type. // If this method returns "" the field becomes hidden. FieldName(t reflect.Type, f reflect.StructField) string // MethodName returns a JavaScript name for the given method in the given type. // If this method returns "" the method becomes hidden. MethodName(t reflect.Type, m reflect.Method) string }
FieldNameMapper provides custom mapping between Go and JavaScript property names.
A FieldNameMapper may optionally have a SkipValue method for advanced mapping that depend on the actual value:
// SkipValue returns a function that allows custom values (typically zero values) to be skipped SkipValue(t reflect.Type, f reflect.StructField) func(reflect.Value) bool
func TagFieldNameMapper ¶
func TagFieldNameMapper(tagName string, uncapMethods bool) FieldNameMapper
TagFieldNameMapper returns a FieldNameMapper that uses the given tagName for struct fields and optionally uncapitalises (making the first letter lower case) method names. The common tag value syntax is supported (name[,options]), however options are ignored. Setting name to anything other than a valid ECMAScript identifier makes the field hidden.
Example ¶
vm := New() vm.SetFieldNameMapper(TagFieldNameMapper("json", true)) type S struct { Field int `json:"field"` } vm.Set("s", S{Field: 42}) res, _ := vm.RunString(`s.field`) fmt.Println(res.Export())
Output: 42
func UncapFieldNameMapper ¶
func UncapFieldNameMapper() FieldNameMapper
UncapFieldNameMapper returns a FieldNameMapper that uncapitalises struct field and method names making the first letter lower case.
Example ¶
vm := New() s := testGoReflectMethod_O{ Test: "passed", } vm.SetFieldNameMapper(UncapFieldNameMapper()) vm.Set("s", s) res, _ := vm.RunString(`s.test + " and " + s.method("passed too")`) fmt.Println(res.Export())
Output: passed and passed too
type FunctionCall ¶
func (FunctionCall) Argument ¶
func (f FunctionCall) Argument(idx int) Value
type InterruptedError ¶
type InterruptedError struct { Exception // contains filtered or unexported fields }
func (*InterruptedError) Error ¶
func (e *InterruptedError) Error() string
func (*InterruptedError) String ¶
func (e *InterruptedError) String() string
func (*InterruptedError) Value ¶
func (e *InterruptedError) Value() interface{}
type JsonEncodable ¶
type JsonEncodable interface {
JsonEncodable() interface{}
}
JsonEncodable allows custom JSON encoding by JSON.stringify() Note that if the returned value itself also implements JsonEncodable, it won't have any effect.
type Object ¶
type Object struct {
// contains filtered or unexported fields
}
func (*Object) DefineAccessorProperty ¶
func (o *Object) DefineAccessorProperty(name string, getter, setter Value, configurable, enumerable Flag) error
DefineAccessorProperty is a Go equivalent of Object.defineProperty(o, name, {get: getter, set: setter, configurable: configurable, enumerable: enumerable})
func (*Object) DefineDataProperty ¶
func (o *Object) DefineDataProperty(name string, value Value, writable, configurable, enumerable Flag) error
DefineDataProperty is a Go equivalent of Object.defineProperty(o, name, {value: value, writable: writable, configurable: configurable, enumerable: enumerable})
func (*Object) ExportType ¶
func (*Object) MarshalJSON ¶
MarshalJSON returns JSON representation of the Object. It is equivalent to JSON.stringify(o). Note, this implements json.Marshaler so that json.Marshal() can be used without the need to Export().
func (*Object) StrictEquals ¶
type Program ¶
type Program struct {
// contains filtered or unexported fields
}
func Compile ¶
Compile creates an internal representation of the JavaScript code that can be later run using the Runtime.RunProgram() method. This representation is not linked to a runtime in any way and can be run in multiple runtimes (possibly at the same time).
func CompileAST ¶
CompileAST creates an internal representation of the JavaScript code that can be later run using the Runtime.RunProgram() method. This representation is not linked to a runtime in any way and can be run in multiple runtimes (possibly at the same time).
func MustCompile ¶
MustCompile is like Compile but panics if the code cannot be compiled. It simplifies safe initialization of global variables holding compiled JavaScript code.
type PropertyDescriptor ¶
type PropertyDescriptor struct { Value Value Writable, Configurable, Enumerable Flag Getter, Setter Value // contains filtered or unexported fields }
func (*PropertyDescriptor) Empty ¶
func (p *PropertyDescriptor) Empty() bool
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
Proxy is a Go wrapper around ECMAScript Proxy. Calling Runtime.ToValue() on it returns the underlying Proxy. Calling Export() on an ECMAScript Proxy returns a wrapper. Use Runtime.NewProxy() to create one.
type ProxyTrapConfig ¶
type ProxyTrapConfig struct { // A trap for Object.getPrototypeOf, Reflect.getPrototypeOf, __proto__, Object.prototype.isPrototypeOf, instanceof GetPrototypeOf func(target *Object) (prototype *Object) // A trap for Object.setPrototypeOf, Reflect.setPrototypeOf SetPrototypeOf func(target *Object, prototype *Object) (success bool) // A trap for Object.isExtensible, Reflect.isExtensible IsExtensible func(target *Object) (success bool) // A trap for Object.preventExtensions, Reflect.preventExtensions PreventExtensions func(target *Object) (success bool) // A trap for Object.getOwnPropertyDescriptor, Reflect.getOwnPropertyDescriptor GetOwnPropertyDescriptor func(target *Object, prop string) (propertyDescriptor PropertyDescriptor) // A trap for Object.defineProperty, Reflect.defineProperty DefineProperty func(target *Object, key string, propertyDescriptor PropertyDescriptor) (success bool) // A trap for the in operator, with operator, Reflect.has Has func(target *Object, property string) (available bool) // A trap for getting property values, Reflect.get Get func(target *Object, property string, receiver *Object) (value Value) // A trap for setting property values, Reflect.set Set func(target *Object, property string, value Value, receiver *Object) (success bool) // A trap for the delete operator, Reflect.deleteProperty DeleteProperty func(target *Object, property string) (success bool) // A trap for Object.getOwnPropertyNames, Object.getOwnPropertySymbols, Object.keys, Reflect.ownKeys OwnKeys func(target *Object) (object *Object) // A trap for a function call, Function.prototype.apply, Function.prototype.call, Reflect.apply Apply func(target *Object, this *Object, argumentsList []Value) (value Value) // A trap for the new operator, Reflect.construct Construct func(target *Object, argumentsList []Value, newTarget *Object) (value *Object) }
ProxyTrapConfig provides a simplified Go-friendly API for implementing Proxy traps. Note that the Proxy may not have Symbol properties when using this as a handler because property keys are passed as strings. get() and getOwnPropertyDescriptor() for Symbol properties will always return undefined; has() and deleteProperty() for Symbol properties will always return false; set() and defineProperty() for Symbol properties will throw a TypeError. If you need Symbol properties implement the handler in JavaScript.
type RandSource ¶
type RandSource func() float64
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
func New ¶
func New() *Runtime
New creates an instance of a Javascript runtime that can be used to run code. Multiple instances may be created and used simultaneously, however it is not possible to pass JS values across runtimes.
func (*Runtime) CaptureCallStack ¶
func (r *Runtime) CaptureCallStack(depth int, stack []StackFrame) []StackFrame
CaptureCallStack appends the current call stack frames to the stack slice (which may be nil) up to the specified depth. The most recent frame will be the first one. If depth <= 0 or more than the number of available frames, returns the entire stack.
func (*Runtime) ClearInterrupt ¶
func (r *Runtime) ClearInterrupt()
ClearInterrupt resets the interrupt flag. Typically this needs to be called before the runtime is made available for re-use if there is a chance it could have been interrupted with Interrupt(). Otherwise if Interrupt() was called when runtime was not running (e.g. if it had already finished) so that Interrupt() didn't actually trigger, an attempt to use the runtime will immediately cause an interruption. It is up to the user to ensure proper synchronisation so that ClearInterrupt() is only called when the runtime has finished and there is no chance of a concurrent Interrupt() call.
func (*Runtime) CreateObject ¶
CreateObject creates an object with given prototype. Equivalent of Object.create(proto).
func (*Runtime) ExportTo ¶
ExportTo converts a JavaScript value into the specified Go value. The second parameter must be a non-nil pointer. Exporting to an interface{} results in a value of the same type as Export() would produce. Exporting to numeric types uses the standard ECMAScript conversion operations, same as used when assigning values to non-clamped typed array items, e.g. https://www.ecma-international.org/ecma-262/10.0/index.html#sec-toint32 Returns error if conversion is not possible.
Example (Func) ¶
const SCRIPT = ` function f(param) { return +param + 2; } ` vm := New() _, err := vm.RunString(SCRIPT) if err != nil { panic(err) } var fn func(string) string err = vm.ExportTo(vm.Get("f"), &fn) if err != nil { panic(err) } fmt.Println(fn("40")) // note, _this_ value in the function will be undefined.
Output: 42
Example (FuncThrow) ¶
const SCRIPT = ` function f(param) { throw new Error("testing"); } ` vm := New() _, err := vm.RunString(SCRIPT) if err != nil { panic(err) } var fn func(string) (string, error) err = vm.ExportTo(vm.Get("f"), &fn) if err != nil { panic(err) } _, err = fn("") fmt.Println(err)
Output: Error: testing at f (<eval>:3:9(4))
Example (FuncVariadic) ¶
const SCRIPT = ` function f() { return Array.prototype.join.call(arguments, ","); } ` vm := New() _, err := vm.RunString(SCRIPT) if err != nil { panic(err) } var fn func(args ...interface{}) string err = vm.ExportTo(vm.Get("f"), &fn) if err != nil { panic(err) } fmt.Println(fn("a", "b", 42))
Output: a,b,42
func (*Runtime) GlobalObject ¶
GlobalObject returns the global object.
func (*Runtime) Interrupt ¶
func (r *Runtime) Interrupt(v interface{})
Interrupt a running JavaScript. The corresponding Go call will return an *InterruptedError containing v. Note, it only works while in JavaScript code, it does not interrupt native Go functions (which includes all built-ins). If the runtime is currently not running, it will be immediately interrupted on the next Run*() call. To avoid that use ClearInterrupt()
func (*Runtime) New ¶
New is an equivalent of the 'new' operator allowing to call it directly from Go.
func (*Runtime) NewArrayBuffer ¶
func (r *Runtime) NewArrayBuffer(data []byte) ArrayBuffer
func (*Runtime) NewGoError ¶
func (*Runtime) NewProxy ¶
func (r *Runtime) NewProxy(target *Object, nativeHandler *ProxyTrapConfig) Proxy
func (*Runtime) NewTypeError ¶
func (*Runtime) RunProgram ¶
RunProgram executes a pre-compiled (see Compile()) code in the global context.
func (*Runtime) Set ¶
Set the specified value as a property of the global object. The value is first converted using ToValue()
func (*Runtime) SetFieldNameMapper ¶
func (r *Runtime) SetFieldNameMapper(mapper FieldNameMapper)
SetFieldNameMapper sets a custom field name mapper for Go types. It can be called at any time, however the mapping for any given value is fixed at the point of creation. Setting this to nil restores the default behaviour which is all exported fields and methods are mapped to their original unchanged names.
func (*Runtime) SetRandSource ¶
func (r *Runtime) SetRandSource(source RandSource)
SetRandSource sets random source for this Runtime. If not called, the default math/rand is used.
func (*Runtime) SetTimeSource ¶
SetTimeSource sets the current time source for this Runtime. If not called, the default time.Now() is used.
func (*Runtime) ToValue ¶
ToValue converts a Go value into a JavaScript value of a most appropriate type. Structural types (such as structs, maps and slices) are wrapped so that changes are reflected on the original value which can be retrieved using Value.Export().
Notes on individual types:
Primitive types ¶
Primitive types (numbers, string, bool) are converted to the corresponding JavaScript primitives.
Strings ¶
Because of the difference in internal string representation between ECMAScript (which uses UTF-16) and Go (which uses UTF-8) conversion from JS to Go may be lossy. In particular, code points that can be part of UTF-16 surrogate pairs (0xD800-0xDFFF) cannot be represented in UTF-8 unless they form a valid surrogate pair and are replaced with utf8.RuneError.
Nil ¶
Nil is converted to null.
Functions ¶
func(FunctionCall) Value is treated as a native JavaScript function. This increases performance because there are no automatic argument and return value type conversions (which involves reflect).
Any other Go function is wrapped so that the arguments are automatically converted into the required Go types and the return value is converted to a JavaScript value (using this method). If conversion is not possible, a TypeError is thrown.
Functions with multiple return values return an Array. If the last return value is an `error` it is not returned but converted into a JS exception. If the error is *Exception, it is thrown as is, otherwise it's wrapped in a GoEerror. Note that if there are exactly two return values and the last is an `error`, the function returns the first value as is, not an Array.
Structs ¶
Structs are converted to Object-like values. Fields and methods are available as properties, their values are results of this method (ToValue()) applied to the corresponding Go value.
Field properties are writable (if the struct is addressable) and non-configurable. Method properties are non-writable and non-configurable.
Attempt to define a new property or delete an existing property will fail (throw in strict mode) unless it's a Symbol property. Symbol properties only exist in the wrapper and do not affect the underlying Go value. Note that because a wrapper is created every time a property is accessed it may lead to unexpected results such as this:
type Field struct{ } type S struct { Field *Field } var s = S{ Field: &Field{}, } vm := New() vm.Set("s", &s) res, err := vm.RunString(` var sym = Symbol(66); var field1 = s.Field; field1[sym] = true; var field2 = s.Field; field1 === field2; // true, because the equality operation compares the wrapped values, not the wrappers field1[sym] === true; // true field2[sym] === undefined; // also true `)
The same applies to values from maps and slices as well.
Handling of time.Time ¶
time.Time does not get special treatment and therefore is converted just like any other `struct` providing access to all its methods. This is done deliberately instead of converting it to a `Date` because these two types are not fully compatible: `time.Time` includes zone, whereas JS `Date` doesn't. Doing the conversion implicitly therefore would result in a loss of information.
If you need to convert it to a `Date`, it can be done either in JS:
var d = new Date(goval.UnixNano()/1e6);
... or in Go:
now := time.Now() vm := New() val, err := vm.New(vm.Get("Date").ToObject(vm), vm.ToValue(now.UnixNano()/1e6)) if err != nil { ... } vm.Set("d", val)
Note that Value.Export() for a `Date` value returns time.Time in local timezone.
Maps ¶
Maps with string or integer key type are converted into host objects that largely behave like a JavaScript Object.
Maps with methods ¶
If a map type has at least one method defined, the properties of the resulting Object represent methods, not map keys. This is because in JavaScript there is no distinction between 'object.key` and `object[key]`, unlike Go. If access to the map values is required, it can be achieved by defining another method or, if it's not possible, by defining an external getter function.
Slices ¶
Slices are converted into host objects that behave largely like JavaScript Array. It has the appropriate prototype and all the usual methods should work. There are, however, some caveats:
- If the slice is not addressable, the array cannot be extended or shrunk. Any attempt to do so (by setting an index beyond the current length or by modifying the length) will result in a TypeError.
- Converted Arrays may not contain holes (because Go slices cannot). This means that hasOwnProperty(n) will always return `true` if n < length. Attempt to delete an item with an index < length will fail. Nil slice elements will be converted to `null`. Accessing an element beyond `length` will return `undefined`.
Any other type is converted to a generic reflect based host object. Depending on the underlying type it behaves similar to a Number, String, Boolean or Object.
Note that the underlying type is not lost, calling Export() returns the original Go value. This applies to all reflect based types.
type StackFrame ¶
type StackFrame struct {
// contains filtered or unexported fields
}
func (*StackFrame) FuncName ¶
func (f *StackFrame) FuncName() string
func (*StackFrame) Position ¶
func (f *StackFrame) Position() Position
func (*StackFrame) SrcName ¶
func (f *StackFrame) SrcName() string
func (*StackFrame) Write ¶
func (f *StackFrame) Write(b *bytes.Buffer)
type Value ¶
type Value interface { ToInteger() int64 ToString() Value String() string ToFloat() float64 ToNumber() Value ToBoolean() bool ToObject(*Runtime) *Object SameAs(Value) bool Equals(Value) bool StrictEquals(Value) bool Export() interface{} ExportType() reflect.Type // contains filtered or unexported methods }
Source Files ¶
- array.go
- array_sparse.go
- builtin_array.go
- builtin_boolean.go
- builtin_date.go
- builtin_error.go
- builtin_function.go
- builtin_global.go
- builtin_json.go
- builtin_map.go
- builtin_math.go
- builtin_number.go
- builtin_object.go
- builtin_proxy.go
- builtin_reflect.go
- builtin_regexp.go
- builtin_set.go
- builtin_string.go
- builtin_symbol.go
- builtin_typedarrays.go
- builtin_weakmap.go
- builtin_weakset.go
- compiler.go
- compiler_expr.go
- compiler_stmt.go
- date.go
- date_parser.go
- func.go
- ipow.go
- map.go
- object.go
- object_args.go
- object_gomap.go
- object_gomap_reflect.go
- object_goreflect.go
- object_goslice.go
- object_goslice_reflect.go
- object_lazy.go
- proxy.go
- regexp.go
- runtime.go
- srcfile.go
- string.go
- string_ascii.go
- string_unicode.go
- typedarrays.go
- value.go
- vm.go
Directories ¶
Path | Synopsis |
---|---|
Package ast declares types representing a JavaScript AST.
|
Package ast declares types representing a JavaScript AST. |
Package file encapsulates the file abstractions used by the ast & parser.
|
Package file encapsulates the file abstractions used by the ast & parser. |
Package ftoa provides ECMAScript-compliant floating point number conversion to string.
|
Package ftoa provides ECMAScript-compliant floating point number conversion to string. |
internal/fast
Package fast contains code ported from V8 (https://github.com/v8/v8/blob/master/src/numbers/fast-dtoa.cc) See LICENSE_V8 for the original copyright message and disclaimer.
|
Package fast contains code ported from V8 (https://github.com/v8/v8/blob/master/src/numbers/fast-dtoa.cc) See LICENSE_V8 for the original copyright message and disclaimer. |
Package parser implements a parser for JavaScript.
|
Package parser implements a parser for JavaScript. |
Package token defines constants representing the lexical tokens of JavaScript (ECMA5).
|
Package token defines constants representing the lexical tokens of JavaScript (ECMA5). |
Package unistring contains an implementation of a hybrid ASCII/UTF-16 string.
|
Package unistring contains an implementation of a hybrid ASCII/UTF-16 string. |