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 Breakpoint
- type BreakpointRequest
- type BreakpointTarget
- type DebugEvent
- type DebugEventReason
- type DebugFrame
- type DebugFrameScope
- type DebugGoRoutine
- type DebugOptions
- type DebugVariable
- type Debugger
- func (dbg *Debugger) Continue(id int) error
- func (dbg *Debugger) GoRoutines() []*DebugGoRoutine
- func (dbg *Debugger) Interrupt(id int, reason DebugEventReason) bool
- func (dbg *Debugger) SetBreakpoints(target BreakpointTarget, requests ...BreakpointRequest) []Breakpoint
- func (dbg *Debugger) Step(id int, reason DebugEventReason) error
- func (dbg *Debugger) Terminate()
- func (dbg *Debugger) Wait() (reflect.Value, error)
- type Exports
- type Interpreter
- func (interp *Interpreter) Compile(src string) (*Program, error)
- func (interp *Interpreter) CompileAST(n ast.Node) (*Program, error)
- func (interp *Interpreter) CompilePath(path string) (*Program, error)
- func (interp *Interpreter) Debug(ctx context.Context, prog *Program, events func(*DebugEvent), ...) *Debugger
- 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) EvalPathWithContext(ctx context.Context, 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) Execute(p *Program) (res reflect.Value, err error)
- func (interp *Interpreter) ExecuteWithContext(ctx context.Context, p *Program) (res reflect.Value, err error)
- func (interp *Interpreter) FileSet() *token.FileSet
- func (interp *Interpreter) Globals() map[string]reflect.Value
- func (interp *Interpreter) ImportUsed()
- func (interp *Interpreter) REPL() (reflect.Value, error)
- func (interp *Interpreter) Symbols(importPath string) Exports
- func (interp *Interpreter) Use(values Exports) error
- type Options
- type Panic
- type Program
- Bugs
Examples ¶
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 ( // 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") )
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
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
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.
type Exports ¶
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 (*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.
WARNING: The node must have been parsed using interp.FileSet(). Results are unpredictable otherwise.
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 ¶
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) FileSet ¶ added in v0.12.0
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 ¶ added in v0.12.0
func (interp *Interpreter) Globals() map[string]reflect.Value
Globals returns a map of global variables and constants in the main package.
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.
Notes ¶
Bugs ¶
Support for recursive types is incomplete.
Support of types implementing multiple interfaces is incomplete.