interp

package
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Nov 9, 2021 License: Apache-2.0 Imports: 33 Imported by: 165

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

Examples

Constants

View Source 
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

View Source 
var (
	// ErrNotLive indicates that the specified ID does not refer to a (live) Go
	// routine.
	ErrNotLive = errors.New("not live")

	// ErrRunning indicates that the specified Go routine is running.
	ErrRunning = errors.New("running")

	// ErrNotRunning indicates that the specified Go routine is running.
	ErrNotRunning = errors.New("not running")
)
View Source 
var Symbols = Exports{
	// contains filtered or unexported fields
}

Symbols exposes interpreter values.

Functions

This section is empty.

Types

type Breakpoint added in v0.10.0 

type Breakpoint struct {
	// Valid indicates whether the breakpoint was successfully set.
	Valid bool

	// Position indicates the source position of the breakpoint.
	Position token.Position
}

Breakpoint is the result of attempting to set a breakpoint.

type BreakpointRequest added in v0.10.0 

type BreakpointRequest func(*breakpointSetup, int)

BreakpointRequest is a request to set a breakpoint.

func FunctionBreakpoint added in v0.10.0 

func FunctionBreakpoint(name string) BreakpointRequest

FunctionBreakpoint requests a breakpoint on the named function.

func LineBreakpoint added in v0.10.0 

func LineBreakpoint(line int) BreakpointRequest

LineBreakpoint requests a breakpoint on the given line.

type BreakpointTarget added in v0.10.0 

type BreakpointTarget func(*Debugger, func(*node))

BreakpointTarget is the target of a request to set breakpoints.

func AllBreakpointTarget added in v0.10.0 

func AllBreakpointTarget() BreakpointTarget

AllBreakpointTarget is used to set breakpoints on all compiled code. Do not use with LineBreakpoint.

func PathBreakpointTarget added in v0.10.0 

func PathBreakpointTarget(path string) BreakpointTarget

PathBreakpointTarget is used to set breapoints on compiled code by path. This can be used to set breakpoints on code compiled with EvalPath, or source packages loaded by Yaegi.

func ProgramBreakpointTarget added in v0.10.0 

func ProgramBreakpointTarget(prog *Program) BreakpointTarget

ProgramBreakpointTarget is used to set breakpoints on a Program.

type DebugEvent added in v0.10.0 

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

A DebugEvent is an event generated by a debugger.

func (*DebugEvent) FrameDepth added in v0.10.0 

func (evt *DebugEvent) FrameDepth() int

FrameDepth returns the number of call frames in the stack trace.

func (*DebugEvent) Frames added in v0.10.0 

func (evt *DebugEvent) Frames(start, end int) []*DebugFrame

Frames returns the call frames in the range [start, end).

func (*DebugEvent) GoRoutine added in v0.10.0 

func (evt *DebugEvent) GoRoutine() int

GoRoutine returns the ID of the Go routine that generated the event.

func (*DebugEvent) Reason added in v0.10.0 

func (evt *DebugEvent) Reason() DebugEventReason

Reason returns the reason for the event.

type DebugEventReason added in v0.10.0 

type DebugEventReason int

DebugEventReason is the reason a debug event occurred. 

const (

	// DebugPause is emitted when a pause request is completed. Can be used with
	// Interrupt to request a pause.
	DebugPause DebugEventReason

	// DebugBreak is emitted when a debug target hits a breakpoint.
	DebugBreak

	// DebugEntry is emitted when a debug target starts executing. Can be used
	// with Step to produce a corresponding event when execution starts.
	DebugEntry

	// DebugStepInto is emitted when a stepInto request is completed. Can be
	// used with Step or Interrupt to request a stepInto.
	DebugStepInto

	// DebugStepOver is emitted when a stepOver request is completed. Can be
	// used with Step or Interrupt to request a stepOver.
	DebugStepOver

	// DebugStepOut is emitted when a stepOut request is completed. Can be used
	// with Step or Interrupt to request a stepOut.
	DebugStepOut

	// DebugTerminate is emitted when a debug target terminates. Can be used
	// with Interrupt to attempt to terminate the program.
	DebugTerminate

	// DebugEnterGoRoutine is emitted when a Go routine is entered.
	DebugEnterGoRoutine

	// DebugExitGoRoutine is emitted when a Go routine is exited.
	DebugExitGoRoutine
)

