gojis

README

Gojis

Pure Go ECMAScript interpreter.

---

Gojis is an implementation of ECMAScript 2018 (ES 9). It basically is a JavaScript VM, just like Goja or Otto. The documentation can be found here.

Why

Goja and Otto are both stuck at implementing most features of ES 5.1. This implementation aims to support ES 9, and, after that maybe even ES 10 and later.

What is this Gojis VM good for?

The Gojis VM can be run as a standalone, or you can embed it into your Go application by using the API. Go get it with

go get -u github.com/gojisvm/gojis

Use the Go API

// FIXME: the API is in draft mode, this is subject to change at any time

vm := gojis.NewVM()

vm.SetFunction("greet", func(gojis.Args) gojis.Object {
    vm.Eval(`console.log("Hello World!");`)
    return nil
})

vm.Eval(`greet();`)
/*
    prints:
    Hello World!
*/

Use the CLI

$ gojis test.js
Hello, World!

$ gojis ./src
Hello, World! from test1
Hello, World! from test2
Hello, World! from test3
Hello, World! from test4

Use the Docker image

$ docker run -d -v ./src:/src gojisvm/gojis:latest
Hello, World! from test1
Hello, World! from test2
Hello, World! from test3
Hello, World! from test4

For more documentation, please have a look at the API documentation.

What are the goals?

The primary goal of this project is to have fun coding, as I love to code, but thinking about system designs and architectures is difficult. The ECMAScript language specification (which can be found in /docs), takes care of most of these things already, so a contributor can really focus on implementation and optimization.

Another goal I am trying to achieve is, to provide the Go community with a JavaScript VM that supports at least ES 6 features. Goja and Otto are both stuck at implementing ES 5.1, but this implementation does exactly that.

Current status

There is a milestone to keep track of the implementation progress of ES 9.

License

Documentation

Overview

Package gojis provides a high level API for interaction with ECMAScript code.

Index

• Constants
• Variables
• type Args
  • func (a *Args) Get(index int) Object
  • func (a *Args) Len() int
• type Console
  • func NewConsole(w io.Writer) Console
• type Object
• type Option
• type Type
• type VM
  • func NewVM(opts ...Option) *VM
  • func (vm *VM) Eval(script string) (Object, error)
  • func (vm *VM) SetConsole(console Console)

Constants

const (
	TypeUnknown = iota
	TypeUndefined
	TypeNull
	TypeBoolean
	TypeString
	TypeSymbol
	TypeNumber
	TypeObject
)

Available types. TypeUnknown must not be used. If it appears, this indicates, that somewhere the type was not set (it is the default value for Type).

const (
	// Null represents the Null ECMAScript language value.
	Null = null(0)
)

const (
	// Undefined represents the Undefined ECMAScript language value.
	Undefined = undefined(0)
)

Variables

var Opts = optStruct{}

Opts represents functional options.

Types

type Args

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

Args represent the arguments that are passed to a function call. The arguments can be retrieved using Args#Get(int), and can be used in the function. The arguments are Objects, which can be Null or Undefined. If 3 arguments are passed to the function, args.Get(5) will return Undefined, NOT nil.

func (*Args) Get

func (a *Args) Get(index int) Object

Get returns the argument at the given index. If there is no such argument, Undefined will be returned. This method never returns nil.

func (*Args) Len

func (a *Args) Len() int

Len returns the amount of arguments. For example, if 3 arguments were passed (indices 0, 1 and 2), this method will return 3. Please note, that in this example, args.Get(3) and higher will return Undefined, whereas args.Get(0), 1 and 2 will return the respective arguments.

type Console

type Console interface {
	io.Writer
	Object
}

Console is an io.Writer that is also an Object.

func NewConsole

func NewConsole(w io.Writer) Console

NewConsole creates a ready to use console that can be used inside a VM.

type Object

type Object interface {
	// Lookup returns a property of this object with the given name. If no such
	// property exists, Undefined will be returned. This method never returns nil.
	Lookup(string) Object
	// SetFunction adds a property (more specific, a function object) to this
	// object. When the function object is invoked, the given function will be
	// executed, with all parameters wrapped into the Args object.
	SetFunction(string, func(Args) Object)
	// CallWithArgs attempts to invoke this objects 'Call' property. Note that this
	// property is only set if this object is a function or constructor object. If
	// this object does not have a 'Call' property that is callable, an error will
	// be returned.
	CallWithArgs(...interface{}) (Object, error)
	// SetObject adds a property with the given name to this object. The property's
	// value will be the given object.
	SetObject(string, Object)

	// IsUndefined is used to determine whether this object represents the Undefined
	// value.
	IsUndefined() bool
	// IsNull is used to determine whether this object represents the Null value.
	IsNull() bool
	// IsFunction is used to determine whether this object can be invoked. If this
	// returns true, CallWithArgs will not return an error.
	IsFunction() bool

	// Type returns the ECMAScript language type of this object.
	Type() Type
	// Value returns the Go value corresponding to the ECMAScript language value of
	// this object.
	Value() interface{}
}

Object represents any ECMAScript language value. This can be a String or a Number as well as Null or Undefined. To check if the object represents Null, use Object#IsNull. To check if the object represents Undefined, use Object#IsUndefined.

type Option

type Option func(*VM)

Option represents configuration for a VM instance.

type Type

type Type uint8

Type represents the ECMAScript language types.

type VM

type VM struct {
	Object // the global object
	// contains filtered or unexported fields
}

VM represents an instance of the GojisVM. It can be used to evaluate ECMAScript code.

func NewVM

func NewVM(opts ...Option) *VM

NewVM creates a new, initialized VM that is ready to use.

func (*VM) Eval

func (vm *VM) Eval(script string) (Object, error)

Eval delegates to the builtin eval function of this VM's global object.

func (*VM) SetConsole

func (vm *VM) SetConsole(console Console)

SetConsole is used to change the console of the VM. Calls like 'console.log' will be written to the given Console.