vm

Documentation

Overview

Package vm is an extendable, embeddable javascript interpreter for squircy3.

This package embeds goja (https://github.com/dop251/goja) as the javascript parser and executor, improving on it with a concurrency-safe API, intuitive API for dealing with asynchronous results, and basic compatibility with NodeJS's require() function.

Index

• Variables
• func Initialize(*plugin.Manager) (plugin.Plugin, error)
• type AsyncResult
  • func (r *AsyncResult) Await() (goja.Value, error)
  • func (r *AsyncResult) Cancel()
• type Module
  • func (m *Module) FullPath() string
  • func (m *Module) Require(name string) (*Module, error)
  • func (m *Module) String() string
• type PrependRuntimeInitHandler
• type Registry
  • func NewRegistry(basePath string) *Registry
  • func (r *Registry) Enable(runtime *goja.Runtime)
  • func (r *Registry) Modules() []string
  • func (r *Registry) SetModule(module *Module)
• type Result
  • func (r *Result) Await() (goja.Value, error)
  • func (r *Result) Cancel()
• type RuntimeInitHandler
• type VM
  • func FromPlugins(m *plugin.Manager) (*VM, error)
  • func New(registry *Registry) (*VM, error)
  • func (vm *VM) Compile(name, in string) (*goja.Program, error)
  • func (vm *VM) Do(fn func(*goja.Runtime))
  • func (vm *VM) OnRuntimeInit(h func(*goja.Runtime))
  • func (vm *VM) PrependRuntimeInit(h func(*goja.Runtime))
  • func (vm *VM) RunProgram(p *goja.Program) *AsyncResult
  • func (vm *VM) RunScript(name, in string) *AsyncResult
  • func (vm *VM) RunString(in string) *AsyncResult
  • func (vm *VM) SetModule(module *Module)
  • func (vm *VM) SetTransformer(fn func(in string) (string, error))
  • func (vm *VM) Shutdown() error
  • func (vm *VM) Start() error

Variables

var ErrExecutionCancelled = errors.New("execution cancelled")

Functions

func Initialize

func Initialize(*plugin.Manager) (plugin.Plugin, error)

Initialize is a plugin.Initializer that initializes a vm plugin.

Types

type AsyncResult

type AsyncResult struct {
	// Closed when the result is ready. Read from this channel to detect when
	// the result has been populated and is safe to inspect.
	Ready chan struct{}
	// Error associated with the result, if any. Only read from this after
	// the result is ready.
	Error error
	// Value associated with the result if there is no error. Only read from
	// this after the result is ready.
	Value goja.Value
	// contains filtered or unexported fields
}

AsyncResult handles invocations of asynchronous code that returns promises. An AsyncResult accepts any goja.Value; non-promises are supported so this is safe (if maybe a bit inefficient) to wrap all results produced by using one of the Run* methods on a VM.

func (*AsyncResult) Await

func (r *AsyncResult) Await() (goja.Value, error)

Await blocks until the result is ready and returns the result or error.

func (*AsyncResult) Cancel

func (r *AsyncResult) Cancel()

Cancel the result to halt execution.

type Module

type Module struct {
	Name string
	Path string
	Main string
	Body string
	// contains filtered or unexported fields
}

A Module is a javascript module identified by a name and full path.

func (*Module) FullPath

func (m *Module) FullPath() string

func (*Module) Require

func (m *Module) Require(name string) (*Module, error)

Require loads the given name within the context of the Module. Relative paths are supported, as are implicit index.js requires, and suffix-less requires. If the name is a module, its package.json will be parsed to determine which script to execute. This method does not evaluate the loaded module, see instead the package-level require function.

func (*Module) String

func (m *Module) String() string

type PrependRuntimeInitHandler

type PrependRuntimeInitHandler interface {
	RuntimeInitHandler
	// PrependRuntimeInitHandler returns true if the handler should be added
	// to the start of the list of handlers.
	PrependRuntimeInitHandler() bool
}

A PrependRuntimeInitHandler is a RuntimeInitHandler that may be added at the start of the list of handlers.

type Registry

type Registry struct {
	Transform func(in string) (string, error)
	// contains filtered or unexported fields
}

A Registry provides basic commonjs-compatible facilities for a VM.

func NewRegistry

func NewRegistry(basePath string) *Registry

NewRegistry creates a new registry with the given base path. A Registry is designed to provide NodeJS type require() functions to goja.

func (*Registry) Enable

func (r *Registry) Enable(runtime *goja.Runtime)

func (*Registry) Modules

func (r *Registry) Modules() []string

func (*Registry) SetModule

func (r *Registry) SetModule(module *Module)

SetModule adds the Module to the Registry.

type Result

type Result struct {
	// Closed when the result is ready. Read from this channel to detect when
	// the result has been populated and is safe to inspect.
	Ready chan struct{}
	// Error associated with the result, if any. Only read from this after
	// the result is ready.
	Error error
	// Value associated with the result if there is no error. Only read from
	// this after the result is ready.
	Value goja.Value
	// contains filtered or unexported fields
}

A Result is the output from executing synchronous code on a VM.

func (*Result) Await

func (r *Result) Await() (goja.Value, error)

Await blocks until the result is ready and returns the result or error.

func (*Result) Cancel

func (r *Result) Cancel()

Cancel the result to halt execution.

type RuntimeInitHandler

type RuntimeInitHandler interface {
	// Initialize and configure the given runtime.
	HandleRuntimeInit(r *goja.Runtime)
}

A RuntimeInitHandler initializes a newly created goja.Runtime.

type VM

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

A VM manages the state and environment of a javascript interpreter.

func FromPlugins

func FromPlugins(m *plugin.Manager) (*VM, error)

FromPlugins returns the vm plugin's VM or an error if it fails.

func New

func New(registry *Registry) (*VM, error)

func (*VM) Compile

func (vm *VM) Compile(name, in string) (*goja.Program, error)

func (*VM) Do

func (vm *VM) Do(fn func(*goja.Runtime))

func (*VM) OnRuntimeInit

func (vm *VM) OnRuntimeInit(h func(*goja.Runtime))

func (*VM) PrependRuntimeInit

func (vm *VM) PrependRuntimeInit(h func(*goja.Runtime))

func (*VM) RunProgram

func (vm *VM) RunProgram(p *goja.Program) *AsyncResult

func (*VM) RunScript

func (vm *VM) RunScript(name, in string) *AsyncResult

func (*VM) RunString

func (vm *VM) RunString(in string) *AsyncResult

func (*VM) SetModule

func (vm *VM) SetModule(module *Module)

func (*VM) SetTransformer

func (vm *VM) SetTransformer(fn func(in string) (string, error))

func (*VM) Shutdown

func (vm *VM) Shutdown() error

func (*VM) Start

func (vm *VM) Start() error