type DebugFrame added in v0.10.0 

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

DebugFrame provides access to stack frame information while debugging a program.

func (*DebugFrame) Name added in v0.10.0 

func (f *DebugFrame) Name() string

Name returns the name of the stack frame. For function calls to named functions, this is the function name.

func (*DebugFrame) Position added in v0.10.0 

func (f *DebugFrame) Position() token.Position

Position returns the current position of the frame. This is effectively the program counter/link register. May return `Position{}`.

func (*DebugFrame) Program added in v0.10.0 

func (f *DebugFrame) Program() *Program

Program returns the program associated with the current position of the frame. May return nil.

func (*DebugFrame) Scopes added in v0.10.0 

func (f *DebugFrame) Scopes() []*DebugFrameScope

Scopes returns the variable scopes of the frame.

type DebugFrameScope added in v0.10.0 

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

DebugFrameScope provides access to scoped variables while debugging a program.

func (*DebugFrameScope) IsClosure added in v0.10.0 

func (f *DebugFrameScope) IsClosure() bool

IsClosure returns true if this is the capture scope of a closure.

func (*DebugFrameScope) Variables added in v0.10.0 

func (f *DebugFrameScope) Variables() []*DebugVariable

Variables returns the names and values of the variables of the scope.

type DebugGoRoutine added in v0.10.0 

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

DebugGoRoutine provides access to information about a Go routine while debugging a program.

func (*DebugGoRoutine) ID added in v0.10.0 

func (r *DebugGoRoutine) ID() int

ID returns the ID of the Go routine.

func (*DebugGoRoutine) Name added in v0.10.0 

func (r *DebugGoRoutine) Name() string

Name returns "Goroutine {ID}".

type DebugOptions added in v0.10.0 

type DebugOptions struct {
	// If true, Go routine IDs start at 1 instead of 0.
	GoRoutineStartAt1 bool
}

DebugOptions are the debugger options.

type DebugVariable added in v0.10.0 

type DebugVariable struct {
	Name  string
	Value reflect.Value
}

DebugVariable is the name and value of a variable from a debug session.

type Debugger added in v0.10.0 

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

A Debugger can be used to debug a Yaegi program.

func (*Debugger) Continue added in v0.10.0 

func (dbg *Debugger) Continue(id int) error

Continue continues execution of the specified Go routine. Continue returns ErrNotLive if there is no Go routine with the corresponding ID, or if it is not live.

func (*Debugger) GoRoutines added in v0.10.0 

func (dbg *Debugger) GoRoutines() []*DebugGoRoutine

GoRoutines returns an array of live Go routines.

func (*Debugger) Interrupt added in v0.10.0 

func (dbg *Debugger) Interrupt(id int, reason DebugEventReason) bool

Interrupt issues a stepInto, stepOver, or stepOut request to a running Go routine. Interrupt returns ErrRunning if the Go routine is running. Interrupt returns ErrNotLive if there is no Go routine with the corresponding ID, or if it is not live.

func (*Debugger) SetBreakpoints added in v0.10.0 

func (dbg *Debugger) SetBreakpoints(target BreakpointTarget, requests ...BreakpointRequest) []Breakpoint

SetBreakpoints sets breakpoints for the given target. The returned array has an entry for every request, in order. If a given breakpoint request cannot be satisfied, the corresponding entry will be marked invalid. If the target cannot be found, all entries will be marked invalid.

func (*Debugger) Step added in v0.10.0 

func (dbg *Debugger) Step(id int, reason DebugEventReason) error

Step issues a stepInto, stepOver, or stepOut request to a stopped Go routine. Step returns ErrRunning if the Go routine is running. Step returns ErrNotLive if there is no Go routine with the corresponding ID, or if it is not live.

func (*Debugger) Terminate added in v0.10.0 

func (dbg *Debugger) Terminate()

Terminate attempts to terminate the program.

func (*Debugger) Wait added in v0.10.0 

func (dbg *Debugger) Wait() (reflect.Value, error)

Wait blocks until all Go routines launched by the program have terminated. Wait returns the results of `(*Interpreter).Execute`.

type Exports 

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

Exports stores the map of binary packages per package path. The package path is the path joined from the import path and the package name as specified in source files by the "package" statement.

