ecmascript

README

ECMAScript

This core.Interpreter is based on Goja, which executes Ecmascript 5.1.

Unlike the demo goja interpreter (interpreters/goja), this interpreter doesn't support libraries. If you want to use this interpreter but also want to use libraries, then you should implement a preprocessing step that generates source that has the libraries embedded in that source.

Eventually deprecate interpreters/goja in favor of this interpreter.

Environment

The base runtime environment includes a binding for the variable _:

1. _.bindings: The current set of machine bindings.

2. _.params: The current parameters for the machine execution. These parameters are provided by the application that uses the Machines core. In the example mservice process, these parameters include

   1. mid: The id of the current machine
   2. cid: The id of the machine's crew

3. _.props: core.StepProps (if any).

4. _.out(X): "Emits" the given message.

If the interpreter's Extended flag is true, then _ has these additional properties:

1. _.genstr(): Generates a random 32-char string

2. _.cronNext(CRONEXPR) → TIMESTAMP: cronNext attempts to parse its argument as a cron expression. If successful, returns the next time in Go RFC3339Nano format.

   Example:

   ({next: _.cronNext("* 0 * * *")});
   

3. _.match(PATTERN, MESSAGE): Invokes pattern matching.

If the interpreter's Test flag is true, then _ has these additional properties:

1. _.sleep(MS): Sleeps for the given number of milliseconds.

2. _.exit(N): Terminates the process (!) with the given exit code.

Documentation

Overview

Package ecmascript provides an ECMAScript-compatible action interpreter.

Index

• Variables
• func AsSource(src interface{}) (code string, err error)
• func RunProgram(o *goja.Runtime, p *goja.Program) (v goja.Value, err error)
• type Interpreter
  • func NewInterpreter() *Interpreter
  • func (i *Interpreter) Compile(ctx context.Context, src interface{}) (interface{}, error)
  • func (i *Interpreter) Exec(ctx context.Context, bs match.Bindings, props core.StepProps, src interface{}, ...) (*core.Execution, error)

Variables

var (
	// InterruptedMessage is the string value of Interrupted.
	InterruptedMessage = "RuntimeError: timeout"

	// Interrupted is returned by Exec if the execution is
	// interrupted.
	Interrupted = errors.New(InterruptedMessage)

	// IgnoreExit will prevent the Goja function "exit" from
	// terminating the process. Being able to halt the process
	// from Goja is useful for some tests and utilities.  Maybe.
	IgnoreExit = false
)

Functions

func AsSource

func AsSource(src interface{}) (code string, err error)

func RunProgram

func RunProgram(o *goja.Runtime, p *goja.Program) (v goja.Value, err error)

Types

type Interpreter

type Interpreter struct {

	// Testing is used to expose or hide some runtime
	// capabilities.
	Test bool

	// Extended adds some additional properties.
	Extended bool
}

Interpreter implements core.Intepreter using Goja, which is a Go implementation of ECMAScript 5.1+.

See https://github.com/dop251/goja.

func NewInterpreter

func NewInterpreter() *Interpreter

NewInterpreter makes a new Interpreter.

func (*Interpreter) Compile

func (i *Interpreter) Compile(ctx context.Context, src interface{}) (interface{}, error)

Compile calls goja.Compile. This step is optional.

See BenchmarkPrecompile and BenchmarkNoPrecompile for a comparison of what compilation can do for you.

func (*Interpreter) Exec

func (i *Interpreter) Exec(ctx context.Context, bs match.Bindings, props core.StepProps, src interface{}, compiled interface{}) (*core.Execution, error)

Exec implements the Interpreter method of the same name.

The following properties are available from the runtime at _.

These two things are most important:

bindings: the map of the current bindings.
props: core.StepProps
out(obj): Add the given object as a message to emit.

Extended properties (enabled by interpreter's Extended property):

randstr(): generate a random string.
cronNext(s): Return a string representing (RFC3999Nano) the
  next time for the given crontab expression.
esc(s): URL query-escape the given string.
match(pat, obj): Execute the pattern matcher.

Testing properties (enabled by the interpreter's Test property):

sleep(ms): sleep for the given number of milliseconds.  For testing.
exit(msg): Terminate the process after printing the given message.
  For testing.