goja

package module
v0.0.0-...-f24d0f0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 17, 2017 License: MIT Imports: 29 Imported by: 0

README

goja

ECMAScript 5.1(+) implementation in Go.

GoDoc

It is not a replacement for V8 or SpiderMonkey or any other general-purpose JavaScript engine as it is much slower. It can be used as an embedded scripting language where the cost of making a lot of cgo calls may outweight the benefits of a faster JavaScript engine or as a way to avoid having non-Go dependencies.

This project was largely inspired by otto.

Features

Current Status

  • API is still work in progress and is subject to change.
  • Some of the AnnexB functionality is missing.
  • No typed arrays yet.

Basic Example

vm := goja.New()
v, err := vm.RunString("2 + 2")
if err != nil {
    panic(err)
}
if num := v.Export().(int64); num != 4 {
    panic(num)
}

Passing Values to JS

Any Go value can be passed to JS using Runtime.ToValue() method. Primitive types (ints and uints, floats, string, bool) are converted to the corresponding JavaScript primitives.

func(FunctionCall) Value is treated as a native JavaScript function.

func(ConstructorCall) Value is treated as a JavaScript constructor (see Native Constructors).

map[string]interface{} is converted into a host object that largely behaves like a JavaScript Object.

[]interface{} is converted into a host object that behaves largely like a JavaScript Array, however it's not extensible because extending it can change the pointer so it becomes detached from the original.

*[]interface{} is same as above, but the array becomes extensible.

A function is wrapped within a native JavaScript function. When called the arguments are automatically converted to the appropriate Go types. If conversion is not possible, a TypeError is thrown.

A slice type is converted into a generic reflect based host object that behaves similar to an unexpandable Array.

A map type with numeric or string keys and no methods is converted into a host object where properties are map keys.

A map type with methods is converted into a host object where properties are method names, the map values are not accessible. This is to avoid ambiguity between m["Property"] and m.Property.

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 these conversions wrap the original value which means any changes made inside JS are reflected on the value and calling Export() returns the original value. This applies to all reflect based types.

Exporting Values from JS

A JS value can be exported into its default Go representation using Value.Export() method.

Alternatively it can be exported into a specific Go variable using Runtime.ExportTo() method.

Native Constructors

In order to implement a constructor function in Go:

func MyObject(call goja.ConstructorCall) Value {
    // call.This contains the newly created object as per http://www.ecma-international.org/ecma-262/5.1/index.html#sec-13.2.2
    // call.Arguments contain arguments passed to the function

    call.This.Set("method", method)

    //...

    // If return value is a non-nil *Object, it will be used instead of call.This
    // This way it is possible to return a Go struct or a map converted
    // into goja.Value using runtime.ToValue(), however in this case
    // instanceof will not work as expected.
    return nil
}

runtime.Set("MyObject", MyObject)

Then it can be used in JS as follows:

var o = new MyObject(arg);
var o1 = MyObject(arg); // same thing
o instanceof MyObject && o1 instanceof MyObject; // true

Regular Expressions

Goja uses the embedded Go regexp library where possible, otherwise it falls back to regexp2.

Exceptions

Any exception thrown in JavaScript is returned as an error of type *Exception. It is possible to extract the value thrown by using the Value() method:

vm := New()
_, err := vm.RunString(`

throw("Test");

`)

if jserr, ok := err.(*Exception); ok {
    if jserr.Value().Export() != "Test" {
        panic("wrong value")
    }
} else {
    panic("wrong type")
}

If a native Go function panics with a Value, it is thrown as a Javascript exception (and therefore can be caught):

var vm *Runtime

func Test() {
    panic(vm.ToValue("Error"))
}

vm = New()
vm.Set("Test", Test)
_, err := vm.RunString(`

try {
    Test();
} catch(e) {
    if (e !== "Error") {
        throw e;
    }
}

`)

if err != nil {
    panic(err)
}

Interrupting

func TestInterrupt(t *testing.T) {
    const SCRIPT = `
    var i = 0;
    for (;;) {
        i++;
    }
    `

    vm := New()
    time.AfterFunc(200 * time.Millisecond, func() {
        vm.Interrupt("halt")
    })

    _, err := vm.RunString(SCRIPT)
    if err == nil {
        t.Fatal("Err is nil")
    }
    // err is of type *InterruptError and its Value() method returns whatever has been passed to vm.Interrupt()
}

NodeJS Compatibility

There is a separate project aimed at providing some of the NodeJS functionality.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	InvalidRuneError = errors.New("Invalid rune")
)

Functions

func IsNull 

func IsNull(v Value) bool

IsNull returns true if the supplied Value is null.

func IsUndefined 

func IsUndefined(v Value) bool

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 Callable 

type Callable func(this Value, args ...Value) (Value, error)

Callable represents a JavaScript function that can be called from Go.

func AssertFunction 

func AssertFunction(v Value) (Callable, bool)

AssertFunction checks if the Value is a function and returns a Callable.

type CompilerError 

type CompilerError struct {
	Message string
	File    *SrcFile
	Offset  int
}

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 

type ConstructorCall struct {
	This      *Object
	Arguments []Value
}

func (ConstructorCall) Argument 

