interp

Documentation

Overview

Package interp provides a complete Go interpreter.

For the Go language itself, refer to the official Go specification https://golang.org/ref/spec.

Importing packages

Packages can be imported in source or binary form, using the standard Go import statement. In source form, packages are searched first in the vendor directory, the preferred way to store source dependencies. If not found in vendor, sources modules will be searched in GOPATH. Go modules are not supported yet by yaegi.

Binary form packages are compiled and linked with the interpreter executable, and exposed to scripts with the Use method. The extract subcommand of yaegi can be used to generate package wrappers.

Custom build tags

Custom build tags allow to control which files in imported source packages are interpreted, in the same way as the "-tags" option of the "go build" command. Setting a custom build tag spans globally for all future imports of the session.

A build tag is a line comment that begins

// yaegi:tags

that lists the build constraints to be satisfied by the further imports of source packages.

For example the following custom build tag

// yaegi:tags noasm

Will ensure that an import of a package will exclude files containing

// +build !noasm

And include files containing

// +build noasm

Example (Eval)

Generic example.

package main

import (
	"fmt"
	"log"

	"github.com/traefik/yaegi/interp"
)

func main() {
	// Create a new interpreter context
	i := interp.New(interp.Options{})

	// Run some code: define a new function
	_, err := i.Eval("func f(i int) int { return 2 * i }")
	if err != nil {
		log.Fatal(err)
	}

	// Access the interpreted f function with Eval
	v, err := i.Eval("f")
	if err != nil {
		log.Fatal(err)
	}

	// Returned v is a reflect.Value, so we can use its interface
	f, ok := v.Interface().(func(int) int)
	if !ok {
		log.Fatal("type assertion failed")
	}

	// Use interpreted f as it was pre-compiled
	fmt.Println(f(2))

}

Output:

4

Index

• Constants
• Variables
• type Exports
• type Interpreter
  • func New(options Options) *Interpreter
  • func (interp *Interpreter) Eval(src string) (res reflect.Value, err error)
  • func (interp *Interpreter) EvalPath(path string) (res reflect.Value, err error)
  • func (interp *Interpreter) EvalTest(path string) error
  • func (interp *Interpreter) EvalWithContext(ctx context.Context, src string) (reflect.Value, error)
  • func (interp *Interpreter) REPL() (reflect.Value, error)
  • func (interp *Interpreter) Symbols(importPath string) Exports
  • func (interp *Interpreter) Use(values Exports)
• type Options
• type Panic
  • func (e Panic) Error() string
• Bugs

Examples

• Package (Eval)

Constants

const (

	// DefaultSourceName is the name used by default when the name of the input
	// source file has not been specified for an Eval.
	// TODO(mpl): something even more special as a name?
	DefaultSourceName = "_.go"

	// Test is the value to pass to EvalPath to activate evaluation of test functions.
	Test = false
	// NoTest is the value to pass to EvalPath to skip evaluation of test functions.
	NoTest = true
)

Variables

var Symbols = Exports{
	// contains filtered or unexported fields
}

Symbols exposes interpreter values.

Types

type Exports

type Exports map[string]map[string]reflect.Value

Exports stores the map of binary packages per package path.

type Interpreter

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

Interpreter contains global resources and state.

func New

func New(options Options) *Interpreter

New returns a new interpreter.

func (*Interpreter) Eval

func (interp *Interpreter) Eval(src string) (res reflect.Value, err error)

Eval evaluates Go code represented as a string. Eval returns the last result computed by the interpreter, and a non nil error in case of failure.

func (*Interpreter) EvalPath

func (interp *Interpreter) EvalPath(path string) (res reflect.Value, err error)

EvalPath evaluates Go code located at path and returns the last result computed by the interpreter, and a non nil error in case of failure. The main function of the main package is executed if present.

func (*Interpreter) EvalTest

func (interp *Interpreter) EvalTest(path string) error

EvalTest evaluates Go code located at path, including test files with "_test.go" suffix. A non nil error is returned in case of failure. The main function, test functions and benchmark functions are internally compiled but not executed. Test functions can be retrieved using the Symbol() method.

func (*Interpreter) EvalWithContext

func (interp *Interpreter) EvalWithContext(ctx context.Context, src string) (reflect.Value, error)

EvalWithContext evaluates Go code represented as a string. It returns a map on current interpreted package exported symbols.

func (*Interpreter) REPL

func (interp *Interpreter) REPL() (reflect.Value, error)

REPL performs a Read-Eval-Print-Loop on input reader. Results are printed to the output writer of the Interpreter, provided as option at creation time. Errors are printed to the similarly defined errors writer. The last interpreter result value and error are returned.

func (*Interpreter) Symbols

func (interp *Interpreter) Symbols(importPath string) Exports

Symbols returns a map of interpreter exported symbol values for the given import path. If the argument is the empty string, all known symbols are returned.

func (*Interpreter) Use

func (interp *Interpreter) Use(values Exports)

Use loads binary runtime symbols in the interpreter context so they can be used in interpreted code.

type Options

type Options struct {
	// GoPath sets GOPATH for the interpreter.
	GoPath string

	// BuildTags sets build constraints for the interpreter.
	BuildTags []string

	// Standard input, output and error streams.
	// They default to os.Stding, os.Stdout and os.Stderr respectively.
	Stdin          io.Reader
	Stdout, Stderr io.Writer
}

Options are the interpreter options.

type Panic

type Panic struct {
	// Value is the recovered value of a call to panic.
	Value interface{}

	// Callers is the call stack obtained from the recover call.
	// It may be used as the parameter to runtime.CallersFrames.
	Callers []uintptr

	// Stack is the call stack buffer for debug.
	Stack []byte
}

Panic is an error recovered from a panic call in interpreted code.

func (Panic) Error

func (e Panic) Error() string

Notes

Bugs

• Support for recursive types is incomplete.

• Support of types implementing multiple interfaces is incomplete.