interp

package
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2022 License: Apache-2.0 Imports: 32 Imported by: 0

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 

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 

type BreakpointRequest func(*breakpointSetup, int)

BreakpointRequest is a request to set a breakpoint.

func FunctionBreakpoint 

func FunctionBreakpoint(name string) BreakpointRequest

FunctionBreakpoint requests a breakpoint on the named function.

func LineBreakpoint 

func LineBreakpoint(line int) BreakpointRequest

LineBreakpoint requests a breakpoint on the given line.

type BreakpointTarget 

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

BreakpointTarget is the target of a request to set breakpoints.

func AllBreakpointTarget 

func AllBreakpointTarget() BreakpointTarget

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

func PathBreakpointTarget 

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 

func ProgramBreakpointTarget(prog *Program) BreakpointTarget

ProgramBreakpointTarget is used to set breakpoints on a Program.

type DebugEvent 

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

A DebugEvent is an event generated by a debugger.

func (*DebugEvent) FrameDepth 

func (evt *DebugEvent) FrameDepth() int

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

func (*DebugEvent) Frames 

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

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

func (*DebugEvent) GoRoutine 

func (evt *DebugEvent) GoRoutine() int

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

func (*DebugEvent) Reason 

func (evt *DebugEvent) Reason() DebugEventReason

Reason returns the reason for the event.

type DebugEventReason 

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 

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

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

func (*DebugFrame) Name 

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 

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 

func (f *DebugFrame) Program() *Program

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

func (*DebugFrame) Scopes 

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

Scopes returns the variable scopes of the frame.

type DebugFrameScope 

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

DebugFrameScope provides access to scoped variables while debugging a program.

func (*DebugFrameScope) IsClosure 

func (f *DebugFrameScope) IsClosure() bool

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

func (*DebugFrameScope) Variables 

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

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

type DebugGoRoutine 

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

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

func (*DebugGoRoutine) ID 

func (r *DebugGoRoutine) ID() int

ID returns the ID of the Go routine.

func (*DebugGoRoutine) Name 

func (r *DebugGoRoutine) Name() string

Name returns "Goroutine {ID}".

type DebugOptions 

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

DebugOptions are the debugger options.

type DebugVariable 

type DebugVariable struct {
	Name  string
	Value reflect.Value
}

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

type Debugger 

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

A Debugger can be used to debug a Yaegi program.

func (*Debugger) Continue 

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 

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

GoRoutines returns an array of live Go routines.

func (*Debugger) Interrupt 

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 

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 

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 

func (dbg *Debugger) Terminate()

Terminate attempts to terminate the program.

func (*Debugger) Wait 

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 

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

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

func (*Interpreter) CompileAST 

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.

WARNING: The node must have been parsed using interp.FileSet(). Results are unpredictable otherwise.

func (*Interpreter) CompilePath 

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

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

func (*Interpreter) Debug 

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 

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 

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

Execute executes compiled Go code.

func (*Interpreter) ExecuteWithContext 

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

ExecuteWithContext executes compiled Go code.

func (*Interpreter) FileSet 

func (interp *Interpreter) FileSet() *token.FileSet

FileSet is the fileset that must be used for parsing Go that will be passed to interp.CompileAST().

func (*Interpreter) Globals 

func (interp *Interpreter) Globals() map[string]reflect.Value

Globals returns a map of global variables and constants in the main package.

func (*Interpreter) ImportUsed 

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 

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.