yaegi

package module
v0.11.3 Latest Latest
Warning

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

Go to latest
Published: Apr 7, 2022 License: Apache-2.0 Imports: 0 Imported by: 2

README

Yaegi

release Build Status GoDoc Discourse status

Yaegi is Another Elegant Go Interpreter. It powers executable Go scripts and plugins, in embedded interpreters or interactive shells, on top of the Go runtime.

Features

  • Complete support of Go specification
  • Written in pure Go, using only the standard library
  • Simple interpreter API: New(), Eval(), Use()
  • Works everywhere Go works
  • All Go & runtime resources accessible from script (with control)
  • Security: unsafe and syscall packages neither used nor exported by default
  • Support Go 1.16 and Go 1.17 (the latest 2 major releases)

Install

Go package

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

Command-line executable

go get -u github.com/traefik/yaegi/cmd/yaegi

Note that you can use rlwrap (install with your favorite package manager), and alias the yaegi command in alias yaegi='rlwrap yaegi' in your ~/.bashrc, to have history and command line edition.

CI Integration

curl -sfL https://raw.githubusercontent.com/traefik/yaegi/master/install.sh | bash -s -- -b $GOPATH/bin v0.9.0

Usage

As an embedded interpreter

Create an interpreter with New(), run Go code with Eval():

package main

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

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

	i.Use(stdlib.Symbols)

	_, err := i.Eval(`import "fmt"`)
	if err != nil {
		panic(err)
	}

	_, err = i.Eval(`fmt.Println("Hello Yaegi")`)
	if err != nil {
		panic(err)
	}
}

Go Playground

As a dynamic extension framework

The following program is compiled ahead of time, except bar() which is interpreted, with the following steps:

  1. use of i.Eval(src) to evaluate the script in the context of interpreter
  2. use of v, err := i.Eval("foo.Bar") to get the symbol from the interpreter context, as a reflect.Value
  3. application of Interface() method and type assertion to convert v into bar, as if it was compiled
package main

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

const src = `package foo
func Bar(s string) string { return s + "-Foo" }`

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

	_, err := i.Eval(src)
	if err != nil {
		panic(err)
	}

	v, err := i.Eval("foo.Bar")
	if err != nil {
		panic(err)
	}

	bar := v.Interface().(func(string) string)

	r := bar("Kung")
	println(r)
}

Go Playground

As a command-line interpreter

The Yaegi command can run an interactive Read-Eval-Print-Loop:

$ yaegi
> 1 + 2
3
> import "fmt"
> fmt.Println("Hello World")
Hello World
>

Note that in interactive mode, all stdlib package are pre-imported, you can use them directly:

$ yaegi
> reflect.TypeOf(time.Date)
: func(int, time.Month, int, int, int, int, int, *time.Location) time.Time
>

Or interpret Go packages, directories or files, including itself:

$ yaegi -syscall -unsafe -unrestricted github.com/traefik/yaegi/cmd/yaegi
>

Or for Go scripting in the shebang line:

$ cat /tmp/test
#!/usr/bin/env yaegi
package main

import "fmt"

func main() {
	fmt.Println("test")
}
$ ls -la /tmp/test
-rwxr-xr-x 1 dow184 dow184 93 Jan  6 13:38 /tmp/test
$ /tmp/test
test

Documentation

Documentation about Yaegi commands and libraries can be found at usual godoc.org.

Limitations

Beside the known bugs which are supposed to be fixed in the short term, there are some limitations not planned to be addressed soon:

  • Assembly files (.s) are not supported.
  • Calling C code is not supported (no virtual "C" package).
  • Interfaces to be used from the pre-compiled code can not be added dynamically, as it is required to pre-compile interface wrappers.
  • Representation of types by reflect and printing values using %T may give different results between compiled mode and interpreted mode.
  • Interpreting computation intensive code is likely to remain significantly slower than in compiled mode.

Contributing

Contributing guide.

License

Apache 2.0.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
_test
c1
c2
ct
ct1
d1
d2
foo
m1
p1
cmd
yaegi
Yaegi interprets Go programs.
Yaegi interprets Go programs.
example
Package extract generates wrappers of package exported symbols.
Package extract generates wrappers of package exported symbols.
internal
cmd/extract
extract generates wrappers of stdlib package exported symbols.
extract generates wrappers of stdlib package exported symbols.
Package interp provides a complete Go interpreter.
Package interp provides a complete Go interpreter.
Package stdlib provides wrappers of standard library packages to be imported natively in Yaegi.
Package stdlib provides wrappers of standard library packages to be imported natively in Yaegi.
syscall
Package syscall provide wrapper of standard library syscall package for native import in Yaegi.
Package syscall provide wrapper of standard library syscall package for native import in Yaegi.
unrestricted
Package unrestricted provides the original version of standard library symbols which may cause the interpreter process to exit.
Package unrestricted provides the original version of standard library symbols which may cause the interpreter process to exit.
unsafe
Package unsafe provides wrapper of standard library unsafe package to be imported natively in Yaegi.
Package unsafe provides wrapper of standard library unsafe package to be imported natively in Yaegi.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL