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.

    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 Symbols = Exports{
    	// contains filtered or unexported fields
    }

      Symbols exposes interpreter values.

      Functions

      This section is empty.

      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.