func (f ConstructorCall) Argument(idx int) Value

type Exception 

type Exception struct {
	// contains filtered or unexported fields
}

func (*Exception) Error 

func (e *Exception) Error() string

func (*Exception) String 

func (e *Exception) String() string

func (*Exception) Value 

func (e *Exception) Value() 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

	// FieldName 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.

type Flag 

type Flag int
const (
	FLAG_NOT_SET Flag = iota
	FLAG_FALSE
	FLAG_TRUE
)

func ToFlag 

func ToFlag(b bool) Flag

func (Flag) Bool 

func (f Flag) Bool() bool

type FunctionCall 

type FunctionCall struct {
	This      Value
	Arguments []Value
}

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) Equals 

func (o *Object) Equals(other Value) bool

func (*Object) Export 

func (o *Object) Export() interface{}

func (*Object) ExportType 

func (o *Object) ExportType() reflect.Type

func (*Object) Get 

func (o *Object) Get(name string) Value

func (*Object) Keys 

func (o *Object) Keys() (keys []string)

func (*Object) MarshalJSON 

func (o *Object) MarshalJSON() ([]byte, error)

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) SameAs 

func (o *Object) SameAs(other Value) bool

func (*Object) Set 

func (o *Object) Set(name string, value interface{}) error

func (*Object) StrictEquals 

func (o *Object) StrictEquals(other Value) bool

func (*Object) String 

func (o *Object) String() string

func (*Object) ToBoolean 

func (o *Object) ToBoolean() bool

func (*Object) ToFloat 

func (o *Object) ToFloat() float64

func (*Object) ToInteger 

func (o *Object) ToInteger() int64

func (*Object) ToNumber 

func (o *Object) ToNumber() Value

func (*Object) ToObject 

func (o *Object) ToObject(r *Runtime) *Object

func (*Object) ToString 

func (o *Object) ToString() valueString

type Position 

type Position struct {
	Line, Col int
}

func (Position) String 

func (p Position) String() string

type Program 

type Program struct {
	// contains filtered or unexported fields
}

func Compile 

func Compile(name, src string, strict bool) (*Program, error)

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 

func CompileAST(prg *js_ast.Program, strict bool) (*Program, error)

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 

func MustCompile(name, src string, strict bool) *Program

MustCompile is like Compile but panics if the code cannot be compiled. It simplifies safe initialization of global variables holding compiled JavaScript code.

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) CreateObject 

func (r *Runtime) CreateObject(proto *Object) *Object

CreateObject creates an object with given prototype. Equivalent of Object.create(proto).

func (*Runtime) ExportTo 

func (r *Runtime) ExportTo(v Value, target interface{}) error

ExportTo converts a JavaScript value into the specified Go value. The second parameter must be a non-nil pointer. Returns error if conversion is not possible.

func (*Runtime) Get 

func (r *Runtime) Get(name string) Value

Get the specified property of the global object.

func (*Runtime) GlobalObject 

func (r *Runtime) GlobalObject() *Object

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).

func (*Runtime) NewGoError 

func (r *Runtime) NewGoError(err error) *Object

func (*Runtime) NewObject 

func (r *Runtime) NewObject() (v *Object)

func (*Runtime) NewTypeError 

func (r *Runtime) NewTypeError(args ...interface{}) *Object

func (*Runtime) RunProgram 

func (r *Runtime) RunProgram(p *Program) (result Value, err error)

RunProgram executes a pre-compiled (see Compile()) code in the global context.

func (*Runtime) RunScript 

func (r *Runtime) RunScript(name, src string) (Value, error)

RunScript executes the given string in the global context.

func (*Runtime) RunString 

func (r *Runtime) RunString(str string) (Value, error)

RunString executes the given string in the global context.

func (*Runtime) Set 

func (r *Runtime) Set(name string, value interface{})

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)

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) ToValue 

func (r *Runtime) ToValue(i interface{}) Value

ToValue converts a Go value into JavaScript value.

Primitive types (ints and uints, floats, string, bool) are converted to the corresponding JavaScript primitives.

func(FunctionCall) Value is treated as a native JavaScript function.

map[string]interface{} is converted into a host object that largely behaves like a JavaScript Object.

[]interface{} is converted into a host object that behaves largely like a JavaScript Array, however it's not extensible because extending it can change the pointer so it becomes detached from the original.

*[]interface{} same as above, but the array becomes extensible.

A function is wrapped within a native JavaScript function. When called the arguments are automatically converted to the appropriate Go types. If conversion is not possible, a TypeError is thrown.

A slice type is converted into a generic reflect based host object that behaves similar to an unexpandable Array.

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 SrcFile 

type SrcFile struct {
	// contains filtered or unexported fields
}

func NewSrcFile 

func NewSrcFile(name, src string) *SrcFile

func (*SrcFile) Position 

func (f *SrcFile) Position(offset int) Position

type Value 

type Value interface {
	ToInteger() int64
	ToString() valueString
	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
}

func Null 

func Null() Value

Null returns JS null value.

func Undefined 

func Undefined() Value

Undefined returns JS undefined value. Note if global 'undefined' property is changed this still returns the original value.

Source Files

View all Source files

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 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).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.