type Interpreter 

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

Interpreter contains global resources and state.

Example (Self) 
package main

import (
	"log"

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

func main() {
	i := interp.New(interp.Options{})

	if err := i.Use(stdlib.Symbols); err != nil {
		log.Fatal(err)
	}
	if err := i.Use(interp.Symbols); err != nil {
		log.Fatal(err)
	}

	_, err := i.Eval(`import (
	"fmt"
	"log"

	// Import interp to gain access to Self.
	"github.com/traefik/yaegi/interp"
)`)
	if err != nil {
		log.Fatal(err)
	}

	_, err = i.Eval(`
		// Evaluate code directly.
		fmt.Println("Hello Yaegi from Go")

		// Evaluate code indirectly via the Self access point.
		_, err := interp.Self.Eval("fmt.Println(\"Hello Yaegi from Yaegi\")")
		if err != nil {
			log.Fatal(err)
		}
`)
	if err != nil {
		log.Fatal(err)
	}

}

Output:


Hello Yaegi from Go
Hello Yaegi from Yaegi

var Self *Interpreter

Self points to the current interpreter if accessed from within itself, or is nil.

func New 

func New(options Options) *Interpreter

New returns a new interpreter.

func (*Interpreter) Compile added in v0.10.0 

func (interp *Interpreter) Compile(src string) (*Program, error)

Compile parses and compiles a Go code represented as a string.

func (*Interpreter) CompileAST added in v0.11.0 

func (interp *Interpreter) CompileAST(n ast.Node) (*Program, error)

CompileAST builds a Program for the given Go code AST. Files and block statements can be compiled, as can most expressions. Var declaration nodes cannot be compiled.

func (*Interpreter) CompilePath added in v0.10.0 

func (interp *Interpreter) CompilePath(path string) (*Program, error)

CompilePath parses and compiles a Go code located at the given path.

func (*Interpreter) Debug added in v0.10.0 

func (interp *Interpreter) Debug(ctx context.Context, prog *Program, events func(*DebugEvent), opts *DebugOptions) *Debugger

Debug initializes a debugger for the given program.

The program will not start running until Step or Continue has been called. If Step is called with DebugEntry, an entry event will be generated before the first statement is executed. Otherwise, the debugger will behave as usual.

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) EvalPathWithContext added in v0.10.0 

func (interp *Interpreter) EvalPathWithContext(ctx context.Context, path string) (res reflect.Value, err error)

EvalPathWithContext 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) Execute added in v0.10.0 

func (interp *Interpreter) Execute(p *Program) (res reflect.Value, err error)

Execute executes compiled Go code.

func (*Interpreter) ExecuteWithContext added in v0.10.0 

func (interp *Interpreter) ExecuteWithContext(ctx context.Context, p *Program) (res reflect.Value, err error)

ExecuteWithContext executes compiled Go code.

func (*Interpreter) ImportUsed added in v0.9.18 

func (interp *Interpreter) ImportUsed()

ImportUsed automatically imports pre-compiled packages included by Use(). This is mainly useful for REPLs, or single command lines. In case of an ambiguous default package name, for example "rand" for crypto/rand and math/rand, the package name is constructed by replacing the last "/" by a "_", producing crypto_rand and math_rand. ImportUsed should not be called more than once, and not after a first Eval, as it may rename packages.

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

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.Stdin, os.Stdout and os.Stderr respectively.
	Stdin          io.Reader
	Stdout, Stderr io.Writer

	// Cmdline args, defaults to os.Args.
	Args []string

	// Environment of interpreter. Entries are in the form "key=values".
	Env []string

	// SourcecodeFilesystem is where the _sourcecode_ is loaded from and does
	// NOT affect the filesystem of scripts when they run.
	// It can be any fs.FS compliant filesystem (e.g. embed.FS, or fstest.MapFS for testing)
	// See example/fs/fs_test.go for an example.
	SourcecodeFilesystem fs.FS

	// Unrestricted allows to run non sandboxed stdlib symbols such as os/exec and environment
	Unrestricted bool
}

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

type Program added in v0.10.0 

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

A Program is Go code that has been parsed and compiled.

Notes

Bugs

  • Support for recursive types is incomplete.

  • Support of types implementing multiple interfaces is incomplete.

Source Files

View all Source files

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.